Yayınlar API’si #

Bir yayın tek bir giden gönderimdir: bir kitle, bir açılış mesajı, bir kanal ve bir zamanlama. İsteğe bağlı olarak, gelen yanıtları ele alan Yapay Zeka Temsilcisini de adlandırır. Yayınlar API’si, bu gönderimleri kontrol paneli yerine kendi kodunuzdan oluşturmanıza, fiyatlandırmanıza, başlatmanıza ve izlemenize olanak tanır. Ürünün kendisi için Yayınlar kılavuzuna bakın.

• Temel URL — https://api.youraiconnector.com/v1
• Kimlik Doğrulama — API anahtarınız (bkz. Kimlik Doğrulama)
• Hatalar ve sayfalama — bkz. Hatalar ve Sayfalama

Aşağıdaki tüm örnekler cURL’de ?apiKey= sorgu biçimini ve JavaScript ile Python’da X-API-Key başlığını göstermektedir; her ikisi de her uç noktada çalışır.

API gezgininde. Bu sayfadaki her uç nokta, yayınlanmış OpenAPI spesifikasyonunda yer alır, böylece tam alanlarına göz atabilir ve API gezgininde canlı istekler çalıştırabilirsiniz.

Bir gönderim nasıl oluşturulur #

Bir yayın göndermek tek bir çağrı değil, dört çağrıdan oluşur:

1. Oluştur: Yayını kitlesi, kanalı ve zamanlaması ile oluşturun — Draft olarak başlar.
2. Açılış mesajını ayarlayın. WhatsApp Business’ta bu, onay için bir şablon göndermek (veya zaten onaylanmış olanı seçmek) anlamına gelir. Diğer tüm kanallarda bu düz metindir.
3. Maliyeti tahmin edin: Herhangi bir harcama yapmadan önce fiyatı kontrol etmek isterseniz (isteğe bağlı).
4. Başlatın. Başlatma işlemi tam bir kontrol gerçekleştirir — kitle, mesaj, şablon onayı, bağlı gönderici — ve ya gönderimi başlatır ya da tam olarak neyin eksik olduğunu size söyler.

Siz başlatma çağrısı yapana kadar hiçbir şey gönderilmez.

Yayın nesnesi #

{
  "id": "bcd123abc456",
  "name": "June promo",
  "status": "Draft",
  "channel": "whatsapp",
  "agent_id": "agt_789",
  "list_id": "lst_456",
  "list_name": "Newsletter subscribers",
  "total_contacts": 240,
  "send_to_new_list_members": false,
  "whats_app_template": {
    "body": "Hi {{first_name}}, our June offer is live.",
    "status": "approved",
    "sid": "HX0123...",
    "language": "en",
    "category": "marketing",
    "variables": ["first_name"]
  },
  "execution_date": 1781000000000,
  "drip_mode": true,
  "time_critical": false,
  "total_contacts_sent": 0,
  "credits_used": 0,
  "created_at": 1780900000000,
  "last_modified_at": 1780900000000
}

Zaman damgaları epoch milisaniyeleri olarak geri döner (execution_date, created_at, last_modified_at, …) ve herhangi bir kişi referansı contacts/uid_whatsapp_15551234567 gibi bir yol dizisi olarak geri döner.

Ayarladığınız alanlar #

user_id, id, status veya source_campaign_id olarak gönderdiğiniz her şey oluşturma sırasında yoksayılır ve güncelleme sırasında düşürülür — durum yalnızca aşağıdaki başlatma, duraklatma ve devam ettirme uç noktaları aracılığıyla değişir.

Platformun yönettiği alanlar #

status, total_contacts_sent, unique_contacts_replied, overall_reply_rate, credits_used, paused_reason, completion_summary, grup sayaçları ve contacts (kontrol panelinden eklenen ve yol dizeleri olarak okunan bireysel kişiler). Bunları okuyun, yazmayın.

Durumlar #

Yayın oluştur #

POST /broadcasts — bir Draft oluşturur.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "June promo",
    "channel": "whatsapp",
    "list_id": "lst_456",
    "agent_id": "agt_789",
    "drip_mode": true,
    "execution_date": "2026-06-15T09:00:00.000Z"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "June promo",
    channel: "whatsapp",
    list_id: "lst_456",
    agent_id: "agt_789",
    drip_mode: true,
    execution_date: "2026-06-15T09:00:00.000Z",
  }),
});
const { broadcast_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "June promo",
        "channel": "whatsapp",
        "list_id": "lst_456",
        "agent_id": "agt_789",
        "drip_mode": True,
        "execution_date": "2026-06-15T09:00:00.000Z",
    },
)
print(res.json()["broadcast_id"])

Yanıt (201)

{ "success": true, "broadcast_id": "bcd123abc456" }

Yayınları listele #

GET /broadcasts — hesaptaki her yayın, en yeniden eskiye doğru.

Sorgu parametreleri

curl "https://api.youraiconnector.com/v1/broadcasts?apiKey=YOUR_API_KEY&status=Sending"

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts?status=Sending", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const { broadcasts } = await res.json();

res = requests.get(
    "https://api.youraiconnector.com/v1/broadcasts",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"status": "Sending"},
)
broadcasts = res.json()["broadcasts"]

Yanıt (200)

{ "success": true, "broadcasts": [{ "id": "bcd123abc456", "name": "June promo", "status": "Sending", "...": "..." }] }

Yayın al #

GET /broadcasts/{broadcastId} — { "success": true, "broadcast": { ... } } döndürür. Devam eden bir gönderimi sorgulamak için kullanın: total_contacts_sent, unique_contacts_replied, overall_reply_rate ve credits_used ilerledikçe güncellenir.

curl "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Hesabınızda bulunmayan bir yayın 404 döndürür.

Yayın güncelle #

PUT /broadcasts/{broadcastId} — yalnızca değiştirmek istediğiniz alanları gönderin. Ayrıca iç içe geçmiş bir nesnenin içindeki tek bir anahtarı noktalı yol ile belirtebilirsiniz, örn. "whats_app_template.body".

curl -X PUT "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "June promo (v2)", "execution_date": "2026-06-16T09:00:00.000Z" }'

await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456", {
  method: "PUT",
  headers: { "X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "June promo (v2)", execution_date: "2026-06-16T09:00:00.000Z" }),
});

Boş bir gövde 400 döndürür. Bilinmesi gereken iki kural:

• opener_media ya hep ya hiçtir. Nesnenin tamamını gönderin veya eki kaldırmak için null kullanın. İçine noktalı bir yol (opener_media.name) ile erişim, 400 ile reddedilir, çünkü kısmen güncellenmiş bir ek, orada olmayan bir dosyayı tanımlayacaktır.
• Durum düzenlenemez. başlat, duraklat ve devam ettir işlemlerini kullanın.

Açılış mesajı #

Her yayın, açılış mesajını whats_app_template içinde taşır. Bunun ne anlama geldiği kanala göre değişir:

• WhatsApp Business — WhatsApp tarafından onaylanmış bir şablon olmalıdır. Aşağıdaki iki uç noktadan birini kullanın.
• Diğer tüm kanallar (WhatsApp Web, SMS, Instagram, Messenger, Telegram, …) — aynı alanın body değeri, gönderilen metnin ta kendisidir. Bunu aşağıdaki uç nokta aracılığıyla göndermek, mesajı kaydeder ve WhatsApp’ı hiç dahil etmeden hazır olarak işaretler.

Onay için şablon gönderin #

POST /broadcasts/{broadcastId}/template

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, our June offer is live until Friday.",
    "language": "en",
    "category": "marketing"
  }'

Yanıt (200)

{ "success": true, "broadcast_id": "bcd123abc456", "template_status": "pending", "template_sid": "HX0123..." }

template_status, WhatsApp’ın belirttiği durumdur: incelenirken pending, kullanılabilir olduğunda approved, reddedildiyse rejected. WhatsApp dışı bir kanalda ise doğrudan template_sid: null ile approved olarak döner — incelenecek bir şey yoktur.

Sizi durduracak durumlar:

• Önceki bir şablon hala incelemedeyken gönderim yapmak 400 hatasını döndürür. Önce kararı bekleyin.
• Halihazırda onaylanmış bir şablonu düzenlemek, yeni şablon gelene kadar onaylı olanı yayında tutar, böylece devam eden bir yayın açılış mesajını asla kaybetmez.
• Doğrudan Meta üzerinden bağlanan bir WhatsApp numarasında, görsel veya video ekli bir yayın gönderilemez (400) — ekler, yönetilen WhatsApp Business hattında ve WhatsApp Web’de desteklenir.

Daha önce onaylanmış bir şablonu kullanın #

POST /broadcasts/{broadcastId}/template/select — şablon kitaplığınızdaki halihazırda onaylanmış bir şablonu yayına kopyalar, böylece beklenecek bir şey kalmaz.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/template/select?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "template_id": "tpl_abc123" }'

Yanıt (200)

{
  "success": true,
  "broadcast_id": "bcd123abc456",
  "template_status": "approved",
  "template_sid": "HX0123...",
  "body": "Hi {{first_name}}, our June offer is live until Friday.",
  "name": "june_promo",
  "language": "en",
  "variables": ["first_name"],
  "category": "marketing"
}

Onay, kitaplık kaydından tarafımızca doğrulanır — siz sadece kimliği gönderirsiniz. Yayın bir WhatsApp taslağı değilse, şablon onaylı değilse, şablon bir açılış mesajı yerine takip mesajıysa veya yayında bir ek varsa (kitaplık şablonları sadece metindir) 400 alırsınız. Hesabınızda bulunmayan bir şablon kimliği 404 döndürür.

Maliyeti tahmin edin #

POST /broadcasts/{broadcastId}/estimate-cost — gönderimi onaylamadan önce fiyatlandırır. whatsapp ve sms yayınlarında kullanılabilir; diğer kanallar 400 döndürür. Tahmin kitle sayısını hesapladığı için yayının bir list_id değerine ihtiyacı vardır.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/estimate-cost?apiKey=YOUR_API_KEY"

WhatsApp yanıtı (200) — hedef ülkeye göre dökümü alınmış krediler:

{
  "success": true,
  "channel": "whatsapp",
  "billing_mode": "credits",
  "data": {
    "countries": [
      { "countryCode": "31", "name": "Netherlands", "iso": "NL", "flag": "🇳🇱", "contactCount": 180, "costPerContact": 1.2, "subtotal": 216 },
      { "countryCode": "1", "name": "United States", "iso": "US", "flag": "🇺🇸", "contactCount": 60, "costPerContact": 0.9, "subtotal": 54 }
    ],
    "totalContacts": 240,
    "totalTemplateCost": 270,
    "templateCategory": "marketing",
    "billing_mode": "credits",
    "service_messages_billable_soon": false
  }
}

SMS yanıtı (200) — Kendi Twilio hesabınız için güncel Twilio fiyatlandırmasına dayalı ABD doları cinsinden:

{
  "success": true,
  "channel": "sms",
  "billing_mode": "twilio_direct",
  "data": {
    "totalContacts": 240,
    "messageLength": 118,
    "segmentsPerMessage": 1,
    "totalSegments": 240,
    "estimatedCostUsd": 1.788,
    "priceUnit": "USD",
    "billedByTwilio": true,
    "billing_mode": "twilio_direct",
    "service_messages_billable_soon": false
  }
}

Bir numara göstermeden önce billing_mode kısmını okuyun. Size kimin faturalandırıldığını söyler:

Bağlı Twilio kimlik bilgisi olmayan SMS’ler yine de segment sayılarını estimatedCostUsd: 0 ile döndürür — bakılacak bir fiyatlandırma yoktur.

Bir yayın başlatın #

POST /broadcasts/{broadcastId}/launch

Başlatma işlemi önce her şeyi kontrol eder ve ancak o zaman yayını ilerletir. Kısmi başlatma yoktur: ya başlar ya da hiçbir şey değişmez ve nedenini belirten bir hata alırsınız.

cURL

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();
if (!data.success) console.error(data.error);

Python

res = requests.post(
    "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/launch",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
print(res.json())

Yanıt (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Scheduled" }

status, yayının ulaştığı yerdir:

• Scheduled — execution_date gelecekte.
• Sending — şu anda başladı.
• Pending Approval — WhatsApp şablonu hala inceleme aşamasında. Şablon onaylanır onaylanmaz kendi kendine gönderilir; başlatmayı tekrar çağırmayın.

Yalnızca bir Draft (veya şablonu o zamandan beri onaylanmış bir Pending Approval yayını) başlatılabilir — başka herhangi bir şey 400 döndürür.

Bir başlatma neden reddedilir #

Bunların her biri, sade bir dille yazılmış bir error mesajı ile 400 olarak geri döner:

Duraklat ve devam ettir #

POST /broadcasts/{broadcastId}/pause, bir Sending veya Scheduled yayınını durdurur ve kuyruğa alınan her şeyi iptal eder.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/pause?apiKey=YOUR_API_KEY"

Bir Pending Approval yayınını duraklatmak, onu tekrar Draft durumuna getirir; henüz hiçbir şey planlanmadığı için devam ettirilecek bir şey yoktur. Diğer tüm durumlar 400 sonucunu döndürür.

POST /broadcasts/{broadcastId}/resume bir Paused yayınını yeniden başlatır:

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/resume?apiKey=YOUR_API_KEY"

Yanıt (200)

{ "success": true, "broadcast_id": "bcd123abc456" }

Sending durumuna veya execution_date değeri hala gelecekteyse tekrar Scheduled durumuna devam eder. Sadece Paused durumundaki bir yayın devam ettirilebilir.

Düşük etkileşimli bir duraklamadan sonra gönderime devam etme #

POST /broadcasts/{broadcastId}/override-engagement-guard

Bir yayın toplu olarak gönderilirken, bir sonrakine başlamadan önce her bir gruba kaç kişinin yanıt verdiğini ölçeriz. Neredeyse kimse yanıt vermiyorsa, yayın kendini duraklatır; sessizliğe doğru zorlamaya devam eden bir gönderim, bir numaranın filtrelenmesinin veya engellenmesinin en hızlı yoludur. Bu, kontrol panelindeki Yine de devam et düğmesidir.

Duraklamaya neden olan yanıt oranı yayın durdurulduğunda değişemeyeceğinden, basit bir devam ettirme işlemi bir sonraki kontrolde tekrar duraklatılacaktır. Bu uç nokta, yine de devam etme kararıdır: bu yayındaki geçersiz kılma işlemini kaydeder ve yayın düşük etkileşim nedeniyle duraklatılmışsa, aynı çağrıda duraklamayı kaldırır.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/override-engagement-guard?apiKey=YOUR_API_KEY"

Yanıt (200)

{ "success": true, "broadcast_id": "bcd123abc456", "status": "Sending", "resumed": true }

• resumed: true — yayın düşük etkileşim nedeniyle duraklatılmıştı ve şimdi tekrar çalışıyor; status, devam ettiği durumdur.
• resumed: false — hiçbir şey kaldırılmadı, geçersiz kılma işlemi sadece gelecekteki kontroller için kaydedildi. Bu, yayın hiç duraklatılmadıysa veya farklı bir nedenle duraklatıldıysa (elle duraklattıysanız, bir gönderim sınırına ulaşıldıysa veya çok fazla gönderim hatası oluştuysa) alacağınız sonuçtur. Bu tür duraklamalar burada kaldırılmaz; nedeni çözdükten sonra kendiniz devam ettirin.

Geçersiz kılma işlemi sadece bu yayın için geçerlidir. Bu bir hesap ayarı değildir ve iki kez çağrılması güvenlidir.

Bir yayını kopyalama #

POST /broadcasts/{broadcastId}/duplicate — hedef kitleyi, mesajı ve ayarları yeni bir Draft içine kopyalar. Önceki çalışmaya dair her şey (sayaçlar, gruplar, zamanlama, yanıt istatistikleri) sıfırdan başlar.

curl -X POST "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456/duplicate?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "to_channel": "sms" }'

Yanıt (201)

{ "success": true, "broadcast_id": "bcd999new111", "source_broadcast_id": "bcd123abc456" }

Bir kopya, canlı bir WhatsApp onayını asla devralmaz: bir WhatsApp kopyasında şablon onayınızı gerektirecek şekilde aktarılır ve başka bir kanala kopyalandığında şablon kaldırılır ve metin düz bir açılış mesajı haline gelir. SMS’e kopyalamak da herhangi bir eki kaldırır, çünkü SMS ek gönderemez.

Bir yayını silme #

DELETE /broadcasts/{broadcastId}

curl -X DELETE "https://api.youraiconnector.com/v1/broadcasts/bcd123abc456?apiKey=YOUR_API_KEY"

Bir Sending veya Scheduled yayını 400 ile reddedilir — önce duraklatın.

Klasik bir kampanyayı yansıtan yayınlar #

Mesaj gönderen klasik kampanyalar Yayınlar’da da görünür ve API bunları yerel yayınlarla birlikte döndürür (bir source_campaign_id taşırlar). Kampanya kontrolü elinde tutmaya devam ettiği için biraz farklı davranırlar:

• Düzenleme: Hedef kitle, mesaj veya zamanlama üzerinde yapılan değişiklikler çalışır ve kampanyaya işlenir.
• Kanal, yanıt Aracısı, ek ve tüm çalıştırma sayaçları burada salt okunurdur — değiştirmeye çalışırsanız 400 alırsınız. Bunları kampanya üzerinden değiştirin.
• Başlatma, sizi kampanya düzenleyiciye yönlendiren bir 400 döndürür.
• Duraklatma ve devam ettirme çalışır ve kampanya üzerinde işlem yapar.
• Silme, 400 döndürür — bunun yerine kampanyayı silin, Yayınlar girişi de onunla birlikte silinecektir.
• Çoğaltma, kanıtlanmış bir kampanyayı taşımanın desteklenen yolu olan bağımsız bir yerel yayın oluşturur.

Hatalar #

Başarısız istekler şu durum kodlarıyla {"success": false, "error": "<message>"} döndürür:

Sonraki adımlar #

• Yayınlar kılavuzu — hızlandırma ve güvenlik davranışı dahil olmak üzere bu uç noktaların arkasındaki ürün
• Kişiler API’si — yayının gönderileceği listeyi oluşturun
• Şablonlar API’si — seçebileceğiniz onaylı WhatsApp şablonlarını yönetin
• Webhooks API’si — yoklama yapmak yerine Broadcast Started ve Broadcast Completed için abone olun