Yayın API'si - Eazybe

Genel Bakış

Bu belge, istemcilerin Meta WABA ile ilgili yayın işlemleri için Eazybe’nin Genel Yayın API’sini nasıl kullanabileceğini açıklar. API şunları destekler:

API anahtarı oluşturma
Tek alıcı şablon yayınları
Toplu şablon yayınları
Sağlık kontrolleri
İşlemsel hata işleme

API, HTTPS üzerinden JSON istekleri kullanır ve x-api-key başlığı aracılığıyla kimlik doğrular. Eazybe platformu üzerinden onaylanmış WhatsApp şablon tabanlı giden mesajlaşma için tasarlanmıştır.

Temel Yapılandırma

Ayar	Değer
Temel URL	`https://cerberus.eazybe.com/prod/api/v2`
Kimlik Doğrulama	`x-api-key` başlığı
Content-Type	`application/json`
Desteklenen İşlemler	Anahtar oluştur, tek yayın gönder, toplu yayın gönder, sağlık kontrolü

Başlamadan Önce

Gönderen telefon numarasının Eazybe’de zaten entegre edildiğinden ve aktif bir WABA kurulumuna bağlı olduğundan emin olun. Gönderilen numara için WABA hesabı bulunamazsa API anahtarı oluşturma başarısız olur.

Göndermeye çalışmadan önce gerekli WhatsApp şablonlarının Meta’da onaylandığını doğrulayın. Onaylanmamış veya eksik şablonlar istek hataları döndürür.

Kimlik Doğrulama Akışı

API Anahtarı Oluştur

Kayıtlı bir gönderen numarası için bu uç noktayı bir kez kullanın ve dönen API anahtarını gelecekteki istekler için güvenli bir şekilde saklayın.

Uç Nokta

POST /broadcast/public/generate-key

İstek Gövdesi

Alan	Tür	Zorunlu	Açıklama
`phoneNumber`	string	Evet	Ülke kodu içeren gönderen telefon numarası, boşluk veya `+` olmadan

Örnek İstek

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/generate-key \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "919876543210"
  }'

Başarılı Yanıt

{
  "status": true,
  "status_code": 200,
  "message": "API key generated successfully",
  "data": {
    "apiKey": "15558044483"
  }
}

Hata Örneği

{
  "status": false,
  "status_code": 400,
  "message": "User is not signed up yet.",
  "data": {
    "error": {
      "message": "No WABA account found for this phone number"
    }
  }
}

API Anahtarını İstek Başlıklarında Kullanın

Tüm yayın uç noktaları, oluşturulan API anahtarını x-api-key başlığında gerektirir.

x-api-key: YOUR_API_KEY

API anahtarınızı güvenli bir şekilde saklayın. Gereksiz yere yeniden oluşturmaktan kaçının.

Tek Yayın Gönderin

Tek bir şablon mesajını bir alıcıya göndermek için tek yayın uç noktasını kullanın.

Uç Nokta

POST /broadcast/public/send-single

Gerekli İstek Yapısı

Alan	Tür	Zorunlu	Açıklama
`templateName`	string	Evet	Onaylanmış WhatsApp şablon adı
`templateLanguage`	string	Evet	Şablon dil kodu (ör., `en`)
`templateType`	string	Evet	Şablon kategorisi: `MARKETING`, `UTILITY` veya `AUTHENTICATION`
`countryCode`	string	Evet	`+` olmadan alıcı ülke kodu
`toPhoneNumber`	string	Evet	Alıcı mobil numarası
`templateId`	string	Hayır	Meta şablon kimliği
`templateParams`	string[]	Hayır	Sırayla şablon değişken değerleri
`broadcastName`	string	Hayır	Bu gönderim için isteğe bağlı etiket

Örnek İstek

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-single \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "templateName": "christmas_template",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "768465685803110",
    "countryCode": "91",
    "toPhoneNumber": "8077378155",
    "templateParams": ["John", "100"],
    "broadcastName": "Single Broadcast Test"
  }'

Başarılı Yanıt

{
  "status": true,
  "message": "Single broadcast queued successfully",
  "data": {
    "broadcastId": "6789abcdef123456",
    "campaign_id": "abc123xyz456",
    "status": "PENDING_SEND"
  }
}

Yaygın Hata Yanıtları

Toplu Yayın Gönderin

Aynı onaylanmış şablonu tek bir istekte birden fazla alıcıya göndermek için toplu uç noktayı kullanın. Tek bir istek 1000 alıcıya kadar içerebilir.

Uç Nokta

POST /broadcast/public/send-bulk

Gerekli İstek Yapısı

Alan	Tür	Zorunlu	Açıklama
`broadcastName`	string	Evet	Benzersiz kampanya adı
`templateName`	string	Evet	Onaylanmış WhatsApp şablon adı
`templateLanguage`	string	Evet	Şablon dil kodu
`templateType`	string	Evet	Şablon kategorisi
`data`	array	Evet	Alıcı listesi, istek başına maksimum 1000
`templateId`	string	Hayır	Meta şablon kimliği
`globalTemplateParams`	string[]	Hayır	Alıcı düzeyinde parametreler sağlanmadığında kullanılan varsayılan değişkenler

`data` İçindeki Alıcı Nesnesi

Alan	Tür	Zorunlu	Açıklama
`countryCode`	string	Evet	`+` olmadan alıcı ülke kodu
`toPhoneNumber`	string	Evet	Alıcı mobil numarası
`templateParams`	string[]	Hayır	Genel değerleri geçersiz kılan alıcı düzeyinde değişkenler

Örnek İstek

curl -X POST https://cerberus.eazybe.com/prod/api/v2/broadcast/public/send-bulk \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "broadcastName": "Festival Kampanyası 2024",
    "templateName": "festive_offer_promo",
    "templateLanguage": "en",
    "templateType": "MARKETING",
    "templateId": "1172528374418691",
    "data": [
      {
        "countryCode": "91",
        "toPhoneNumber": "9897964421",
        "templateParams": ["John Doe", "212812790", "16-02-2026"]
      },
      {
        "countryCode": "91",
        "toPhoneNumber": "8077378155",
        "templateParams": ["Vineet", "122878278", "14-02-2026"]
      }
    ],
    "globalTemplateParams": ["Varsayılan Şirket", "Test tarihi"]
  }'

Başarılı Yanıt

{
  "status": true,
  "message": "Broadcast is being processed",
  "data": {
    "total_contacts": 2,
    "failed_contacts": 0,
    "estimated_cost": 0.15,
    "oldBalance": 100.5,
    "newEstimatedBalance": 100.35
  }
}

İşlemsel Notlar

Toplu bir istek 1000 alıcıyı aşamaz.
Yayın adları benzersiz olmalıdır, aksi takdirde istek başarısız olur.

Geçersiz numaralar kısmi başarısızlıklar oluşturabilir. Başarısız kontaklar ayrı olarak sayılır ve bu geçersiz kontaklar için kredi düşülmez. Başarısız kontaklar aşağı akış takibi için failure_reason_code: “INVALID_PHONE_NUMBER” ile saklanabilir.

Şablon Parametre İşleme

API hem alıcı düzeyinde hem de genel parametreleri destekler.

Alıcı Düzeyinde Parametreler

Her kontakın farklı değişken değerleri alması gerektiğinde her alıcı nesnesi içinde templateParams kullanın. Örnek kullanım durumları:

Müşteri başına sipariş kimliği
Müşteri başına randevu saati
Alıcı başına kişiselleştirilmiş ad

Genel Parametreler

Bir toplu kampanyadaki tüm alıcılara aynı değişken değerleri uygulandığında globalTemplateParams kullanın. Bu, tekrarlanan yük verilerini azaltır ve marka adı, kupon kodu veya teklif yüzdesi gibi ortam genelindeki ortak değerler için kullanışlıdır.

Öncelik Kuralı

Alıcı düzeyinde templateParams sağlandığında, bu alıcı için genel değerleri geçersiz kılar.

Sağlık Kontrolü

Genel Yayın API hizmetinin operasyonel olup olmadığını doğrulamak için sağlık uç noktasını kullanın.

Uç Nokta

GET /broadcast/public/health

Örnek İstek

curl -X GET https://cerberus.eazybe.com/prod/api/v2/broadcast/public/health

Örnek Yanıt

{
  "status": "ok",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "Public Broadcast API",
  "version": "1.0.0",
  "endpoints": {
    "single": "POST /broadcast/public/send-single",
    "bulk-standard": "POST /broadcast/public/send-bulk-standard",
    "health": "GET /broadcast/public/health"
  }
}

Hata İşleme Referansı

Durum Kodu	Hata	Anlamı
`400`	`User is not signed up yet`	API anahtarı geçersiz veya telefon numarası kayıtlı değil
`400`	`No subscriptions available`	Yayınlar için aktif bir abonelik mevcut değil
`400`	`Insufficient credits`	Cüzdan bakiyesi yeterli değil
`400`	`Template does not exist`	Şablon eksik veya onaylanmamış
`400`	`Invalid template language`	İstenen şablon dil varyasyonu onaylanmamış
`400`	`Invalid phone number format`	Ülke kodu veya telefon biçimi geçersiz
`400`	`Pricing not available`	Hedef ülke kodu için gönderim desteklenmiyor
`400`	`Recipient limit exceeded`	Toplu istek 1000’den fazla alıcı içeriyor
`400`	`Broadcast with same name exists`	Kampanya adı benzersiz olmalı
`500`	`Internal Server Error`	Beklenmeyen sunucu tarafı hata

Hata Nedeni Kodları

Kod	Anlamı	Notlar
`INVALID_PHONE_NUMBER`	Geçersiz alıcı numarası	Ülke kodu ve numara biçimini kontrol edin
`UNSUPPORTED_COUNTRY_CODE`	Ülke fiyatlandırması mevcut değil	Hedef desteklenmiyor
`TEMPLATE_SEND_FAILED`	Şablon gönderimi başarısız oldu	Ham API hata yanıtını inceleyin
`131014`	Geçersiz parametre	Şablon parametre sorunu
`131051`	Hız sınırı aşıldı	Kısa bir süre içinde çok fazla istek gönderildi
`WORKER_ERROR`	İşçi işleme hatası	İşçi hata yanıtını inceleyin

Hız Sınırları ve Platform Kısıtlamaları

Meta’nın WABA başına saniyede yaklaşık 30 mesaj gönderim oranı vardır. API, 429, 80007 ve 130429 gibi hız sınırlama hataları için otomatik yeniden deneme ve üstel geri çekme içerir.

İstek başına 1000 alıcı sınırına yaklaştığınızda, büyük yüklemeleri birden fazla istek için sorumlu bir şekilde bölün ve bölün.

İstemciler için Önerilen İş Akışı

Entegre Edin ve Doğrulayın

Herhangi bir API kullanımından önce gönderen numarasını Eazybe’de entegre edin ve doğrulayın.

API Anahtarı Oluşturun

API anahtarını bir kez oluşturun ve güvenli bir şekilde saklayın.

Şablonları Doğrulayın

WhatsApp şablonunun Meta’da onaylandığından ve dil varyasyonunun mevcut olduğundan emin olun.

Verileri Doğrulayın

Göndermeden önce alıcı ülke kodlarını, telefon numaralarını ve şablon değişken sayısını doğrulayın.

Yayın Gönderin

Tek seferlik testler için tek uç noktayı, kampanyalar için toplu uç noktayı kullanın.

Yanıtı İzleyin

failed_contacts, bakiye değişiklikleri ve kuyruk durumu için yanıtı izleyin.

Benzersiz Adlar Kullanın

Her kampanya için benzersiz yayın adları kullanın.

En İyi Uygulamalar

API anahtarını güvenli bir şekilde saklayın ve gereksiz yere yeniden oluşturmaktan kaçının
Başarısızlıkları ve operasyonel temizliği azaltmak için numaraları önceden doğrulayın
Şablon değişken sayısını onaylanmış şablon yer tutucularıyla tam olarak eşleştirin
Paylaşılan değerler için globalTemplateParams kullanın ve kişiselleştirme gerekmediğinde sadece alıcı düzeyinde parametreler kullanın
Büyük yayın isteklerinden önce kredileri kontrol edin
Tam hacimli kampanyalar göndermeden önce küçük bir test toplu işle başlayın

Örnek Yük Desenleri

Değişkenli Tek Gönderim

{
  "templateName": "order_shipped",
  "templateLanguage": "en",
  "templateType": "MARKETING",
  "countryCode": "91",
  "toPhoneNumber": "9876543210",
  "templateParams": ["John", "ORD12345", "17-02-2024"]
}

Alıcı Düzeyinde Değişkenlerle Toplu Gönderim

{
  "broadcastName": "Randevu Hatırlatmaları",
  "templateName": "appointment_reminder",
  "templateLanguage": "en",
  "templateType": "UTILITY",
  "data": [
    {
      "countryCode": "1",
      "toPhoneNumber": "5551234567",
      "templateParams": ["Alice", "2024-01-20", "10:00 AM"]
    },
    {
      "countryCode": "1",
      "toPhoneNumber": "5559876543",
      "templateParams": ["Bob", "2024-01-20", "2:30 PM"]
    }
  ]
}

Genel Değişkenlerle Toplu Gönderim

{
  "broadcastName": "Küresel Promosyon",
  "templateName": "promo_offer",
  "templateLanguage": "en",
  "templateType": "MARKETING",
  "data": [
    {
      "countryCode": "91",
      "toPhoneNumber": "9876543210"
    },
    {
      "countryCode": "91",
      "toPhoneNumber": "9876543211"
    }
  ],
  "globalTemplateParams": ["Mağazam", "SAVE20", "20"]
}

Overview

Endpoints

​Genel Bakış

​Temel Yapılandırma

​Başlamadan Önce

​Kimlik Doğrulama Akışı

​API Anahtarı Oluştur

​Uç Nokta

​İstek Gövdesi

​Örnek İstek

​Başarılı Yanıt

​Hata Örneği

​API Anahtarını İstek Başlıklarında Kullanın

​Tek Yayın Gönderin

​Uç Nokta

​Gerekli İstek Yapısı

​Örnek İstek

​Başarılı Yanıt

​Yaygın Hata Yanıtları

​Toplu Yayın Gönderin

​Uç Nokta

​Gerekli İstek Yapısı

​data İçindeki Alıcı Nesnesi

​Örnek İstek

​Başarılı Yanıt

​İşlemsel Notlar

​Şablon Parametre İşleme

​Alıcı Düzeyinde Parametreler

​Genel Parametreler

​Öncelik Kuralı

​Sağlık Kontrolü

​Uç Nokta

​Örnek İstek

​Örnek Yanıt

​Hata İşleme Referansı

​Hata Nedeni Kodları

​Hız Sınırları ve Platform Kısıtlamaları

​İstemciler için Önerilen İş Akışı

​Entegre Edin ve Doğrulayın

​API Anahtarı Oluşturun

​Şablonları Doğrulayın

​Verileri Doğrulayın

​Yayın Gönderin

​Yanıtı İzleyin

​Benzersiz Adlar Kullanın

​En İyi Uygulamalar

​Örnek Yük Desenleri

​Değişkenli Tek Gönderim

​Alıcı Düzeyinde Değişkenlerle Toplu Gönderim

​Genel Değişkenlerle Toplu Gönderim

Genel Bakış

Temel Yapılandırma

Başlamadan Önce

Kimlik Doğrulama Akışı

API Anahtarı Oluştur

Uç Nokta

İstek Gövdesi

Örnek İstek

Başarılı Yanıt

Hata Örneği

API Anahtarını İstek Başlıklarında Kullanın

Tek Yayın Gönderin

Uç Nokta

Gerekli İstek Yapısı

Örnek İstek

Başarılı Yanıt

Yaygın Hata Yanıtları

Toplu Yayın Gönderin

Uç Nokta

Gerekli İstek Yapısı

`data` İçindeki Alıcı Nesnesi

Örnek İstek

Başarılı Yanıt

İşlemsel Notlar

Şablon Parametre İşleme

Alıcı Düzeyinde Parametreler

Genel Parametreler

Öncelik Kuralı

Sağlık Kontrolü

Uç Nokta

Örnek İstek

Örnek Yanıt

Hata İşleme Referansı

Hata Nedeni Kodları

Hız Sınırları ve Platform Kısıtlamaları

İstemciler için Önerilen İş Akışı

Entegre Edin ve Doğrulayın

API Anahtarı Oluşturun

Şablonları Doğrulayın

Verileri Doğrulayın

Yayın Gönderin

Yanıtı İzleyin

Benzersiz Adlar Kullanın

En İyi Uygulamalar

Örnek Yük Desenleri

Değişkenli Tek Gönderim

Alıcı Düzeyinde Değişkenlerle Toplu Gönderim

Genel Değişkenlerle Toplu Gönderim