WhatsApp Şablonları API’si #

WhatsApp mesaj şablonları, normal 24 saatlik konuşma penceresinin dışında gönderilmek üzere onaylanmış, önceden yazılmış mesajlardır; örneğin bir hoş geldin mesajı, randevu hatırlatıcısı veya yeniden etkileşim dürtmesi gibi. Bu API, şablonları programatik olarak listelemenize, oluşturmanıza, düzenlemenize, göndermenize, kontrol etmenize, silmenize ve iletmenize olanak tanır.

Aşağıdaki tüm yollar, API temel URL’sine göre belirlenmiştir:

https://api.youraiconnector.com/v1

Her istek kimlik doğrulamasına tabidir. Kabul edilen dört yöntem için Kimlik Doğrulama bölümüne bakın. Bu sayfadaki örnekler X-API-Key başlığını (ve cURL için bir sorgu parametresi biçimini) kullanır.

Alt hesaplarla çalışma (ajanslar) #

Onay durumları #

Açık bir konuşma dışında gönderilen mesajların önce WhatsApp tarafından incelenmesi gerektiğinden, her şablon bir onay status taşır:

Yalnızca draft ve rejected durumundaki şablonlar düzenlenebilir veya (yeniden) gönderilebilir. Bir şablon approved olduğunda kilitlenir; değişiklik yapmanız gerekirse yeni bir tane oluşturun.

Otomatik onay: Bazı kanallar harici bir inceleme adımı gerektirmez. Böyle bir kanalda kampanya için oluşturulan veya gönderilen şablonlar, içerik kimliği (sid) olmadan doğrudan approved olarak kaydedilir.

Meta bağlantılı hesaplarda şablonlar #

Bu uç noktalar, hesabınızın hangi WhatsApp bağlantısı üzerinde çalıştığına bakılmaksızın aynı şekilde çalışır, ancak arka planda gerçekleşen işlemler farklılık gösterir:

• Yönetilen bir WhatsApp bağlantısında, şablonlar mesajlaşma sağlayıcısına kaydedilir ve sid, sağlayıcının içerik kimliğidir (HXXXXXXXX…).
• Numarası kendi WhatsApp İşletme Hesabı üzerinde çalışan bir hesapta (her iki Meta bağlantı seçeneği için de), şablonlar o WhatsApp İşletme Hesabı içinde oluşturulur ve incelenir; sid ise Meta’nın kendi şablon kimliğidir — "3394843740694756" gibi sayısal bir dize. status yukarıdaki tablodaki değerleri kullanmaya devam eder ve rejection_reason, Meta’nın açıklamasını taşımaya devam eder.

Bunun için iki ek uç nokta mevcuttur: hangi bağlantıda olduğunuzu sorgulamak için bir tane ve şablon listenizi WhatsApp İşletme Hesabınızla eşitlemek için bir tane. WhatsApp İşletme Hesabı’nda zaten var olan şablonlar, eşitleme işlemiyle kitaplığınıza aktarılır, böylece daha sonra yapılan bir GET /whatsapp-templates çağrısı bunları diğer tüm şablonlar gibi listeler.

Şablonların hangi bağlantıda çalıştığını kontrol etme #

GET /whatsapp-templates/provider

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/provider?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/provider", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/provider",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "provider": "meta",
  "lane": "meta_cloud_api",
  "waba_id": "2357661648036355",
  "templates_enabled": true
}

Meta’dan şablonları eşitleme #

WhatsApp İşletme Hesabınızda bulunan her şablonun onay durumunu yeniler ve orada var olup henüz kitaplığınızda bulunmayan tüm şablonları içe aktarır. İstediğiniz sıklıkta çağırmak güvenlidir. Yönetilen bir bağlantıda eşitlenecek bir şey yoktur, bu nedenle çağrı hiçbir işlem yapmaz ve yalnızca kaç şablonunuz olduğunu bildirir.

POST /whatsapp-templates/meta-sync

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/meta-sync",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "provider": "meta",
  "imported": 2,
  "updated": 5,
  "total": 12
}

Meta ile doğrudan iletişim (gelişmiş) #

Yukarıdaki uç noktaların sağlamadığı bir şeye (şablon üst bilgileri, alt bilgileri, düğmeler veya tamamen elle oluşturulmuş bir şablon) ihtiyacınız varsa, /v1/meta-templates isteğinizi şablon kitaplığınızda hiçbir şey saklamadan doğrudan Meta’nın kendi şablon API’sine iletir. Bu yalnızca numarası kendi WhatsApp İşletme Hesabı üzerinde çalışan hesaplarda çalışır; yönetilen bir bağlantıda her çağrı, önce bir Meta uygulaması bağlamanızı isteyen bir 400 döndürür.

Meta tarafından reddedilen bir şablon, error içinde Meta’nın kendi açıklamasıyla birlikte 400 döndürür.

Şablonları listele #

Hesabınızdaki tüm şablonları, her birinin kısa bir özetiyle birlikte döndürür.

GET /whatsapp-templates

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": [
    {
      "id": "template_abc123",
      "name": "welcome_message",
      "status": "approved",
      "language": "en",
      "body": "Hi {{first_name}}, thanks for reaching out!"
    },
    {
      "id": "template_def456",
      "name": "appointment_reminder",
      "status": "pending",
      "language": "en",
      "body": "Hi {{first_name}}, this is a reminder about your appointment."
    }
  ]
}

Bir şablonu al #

Değişkenleri, durumu ve zaman damgaları dahil olmak üzere tek bir şablonun tüm ayrıntılarını döndürür.

GET /whatsapp-templates/{templateId}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "template": {
    "id": "template_abc123",
    "name": "welcome_message",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "language": "en",
    "variables": ["first_name"],
    "status": "approved",
    "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "type": "general",
    "category": "marketing",
    "rejection_reason": null,
    "campaign_id": "campaign123",
    "date_created": "2026-06-01T10:00:00.000Z",
    "date_updated": "2026-06-02T08:30:00.000Z",
    "submitted_at": "2026-06-01T10:05:00.000Z",
    "approved_at": "2026-06-02T08:30:00.000Z"
  }
}

Hesabınızda bulunmayan bir şablon, { "success": false, "error": "Template not found" } ile birlikte 404 döndürür.

Bir şablon oluşturun #

Bir kampanyanın açılış mesajı için bir şablon oluşturur ve bunu tek adımda onay için gönderir.

POST /whatsapp-templates

Değişken yer tutucuları {{first_name}}, {first_name} veya [first_name] olarak yazılabilir; bunların hepsi çift süslü parantez biçimine normalleştirilir.

Sonuç, kampanyanın kanallarına bağlıdır:

• WhatsApp Business API kampanyası: içerik WhatsApp incelemesine gönderilir. Yanıt campaign_status (received veya pending) ve bir template_sid içerir.
• Harici inceleme adımı olmayan bir kanal: şablon saklanır ve otomatik olarak onaylanır (campaign_status: "approved", template_sid: null).
• Kampanyada WhatsApp kanalı yok: hiçbir şey oluşturulmaz ve campaign_status değeri not_applicable olur.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Yanıt (inceleme için gönderildi)

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Bağımsız bir şablon oluşturma #

Bir kampanyanın açılış mesajına bağlamadan şablon kitaplığınızda bir şablon oluşturur. Bu, bu sayfanın geri kalanının izlediği yaşam döngüsünün oluşturma adımıdır: burada oluşturun, düzenleyin, incelemeye gönderin, durumunu sorgulayın ve artık ihtiyacınız kalmadığında silin.

POST /whatsapp-templates/docs

Kimlik doğrulama (tek kullanımlık kod) şablonları. WhatsApp, serbest metinli kimlik doğrulama şablonlarını kabul etmez: mesaj gövdesi WhatsApp tarafından önceden belirlenmiştir ve şablon bir “kodu kopyala” düğmesi içermelidir. category: "authentication" ile bir şablon oluşturduğunuzda, bunu sizin için bu sabit biçimde göndeririz. body öğeniz uygulamada gösterilen önizleme olarak tutulur, ancak kişinizin aldığı metin WhatsApp’ın kendi ifadeleridir (kod, bir güvenlik hatırlatıcısı ve 10 dakikalık geçerlilik süresi notu). Tam olarak bir değişken tanımlayın, örneğin ["code"], ve gönderim yaparken kodu iletin (bkz. Bir kişiye şablon gönder üzerindeki variables alanı). Kod 15 karakterden kısa olmalıdır.

Hangi oluşturma yöntemini kullanmalıyım? Kendiniz düzenleyip gönderebileceğiniz bir şablon istediğinizde bunu kullanın. Bir kampanyanın açılış mesajını ayarlamak istediğinizde POST /whatsapp-templates (yukarıda) kullanın; bu yöntem campaign_id gerektirir ve doğrudan kampanyaya yazar.

submitted olarak oluşturulan bir şablon, arka planda WhatsApp incelemesine gönderilir, bu nedenle yanıtın içinde beklemek yerine sonuç için durum uç noktasını kontrol edin.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/docs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"],
    "status": "draft",
    "category": "marketing"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/docs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
    status: "draft",
    category: "marketing",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/docs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
        "status": "draft",
        "category": "marketing",
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "template_id": "template_abc123",
  "status": "draft"
}

Eksik bir name, language veya body, desteklenmeyen bir dil, draft veya submitted dışındaki bir status, bilinmeyen bir type veya category ya da 1024 karakterden uzun bir gövde, açıklayıcı bir error ile birlikte 400 döndürür. Kampanyalarınızdan biri olmayan bir campaign_id, 404 döndürür.

Bir şablonu güncelleyin #

Henüz onaylanmamış bir şablonu düzenler. Yalnızca draft veya rejected durumundaki şablonlar düzenlenebilir. name, body, language ve variables değerlerinin herhangi bir kombinasyonunu sağlayın; yalnızca gönderdiğiniz alanlar değiştirilir.

PUT /whatsapp-templates/{templateId}

Düzenleme, şablonu inceleme için yeniden göndermez. Daha sonra gönderim uç noktasını kullanın.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Hi {{first_name}}, here is an update for you.",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      body: "Hi {{first_name}}, here is an update for you.",
      variables: ["first_name"],
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "body": "Hi {{first_name}}, here is an update for you.",
        "variables": ["first_name"],
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "template_id": "template_abc123"
}

Zaten approved olan (veya başka bir şekilde düzenlenemeyen) bir şablonu düzenlemeye çalışmak, hiçbir alan göndermemek veya geçersiz bir değer göndermek, açıklayıcı bir error ile birlikte 400 döndürür.

Onay için şablon gönderin #

Bir draft veya rejected şablonunu inceleme için gönderir. Harici inceleme gerektirmeyen bir kanaldaki şablonlar anında onaylanır; diğer tüm şablonlar WhatsApp’a gönderilir ve döndürülen status (genellikle received veya pending) şablon üzerinde saklanır.

POST /whatsapp-templates/{templateId}/submit

Takip şablonları, gönderilmeden önce gerekli değişkenlerini bildirmeli ve kullanmalıdır: bir ad yer tutucusu ve akıllı takip mesajları için kişisel bağlam yer tutucusu.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/submit",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "template_id": "template_abc123",
  "status": "pending",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}

Onay durumunu kontrol edin #

Bir şablonun mevcut durumunu sorgulamak için hafif bir uç nokta. Durum, arka planda periyodik olarak yenilenen kayıtlı kayıttan okunur, bu nedenle çok yeni bir onay veya reddin görünmesi kısa bir süre alabilir.

GET /whatsapp-templates/{templateId}/status

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

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

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/status",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "template_id": "template_abc123",
  "name": "welcome_message",
  "status": "approved",
  "sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "rejection_reason": null,
  "date_updated": "2026-06-02T08:30:00.000Z"
}

Şablonu silin #

Şablon kaydını hesabınızdan kaldırır.

DELETE /whatsapp-templates/{templateId}

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "template_id": "template_abc123",
  "note": "The template record was removed from your account. Content already approved by WhatsApp may remain registered with the messaging provider."
}

Bir kişiye şablon gönderin #

Açık bir konuşma olmasa bile bir kişiye onaylanmış bir şablon gönderir; bu işlem sohbet oturumunu yeniden başlatır. Kişiyi contactId veya phoneNumber ile hedefleyebilir ve şablonu whatsappTemplateId veya templateName ile seçebilirsiniz.

POST /whatsapp-templates/send

Şablonun gövdesi gelişmiş değişken değiştirmeyi destekler:

• Temel değişkenler: {{first_name}}, {{email}}, {{company}}
• Varsayılan değerler: {{first_name|there}}, alan boşsa there gösterir
• Dönüşümler: {{company|uppercase}}, {{name|lowercase}}, {{name|capitalize}}
• Birleştirilmiş: {{company|Your Company|uppercase}}

Krediler: Şablon göndermek kredi tüketir. Tam maliyet, alıcının ülkesine ve şablonun kategorisine bağlıdır.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "contact123",
    "whatsappTemplateId": "template_abc123"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/send", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    contactId: "contact123",
    whatsappTemplateId: "template_abc123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "contactId": "contact123",
        "whatsappTemplateId": "template_abc123",
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Hem kişi tanımlayıcısı hem de şablon tanımlayıcılarından yoksun bir istek 400 döndürür. Hesabınızda gönderim için gereken mesajlaşma kimlik bilgileri eksikse, yanıt 403 olur.

Bir kampanyanın canlı şablonunu oluşturun veya güncelleyin #

Bir kampanyanın açılış şablonu için, gövdedeki bir campaign_id yerine yol (path) ile kapsamlandırılmış ikinci bir uç nokta çifti. Bunlar, halihazırda canlı olan bir kampanya için kullanılacak olanlardır: yukarıdaki Şablon oluştur seçeneğinin aksine, burada güncelleme yapmak kampanyanın takip taslaklarını da inceleme için yeniden gönderir, böylece açılış şablonu ve takip mesajları senkronize kalır.

POST /whatsapp-templates/campaign/{campaignId}, kampanyanın açılış şablonunu oluşturur. PUT /whatsapp-templates/campaign/{campaignId} ise şablonu düzenler; kampanyanın halihazırda bir şablona sahip olması gerekir, aksi takdirde bu işlem 400 döndürür.

cURL (oluştur)

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "welcome_message",
    "language": "en",
    "body": "Hi {{first_name}}, thanks for reaching out!",
    "variables": ["first_name"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "welcome_message",
    language: "en",
    body: "Hi {{first_name}}, thanks for reaching out!",
    variables: ["first_name"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/campaign/campaign123",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "welcome_message",
        "language": "en",
        "body": "Hi {{first_name}}, thanks for reaching out!",
        "variables": ["first_name"],
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "campaign_status": "pending",
  "template_sid": "HXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "message": "WhatsApp template created and campaign updated successfully."
}

Düzenlemek için yöntemi PUT ile değiştirin ve aynı alanları kullanın; bu işlem açılış şablonunu (ve WhatsApp API kampanyasında kampanyanın takip taslaklarını) inceleme için yeniden gönderir.

Hesabınıza ait olmayan bir kampanya 404 döndürür; yetkili olmadığınız başka bir hesaba ait bir kampanya ise 403 döndürür. Mevcut bir şablonu olmayan bir kampanyayı düzenlemek 400 döndürür.

Mevcut bir kişiye şablon gönderin #

Yukarıdaki Bir kişiye şablon gönder seçeneğine göre daha basit, yol (path) ile kapsamlandırılmış bir alternatif: hem şablon hem de kişi halihazırda mevcut olmalıdır; isimle arama yapılmaz veya anında oluşturulmaz.

POST /whatsapp-templates/{templateId}/send-to-contact

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactId": "contact123" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactId: "contact123" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/send-to-contact",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactId": "contact123"},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "WhatsApp template message sent successfully"
}

Krediler: Gönderim, yukarıdaki uç nokta ile aynı şekilde fiyatlandırılan kredileri tüketir. Eksik olan veya hesabınızda bulunmayan bir contactId, 403 döndürür; mevcut olmayan bir templateId ise 404 döndürür.

Toplu şablon gönderimi #

Tek bir çağrıda birçok kişiye tek bir şablon gönderin; onaylamadan önce gösterebileceğiniz bir maliyet önizlemesi ile birlikte.

Önce maliyeti tahmin edin #

Hiçbir şey göndermeden veya kredi harcamadan, hedef ülkeye göre dökümü alınmış şekilde gönderim maliyetini döndürür. Şablon fiyatlandırması hedef ülke başına yapıldığından, bunun istemci tarafında tahmin edilmek yerine gerçek kişiler üzerinden sunucu tarafında hesaplanması gerekir.

POST /whatsapp-templates/{templateId}/estimate-bulk-cost

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/estimate-bulk-cost",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": {
    "countries": [
      {
        "countryCode": "1",
        "name": "United States",
        "iso": "US",
        "flag": "🇺🇸",
        "contactCount": 120,
        "costPerContact": 0.5,
        "subtotal": 60.0
      }
    ],
    "totalContacts": 120,
    "totalTemplateCost": 60.0,
    "templateCategory": "marketing",
    "skippedContacts": 2
  }
}

skippedContacts, eksik olan, size ait olmayan veya telefon numarası bulunmayan kimlikleri sayar; tahmin yalnızca geri kalanını kapsar, bu nedenle sıfır olmayan bir değer, gerçek gönderimin seçtiğinizden daha az kişiye ulaşacağı anlamına gelir.

Toplu gönderim yapın #

Şablonu listedeki her kişiye gönderir, kişi bazlı akıllı değişkenleri çözer ve gönderim başına kredi düşer.

POST /whatsapp-templates/{templateId}/bulk-send

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "contactIds": ["contact123", "contact456"] }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ contactIds: ["contact123", "contact456"] }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/template_abc123/bulk-send",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"contactIds": ["contact123", "contact456"]},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": { "sent": 118, "failed": 2, "total": 120 }
}

Başarısız olan bir kişi (bulunamadı, hesabınızda değil veya gönderim hatası) atlanır ve toplu işlemi durdurmak yerine failed içinde sayılır. Boş bir contactIds, gönderim başına 5000’den fazla kimlik (tahmin için 500) veya eksik bir templateId, 400 döndürür.

Başarısız bir mesajı yeniden deneyin #

Yeni bir mesaj kaydı oluşturmadan veya tekrar kredi harcamadan, başarısız olan bir mesajı yeniden göndermek için iki uç nokta.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry-template, özellikle başarısız olan bir şablon mesajını yeniden dener; başarısız mesajda zaten mevcut değilse, kampanya içeriğindeki şablon içeriğini yeniden çözer. Yalnızca failed durumuna ve template türüne sahip mesajlar bu şekilde yeniden denenebilir.

POST /whatsapp-templates/messages/{contactId}/{messageId}/retry kanaldan bağımsızdır ve herhangi bir başarısız şablon dışı mesaj (örneğin WhatsApp Web) için çalışır; mesajın kanalına göre doğru gönderim yoluna yönlendirir. failed, failed_connection, limit_exceeded veya queued_retry durumlarını kabul eder.

Uç noktaların hiçbiri istek gövdesi almaz.

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/messages/contact123/msg_abc789/retry-template",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "Message retry initiated successfully"
}

Kanaldan bağımsız sürüm için yolu .../msg_abc789/retry ile değiştirin. Durumu yeniden denemeye uygun olmayan veya (şablon uç noktasında) şablon mesajı olmayan bir mesaj 400 döndürür. Eksik bir kişi veya mesaj 404 döndürür.

WhatsApp Business profili #

WhatsApp’ta kişilere gösterilen WhatsApp Business profilini (hakkında, adres, açıklama, e-posta, web siteleri, işletme kategorisi ve logo) yönetin. Hem yönetilen bir bağlantıda hem de kendi WhatsApp Business Hesabını çalıştıran bir hesapta çalışır.

Profili kaydet #

PUT /whatsapp-templates/profile

cURL

curl -X PUT "https://api.youraiconnector.com/v1/whatsapp-templates/profile?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "about": "We reply within a few hours",
    "email": "support@example.com",
    "websites": ["https://example.com"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    about: "We reply within a few hours",
    email: "support@example.com",
    websites: ["https://example.com"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "about": "We reply within a few hours",
        "email": "support@example.com",
        "websites": ["https://example.com"],
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "WhatsApp Business profile updated successfully"
}

Eksik bir phoneNumber, geçersiz bir web sitesi URL’si veya hesabınızda bağlı olmayan bir phoneNumber, 400 veya 404 döndürür.

Profil resmi yükle #

Sağladığınız bir URL’den bir resim indirir ve onu WhatsApp’a yükleyerek bir tanıtıcı (handle) döndürür. Fotoğraf olarak ayarlamak için bu tanıtıcıyı yukarıdaki profili kaydet çağrısında profilePictureHandle olarak iletin; bu uç nokta yalnızca resmi yükler, tek başına ayarlamaz.

POST /whatsapp-templates/profile/picture

cURL

curl -X POST "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+31612345678",
    "fileUrl": "https://example.com/logo.png"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phoneNumber: "+31612345678",
    fileUrl: "https://example.com/logo.png",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/whatsapp-templates/profile/picture",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "phoneNumber": "+31612345678",
        "fileUrl": "https://example.com/logo.png",
    },
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "1234567890123456"
}

data, yüklenen resmin tanıtıcısıdır. Eksik bir phoneNumber veya fileUrl ya da dosyada WhatsApp erişim belirteci olmayan bir phoneNumber, 400 döndürür; ulaşılamayan veya geçersiz bir fileUrl, indirmenin neden başarısız olduğunu açıklayan bir hata döndürür.

Gönderen durumunu kontrol et #

Bağlı bir WhatsApp numarasının mesajlaşma sağlayıcısındaki canlı gönderim durumunu sorgular (ve yeniler). Bir numaraya güvenmeden önce gerçekten gönderim yapabildiğini doğrulamak için kullanışlıdır.

GET /whatsapp-templates/sender-status/{phoneNumber}

cURL

curl "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678" \
  -H "X-API-Key: YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/whatsapp-templates/sender-status/+31612345678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Yanıt

{
  "success": true,
  "data": "ONLINE"
}

data; ONLINE (normal gönderim), PENDING (hala doğrulanıyor) veya DELETED (sağlayıcı artık bu göndereni tanımıyor — numarayı yeniden bağlayın) değerlerinden biridir. Dosyada WhatsApp işletme bilgisi olmayan bir phoneNumber, 404 döndürür.

Yapay zeka ile takip şablonları oluşturun #

Platform, bir kampanya sessizleştiğinde gönderilen hatırlatmalar olan WhatsApp takip şablonlarını, kampanyanın kendi talimatlarından ve hedefinden yola çıkarak sizin için yazabilir. Arka planda çalışan bir iş uç noktası ve mevcut entegrasyonlar için tutulan üç eski uç nokta bulunmaktadır. Hepsi yapay zeka kredilerini kullanır.

Bir oluşturma işi başlatın #

POST /campaigns/{campaignId}/template-generation

cURL

curl -X POST "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "all" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ type: "all" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/campaigns/campaign_abc123/template-generation",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"type": "all"},
)
data = res.json()

Yanıt (202)

{ "success": true, "campaign_id": "campaign_abc123", "type": "all" }

Çağrı, iş sıraya alınır alınmaz geri döner. Kampanyayı okuyun (GET /campaigns/{campaignId}, bkz. Kampanyalar API) ve bitene kadar template_generation_status nesnesini izleyin:

Oluşturulan şablonlar, diğerleri gibi kampanyaya eklenir, bu nedenle Şablonları listele kısmında görünürler ve gönderilmeden önce WhatsApp onayından geçmeleri gerekir. 400, type değerinin all veya cold_only dışında bir şey olduğu anlamına gelir; 404 ise kampanyanın mevcut olmadığı veya başka bir hesaba ait olduğu anlamına gelir.

Temsilcilerin bu çağrının bir ikizi olan POST /agents/{agentId}/template-generation uç noktası vardır; bu, bir Temsilci için takip mesajlarını yazar ve normal durumda çağrı sırasında tamamlanır — bkz. Takip mesajları oluşturma, Yapay Zeka Temsilcileri API’sinde.

Eski oluşturma uç noktaları #

Daha önceki üç uç nokta aynı işi yapar ve mevcut entegrasyonların çalışmaya devam etmesi için tutulur. Yeni kodlar yukarıdaki iş uç noktasını kullanmalıdır.

Her üçü de hesapta otomatik takiplerin açık olmasını ve yeterli kredinin bulunmasını gerektirir — 400 hangisinin eksik olduğunu belirtir — ve kampanya adresli çift, kampanya başka bir hesaba ait olduğunda 403 döndürür.

Şablonlar API hataları #

Şablon uç noktaları standart hata zarfını döndürür:

{
  "success": false,
  "error": "Template not found"
}

Bu uç noktalardaki bir 404, genellikle kaynağın bulunamadığı anlamına gelir; ya kaynak mevcut değildir ya da başka bir hesaba aittir. Birkaç uç nokta (kampanya kapsamlı oluşturma/güncelleme ve mevcut bir kişiye gönderimler), kampanya veya kişi mevcut olmamak yerine başkasına ait olduğunda bunun yerine 403 döndürür. Bazı uç noktalar ayrıca HTTP durumunu yansıtan bir error_code alanı da içerir. Her uç noktanın döndürebileceği ortak kodlar — 400, 401, 403 (planınız API erişimini içermiyor), 429 (hız sınırı) ve 500 — yeniden deneme rehberliği ile birlikte Hatalar ve Sayfalandırma bölümünde listelenmiştir.

Sonraki adımlar #

• Kimlik Doğrulama — bir isteğin kimliğini doğrulamak için dört yol.
• Hatalar ve Hız Sınırları — durum kodları ve 300 istek/dakika sınırı.
• Kampanyalar API — şablonların eklendiği kampanyaları yönetin.