WhatsApp API Medya: Desteklenen Dosya Türleri ve Boyut Limitleri

Medyayı yüklemeli miyim, bağlantı mı göndermeliyim?

Meta, dosyayı yükleyip medya kimliğini göndermenizi önerir. Alternatif olarak herkese açık bir sunucudaki dosyaya bağlantı gönderebilirsiniz; ancak Meta'nın görsel, video ve belge referansları daha iyi performans için yüklenen kimliği tercih etmenizi söyler, verim (throughput) rehberi de yüksek hacimler için aynısını söyler.

Meta'nın kendi uç noktasında yükleme, dosya, MIME türü ve messaging_product=whatsapp ile /<PHONE_NUMBER_ID>/media adresine bir POST'tur; yanıt {"id": "<MEDIA_ID>"} olur. Yüklenen dosyalar şifrelenir ve siz daha önce silmediğiniz sürece 30 gün saklanır.

OmniChannels.ai WhatsApp uç noktasında bir medya mesajı mediaUrl (herkese açık bir HTTPS URL'si) veya mediaFile (istekle birlikte yüklediğiniz bir dosya) alır; alt yazı content içinde gider. WhatsApp API belgelerine bakın. Büyük gönderimlerde hesabınızın medya depolamayı ve yeniden kullanımı nasıl yönettiğini ekibimize sorun.

Medya kimlikleri ne kadar süre geçerli kalır?

Meta, yüklemeden dönen kimlik için 30 gün, gelen bir webhook'ta alınan kimlik için 7 gün belirtir. Bir kimlik için dönen indirme URL'si 5 dakika sonra geçersiz olur.

Pratik sonuçlar:

• Bir medya kimliğini aylarca önbelleğe almayın. Orijinal dosyanızı saklayın ve kimlik reddedildiğinde yeniden yükleyin.
• Gelen dosyaları olay geldiği anda indirin ve kendi kopyanızı tutun.
• Alınan bir indirme URL'sini asla saklamayın; ihtiyaç duyduğunuzda yenisini isteyin.

Medya mesajlarına alt yazı ekleyebilir miyim?

Evet. Görsel, video ve belge mesajları, Meta'nın mesaj referanslarına göre 1.024 karaktere kadar isteğe bağlı bir alt yazı kabul eder. Alt yazılar dosyanın yanındaki düz metindir.

Bu modelde ses ve çıkartma mesajlarının alt yazısı yoktur. Sesli mesajla birlikte söz istiyorsanız yanına kısa bir metin mesajı gönderin. Müşteri hizmetleri penceresi içinde alt yazılar serbest biçimlidir; dışında medyanın onaylı bir şablonun içinde gitmesi gerekir.

Mesaj şablonlarında medya nasıl çalışır?

Bir şablonun başlığında görsel, video veya belge olabilir ve bu başlık şablonu oluştururken sabitlenir. Şablonu onaya gönderirken bir örnek dosya sağlarsınız ve gönderim sırasında gerçek dosyayı verebilirsiniz.

API'mizde headerFormat, oluşturma sırasında IMAGE, VIDEO veya DOCUMENT olabilir, headerFile örneği taşır ve gönderim anındaki mediaUrl başlık medyasını değiştirir. Örnek dosya gereksinimleri için Meta'nın şablon belgelerine bakın. Şablon kategorileri ve onay ile şablon örnekleri yazılarına göz atın.

Müşterinin gönderdiği medyayı nasıl indiririm?

Gelen medya, bir medya kimliğiyle bir webhook olarak gelir; onu bir URL'ye çözer ve yetkilendirmeyle indirirsiniz.

1. Medya kimliğini gelen mesaj olayından okuyun.
2. O kimlik için medya URL'sini isteyin. Meta'nın yanıtı url, mime_type, sha256 ve file_size alanlarını içerir.
3. O URL'ye Authorization: Bearer <token> başlığıyla bir GET gönderin. Token olmadan istek başarısız olur.
4. Content-Type başlığını ve sha256 değerini kontrol edin, sonra dosyayı saklayın.
5. 404 alırsanız yeni bir URL isteyip yeniden deneyin; yine başarısız olursa erişim token'ını yenileyin.

Meta'nın Cloud API'deki maksimum gelen medya boyutu 100 MB'dır. Daha büyük bir dosya, 131052 hata koduyla bir webhook tetikler; müşteriden daha küçük bir dosya göndermesini veya başka yolla paylaşmasını isteyin. Her dosyayı kurum içinde açmadan önce tarayın. Webhook rehberine bakın ve gelen medyanın hesabınızda nasıl iletildiğini devreye alma mühendisinizle teyit edin.

Uygulamalı örnek: rapor gönderen bir diş kliniği

Kahire'deki "Nile Smile Clinic" (kurgusal) randevu kartları ve röntgen raporları gönderir.

1. Randevu kartları, iki satırlık alt yazıyla 300 KB'lık PNG görsellerdir. 5 MB'ın çok altında.
2. Tedavi raporları 2 ila 8 MB'lık, report-2026-0381.pdf adlı PDF'lerdir ve belge olarak gönderilir.
3. 25 MB'lık bir klinik tanıtım videosu video limiti için çok büyüktür. Ekip onu faststart ile 16 MB'ın altında H.264/AAC MP4 olarak yeniden kodlar.
4. Hastalar reçete fotoğrafları gönderir. Gelen kutusu her dosyayı hemen indirir, çünkü gelen kimlik 7 gün sonra geçersiz olur.
5. Sesli karşılama mesajı mono Opus OGG olarak dışa aktarılır, çünkü diğer OGG türleri reddedilir.

Yaygın hatalar nelerdir?

• Yalnızca boyuta bakmak. Yanlış renk biçimli 3 MB'lık bir görsel veya yanlış kodekli bir video yine başarısız olur.
• MIME uyuşmazlığı. application/octet-stream olarak sunulan bir .jpg, 131053 hatasının klasik nedenidir.
• Yavaş veya özel bir URL'ye bağlantı vermek; süresi dolmuş imzalı bir bağlantı ya da oturum açma arkasındaki bir sayfa gibi.
• Eski bir medya kimliğine güvenmek. Kimliklerin süresi 30 gün sonra dolar.
• Gelen kimliğin geçerlilik süresini göz ardı etmek. Müşteri dosyaları 7 gün içinde kaydedilmelidir.
• Animasyonlu WebP'yi görsel olarak göndermek. Reddedilir; çıkartma veya video kullanın.
• Limitler değişir. Doğrulamayı koda gömmeden önce Meta'nın referansını yeniden kontrol edin.

OmniChannels.ai nasıl yardımcı olur?

OmniChannels.ai, WhatsApp görsel, video, ses, belge ve çıkartma mesajlarını tek bir API üzerinden, herkese açık bir bağlantı veya yüklenmiş bir dosya ile alt yazı kullanarak gönderir ve medya ile ekleri paylaşılan gelen kutusunda gösterir. BroadNet resmi bir Meta Business Solution Provider'dır; bu yüzden görsel, video veya belge başlıklı şablonlar oluşturulabilir ve onay durumuyla izlenebilir. WhatsApp API belgelerini ve hatalar ile limitler sayfasını okuyun ya da WhatsApp kanalına göz atın.