Skip to main content

Genel Bakış

Genel Yayın API’si, harici sistemlerin kuruluşunuza ait WhatsApp Business numaralarına erişmesini sağlar. Her istek API anahtarıyla tek bir kuruluş kapsamında değerlendirilir ve kullanılan tüm WABA numaraları bu kuruluşa ait olmalıdır. /broadcast/public altında iki uç nokta grubu bulunur:
  • v2 uç noktaları: kuruluş kimlik doğrulama anahtarını kullanır ve bu sayfada belgelenir.
  • Eski uç noktalar: numara başına kullanılan eski WABA anahtarıyla çalışmaya devam eder ve değiştirilmemiştir. Eski uç noktalar bölümüne bakın.

Temel Yapılandırma

Başlamadan Önce

Anahtarı sunucu tarafında tutun. Bu anahtar, kuruluşunuzun tüm WhatsApp numaralarından gönderim yapılmasına izin verir. Anahtarı ortam değişkenlerinde veya bir gizli anahtar yöneticisinde saklayın; web ya da mobil koda eklemeyin.
Buradan başlayın. Kullanabileceğiniz WABA numaralarını görmek için Telefon numaralarını listele bölümünü, şablonun onaylı olduğunu doğrulamak için Şablonları listele bölümünü kullanın.

Kimlik Doğrulama Akışı

1

İstek Başlıklarında Kimlik Doğrulama Anahtarını Kullanın

Tüm yayın uç noktaları, oluşturulan kimlik doğrulama anahtarının x-api-key başlığında gönderilmesini gerektirir. Anahtarı Workspace → Staff bölümünde bulabilirsiniz.

API anahtarınızı güvenli bir şekilde saklayın. Gereksiz yere yeniden oluşturmayın.
Kuruluş kimlik doğrulama anahtarınızı Staff bölümünde bulun

Anahtar neyi çözüyor?

Anahtar kuruluşunuzu tanımlar. fromPhoneNumber veya phone_number alan uç noktalarda API ayrıca numaranın söz konusu kuruluşa kayıtlı olduğunu ve WABA kaydının tamamlandığını doğrular; waba_id, phone_number_id, phone_number ve access_token’in hepsinin mevcut olması gerekir. Bir uyumsuzluk 403’i değil, 401’i döndürür.

Uç nokta dizini


Telefon numaralarını listele

Kuruluşunuza kayıtlı tüm WhatsApp Business numaralarını listeler. Gönderilen uç noktalarında döndürülen phone_number’i fromPhoneNumber olarak kullanın.

Uç Nokta

İstek

Yanıt

200 — Telefon numaraları başarıyla getirildi
Boş bir data dizisi, anahtarın geçerli olduğu ancak kuruluşa henüz bağlı bir WABA numarası olmadığı anlamına gelir. Bu bir hata değil, yapılandırma durumudur.

Şablonları listele

Numaralarınızdan birinde mevcut olan onaylanmış WhatsApp şablonlarını döndürür. Bunu bir yayından önce çağırın; onaylanmamış veya yanlış yazılmış bir şablon adı göndermek tüm isteği başarısızlığa uğratır.

Uç Nokta

Sorgu parametreleri

İstek

Yanıt

200 — Şablonlar başarıyla getirildi
Gövdedeki {{n}} yer tutucularını sayın; bu, her bir alıcının templateParams dizisinin tam olarak sağlaması gereken değer sayısıdır.

Şablon yayınını gönder

Onaylanmış bir şablonu alıcı listesine gönderir. Liste boyutuna göre davranış değişiklikleri: 1.000 alıcıya kadar yayın eşzamanlı olarak kuyruğa alınır; bunun üzerinde parçalara bölünür ve durum için yoklama yaptığınız bir arka plan işi olarak işlenir.

Uç Nokta

Başlıklar

Gövde

Alıcı nesnesi

İstek

Bu örnekte ilk alıcı kendi değerlerini alır ve ikincisi globalTemplateParams’e geri döner.

Yanıtlar

200 — Sıraya alındı (1.000 alıcı veya daha az)
202 — Arka planda işleme için kabul edildi (1.000’den fazla alıcı)
jobId’i saklayın; yayının nasıl bittiğini kontrol etmenin tek yolu budur. Anket Bununla yayın durumunu alın. 400 — Alıcı sınırı aşıldı
400 — Şablon onaylanmadı
Yinelenen alıcılar reddedilir, birleştirilmez. Aynı countryCode + toPhoneNumber çifti iki kez görünürse, kopyanın dizinini adlandıran bir 400 ile isteğin tamamı başarısız olur. Göndermeden önce listenizi tekilleştirin.

Serbest biçimli mesaj gönder

Bir alıcıya tek bir mesaj gönderir. Sekiz içerik türünün tamamı bu uç noktayı paylaşır; type alanı diğer hangi alanların gerekli olduğuna karar verir.

Uç Nokta

Ortak alanlar

Türe özgü alanlar

Uzantı, dosyadan değil, URL yolundan okunur. .webp ile biten bir URL’den sunulan gerçek bir PNG, image için reddedilir ve hiçbir uzantısı olmayan bir URL, her medya türü için reddedilir. Sorgu dizeleri göz ardı edildiğinden …/photo.png?v=2 uygundur.

Metin

Resim

Belge

Ses

Video

Çıkartma

Konum

latitude ve longitude, dize değil, JSON numaraları olmalıdır. Enlem -90 ile 90 arası, boylam -180 ile 180 arası kabul edilir.

Etkileşimli — düğmeler

3’e kadar yanıtlama düğmesi. Üçten fazlası reddedilir.

Etkileşimli — liste

Bölüm başına değil, tüm bölümlerin toplamında 10’a kadar satır sayıldı.

Yanıt

200 — sekiz türün tümü için aynı şekil

Yayın durumunu al

202 ve jobId döndüren büyük bir yayın işinin ilerlemesini döndürür. 1.000 veya daha az alıcının olduğu yayınlar iş yaratmaz ve oylanacak hiçbir şey yoktur.

Uç Nokta

İstek

Yanıtlar

200 — iş kaydı artı parça ilerlemesinin özeti
404 — Yayın işi bulunamadı 401 — İş farklı bir kuruluşa ait Başka bir kuruluş tarafından oluşturulan bir iş, 404 yerine 401 değerini döndürür; iş kimlikleri kuruluşlar arasında numaralandırılamaz.

Sağlık kontrolü

Hizmetin çalışır durumda olduğunu doğrular ve şu anda sunduğu rotaları listeler. API anahtarına gerek yok.

Uç Nokta


Doğrulama kuralları

Bunlar, herhangi bir şey WhatsApp’a ulaşmadan önce çalışır, dolayısıyla buradaki reddetme mesaj kotasına neden olmaz. Her başarısızlık, message: "Validation error" ile 400’i ve belirli bir nedeni döndürür.

İstek sınırları

Limitler sabit 60 saniyelik bir pencerede sayılır. Çoğunun kapsamı API anahtarınız ve istekteki telefon numarasına göre belirlenir; dolayısıyla iki farklı gönderme numarası aynı bütçe için rekabet etmez.

Limitin aşılması

Mesaj size pencerede tam olarak kaç saniye kaldığını söyler. Hemen yeniden denemek yerine bu kadar bekleyin; hemen yeniden denemek hiçbir şey tüketmez ancak aynı hatayı döndürür.

Hata Yönetimi

Her hata aynı zarfı kullanır:

Durum kodları

Dört 401

Dördü de 401 değerini döndürür ancak farklı anlamlara gelir:
Yeniden deneme politikası. Üstel geri çekilme ile 500 ve 503’i yeniden deneyin. 400 veya 401’i hiçbir zaman yeniden denemeyin; aynı istek aynı şekilde başarısız olur. 429’te yanıtta belirtilen süre kadar bekleyin. Yeniden denemeyi düşündüğünüz isteklerde her zaman bir Idempotency-Key gönderin.

Eski uç noktalar

Farklı kimlik doğrulama. Bu üçü v2’den öncedir ve kuruluşunuzun auth_key’ini değil, hâlâ sayı başına eski WABA anahtarını kullanır. Bunlar değişmemiştir ve desteklenmeye devam etmektedir ancak yeni entegrasyonlar yukarıdaki v2 uç noktalarını kullanmalıdır.
Bir telefon numarası için eski bir API anahtarı oluşturur. Kuruluş kimliğini değil phoneNumber’i alır.
Bir şablon mesajı gönderir. Alıcı alanları data dizisi yerine en üst düzeyde bulunur.
Toplu şablon gönderimi, 1.000 alıcıyla sınırlıdır; parçalama ve iş kimliği yoktur. Sınırın aşılması, atan v2 uç noktasının aksine, yanıt gövdesinde bir HTTP 200 durum satırıyla 400’i döndürür.