Şablon mesajı gönderme

Bu rehber, CRM’inize veya yönetim panelinize bir “WhatsApp’tan gönder” düğmesi ekler. Düğme, bir telefon numarasına onaylı bir şablon gönderir. Numaranın Kai’de konuşması yoksa, gönderim konuşmayı açar. WhatsApp serbest metni yalnızca müşterinin son mesajından sonraki 24 saat içinde kabul eder. Bu pencerenin dışında ve ilk temasta, WhatsApp yalnızca Meta’nın onayladığı bir şablonu kabul eder. Bu Meta’nın kuralıdır, Kai’nin değil. Bu rehberdeki anahtarın messages:send yetkisine ihtiyacı vardır. Bu yetki templates:read ve conversations:read yetkilerini de kapsar.

1. Kanalı bulun

Kanal listesini bir kez okuyun ve WhatsApp kanalınızın kimliğini saklayın:

curl https://kaisupport.com/api/v1/channels \
  -H "Authorization: Bearer $KAI_API_KEY"

{
  "data": [
    {
      "id": "7c1f4a80-...",
      "kind": "whatsapp_cloud",
      "external_id": "104857923341",
      "enabled": true,
      "supports_templates": true,
      "created_at": "2026-05-11T09:00:00.000Z"
    }
  ]
}

Çalışma alanında tek bir WhatsApp kanalı varsa, sonraki adımlarda channel_id alanını atlayabilirsiniz. Kai kanalı sizin için bulur.

2. Şablonları ipuçlarıyla listeleyin

Kullanıcınız gönderim penceresini açtığında şablonları isteyin. Mesajı gönderen ekip arkadaşının e-posta adresini ve müşteriyi de ekleyin:

curl -G "https://kaisupport.com/api/v1/templates" \
  -H "Authorization: Bearer $KAI_API_KEY" \
  --data-urlencode "agent=baran@example.com" \
  --data-urlencode "phone=+905356328781" \
  --data-urlencode "contact_name=Gülsüm Bodur"

{
  "channel_id": "7c1f4a80-...",
  "agent": { "member_id": "2c9a0d51-...", "name": "Baran Demir", "email": "baran@example.com" },
  "contact": { "contact_id": "4f1d6f2a-...", "name": "Gülsüm Bodur" },
  "data": [
    {
      "name": "consultation_request_cant_be_reached_reschedule_tr",
      "language": "tr",
      "status": "approved",
      "header": "Derece Kampüsü · {{konu}}",
      "body": "Selamlar {{customer_name}} ben Derece Kampüsü'nden {{consultant_name}}, ön görüşme talep etmişsin ancak sana ulaşamadım.",
      "variables": ["header.konu", "customer_name", "consultant_name"],
      "variable_hints": [
        { "address": "header.konu", "key": "konu", "part": "header", "binding": "free", "value": null, "source": null },
        { "address": "customer_name", "key": "customer_name", "part": "body", "binding": "customer_name", "value": "Gülsüm Bodur", "source": "request" },
        { "address": "consultant_name", "key": "consultant_name", "part": "body", "binding": "agent_name", "value": "Baran Demir", "source": "member" }
      ],
      "sendable": true
    }
  ]
}

Yanıt yalnızca gönderebileceğiniz şablonları içerir. variables alanı, yer tutucuları gönderiminizin dolduracağı sırayla adlandırır.

Başlıklı şablonlar

Bir şablonun mesajın üstünde bir başlığı olabilir. WhatsApp başlığı ilk satırda kalın gösterir. header alanı başlığı taşır; şablonun başlığı yoksa null olur. Başlığın kendi değişkenleri olabilir ve Kai bunları doldurur. WhatsApp, başlığın ve mesajın değişkenlerini ayrı numaralar ve adlandırır; bu yüzden başlıktaki {{1}} ile mesajdaki {{1}} iki ayrı değerdir. Bu nedenle her değişkenin bir adresi vardır; gönderirken bu adı kullanırsınız:

Nerede	Yer tutucu	Adres
Mesaj	`{{customer_name}}`	`customer_name`
Başlık	`{{konu}}`	`header.konu`

variables alanı bu adresleri, gönderimin dolduracağı sırayla listeler: önce başlığın değişkenleri, sonra mesajın değişkenleri. Her ipucu ayrıca header veya body olan bir part alanı taşır; alanlarınızı buna göre gruplayabilirsiniz.

Kai, görsel, video veya belge başlığı olan bir şablonu gönderemez; çünkü o başlık bir değer değil bir dosya ister. Kai, bir düğmesinde değişken bağlantı olan şablonu da gönderemez. Bu şablonlar yanıtta yer almaz. Onları görmek için status=all ekleyin; orada sendable alanı false olur.

İpuçlarını kullanın

variable_hints içindeki her kayıt, bir alanı nasıl dolduracağınızı söyler:

null olmayan bir value, Kai’nin kullanacağı değerdir. Alanınızı bu değerle önden doldurun. Kullanıcınız göndermeden önce bunu değiştirebilir.
null olan bir value, Kai’nin bu değişkeni dolduramadığı anlamına gelir. Kullanıcınızdan bu değeri isteyin ve o yanıtlamadan göndermeyin.

binding alanı, değerin nereden geldiğini söyler. agent_name, agent alanındaki ekip arkadaşının profilini okur. customer_name kişiyi okur. free, her seferinde bir insanın yazdığı anlamına gelir. Çalışma alanı bir bağlamayı Ayarlar (Settings) → Kanallar (Channels) altında yapılandırır. Kimse yapılandırmadığında Kai bunu değişkenin adından tahmin eder; bu yüzden {{consultant_name}} ve {{customer_name}} kurulum olmadan çalışır. Hiçbir üyenin taşımadığı bir agent adresi, "agent": null ve boş ipuçları döndürür. Boş bir alanı incelerken bu alanı okuyun.

Kai gönderim anında hiçbir değişkeni doldurmaz. Gönderim bütün değerleri ister. Mesaj çıkmadan önce kişinin okuduğu şey sizin formunuzdur; bu ekranın ardından Kai’nin eklediği bir değeri kimse onaylamamış olur.

Kai, kanalın şablon kitaplığının bir kopyasını tutar. Şablon eklemek veya değiştirmek için Meta’nın WhatsApp Manager’ını kullanın, sonra Kai’de Ayarlar (Settings) → Kanallar (Channels) altında eşitleyin.

3. Şablonu gönderin

curl -X POST https://kaisupport.com/api/v1/conversations/outbound \
  -H "Authorization: Bearer $KAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-reachout-8842" \
  -d '{
    "to": { "phone": "+905356328781" },
    "contact": { "name": "Gülsüm Bodur" },
    "template": {
      "name": "consultation_request_cant_be_reached_reschedule_tr",
      "language": "tr",
      "variables": {
        "header.konu": "Ön görüşme",
        "customer_name": "Gülsüm Bodur",
        "consultant_name": "Baran Demir"
      }
    },
    "assignee": "baran@example.com",
    "opt_in_confirmed": true
  }'

Değerleri formunuzdan gönderin; form, ipuçlarını veya kullanıcınızın yaptığı değişiklikleri taşır. Her değişken zorunludur.

Değerler için iki biçim

Değişkenlerini adlandıran bir şablon, yukarıdaki gibi bir nesne kabul eder. Anahtarlar, 2. adımdaki adreslerdir. Kai değerleri şablonun sırasına koyar, yani bu sırayı bilmeniz gerekmez. Bütün değişkenlerini numaralayan bir şablon ({{1}}, {{2}}), 2. adımdaki variables alanının sırasıyla bir dizi kabul eder. Başlığın değerleri önce gelir:

"variables": ["Ön görüşme", "Gülsüm Bodur", "Baran Demir"]

Adlandırılmış bir şablon için de dizi çalışır. Ama o zaman değerleriniz şablonun sırasını izler ve birisi bu sırayı Meta’nın WhatsApp Manager’ında değiştirebilir. Yer değiştiren iki değer yine iki metindir, bu yüzden hiçbir şey hata vermez ve müşteri yanlış ismi okur. Adlandırılmış bir şablon için nesneyi kullanın. Kai, şablonun taşımadığı bir değişken adını reddeder ve hatada o adı belirtir. Yanlış yazılmış bir ad, atılacak bir değer değil, entegrasyonunuzdaki bir hatadır. Sade bir ad her zaman mesajın değişkenidir: başlığın bir değişkenini doldurmak için adın önüne header. yazmanız gerekir. Tek çağrı her şeyi yapar. Kai numaranın konuşmasını bulur veya oluşturur. Arkasındaki kişiyi bulur veya oluşturur. Şablonun başlığını ve gövdesini kendi kopyasından doldurur ve gönderir. Sonra konuşmayı assignee alanındaki ekip arkadaşına atar. Her çağrıda opt_in_confirmed alanını true yapmanız gerekir. Bu, kişinin sizden mesaj almayı kabul ettiğine dair sizin beyanınızdır. Kai bu beyanı mesajın üzerinde saklar.

{
  "data": {
    "conversation": {
      "id": "9d2b1c44-...",
      "status": "human",
      "assigned_member_id": "2c9a0d51-...",
      "assigned_via": "api",
      "contact_id": "4f1d6f2a-..."
    },
    "existing_conversation": false,
    "message": {
      "external_id": "wamid.HBgL...",
      "text": "Derece Kampüsü · Ön görüşme\n\nSelamlar Gülsüm Bodur ben Derece Kampüsü'nden Baran Demir, ön görüşme talep etmişsin ancak sana ulaşamadım.",
      "delivery_status": "sent",
      "ts": "2026-08-11T11:02:07.000Z"
    }
  }
}

existing_conversation alanı true ise konuşma zaten vardı. Mesaj o konuşmaya eklendi ve ikinci bir konuşma açılmadı. Kişiyi "to": { "contact_id": "..." } ile de adlandırabilirsiniz. Kai o zaman kişinin kayıtlı telefon numarasını kullanır. Telefonu olmayan bir kişi no_phone hatası döndürür.

4. Güvenle yeniden deneyin

Bir gönderim para tutar ve bir insana ulaşır. Her mesaj niyeti için benzersiz bir değerle Idempotency-Key başlığı gönderin.

Aynı anahtarla bir çağrı zaten başarılı olduysa, Kai saklanan yanıtı döndürür ve tekrar göndermez.
İlk çağrı başarısız olduysa, Kai anahtarı serbest bırakır. Yeniden denemeniz çalışır.
İlk çağrı hâlâ çalışıyorsa, Kai 409 idempotency_in_flight hatası döndürür. Kısa bir süre sonra yeniden deneyin.
Aynı anahtar farklı bir gövdeyle 422 idempotency_mismatch hatası döndürür. Yeni bir mesaj için yeni bir anahtar kullanın.

5. Yanıtı kimin karşılayacağına karar verin

Gönderimin kendisi konuşmayı kimin yöneteceğine karar vermez. Buna assignee alanı karar verir.

assignee ile konuşma o ekip arkadaşına ait olur. Kai atanmış bir konuşmada yanıt vermez. Müşterinin yanıtı, o ekip arkadaşının gelen kutusunda ve Element X odalarında bekler.
assignee olmadan konuşma, kanalın yanıt politikasında kalır. Kanal otopilotta çalışıyorsa, müşteriye Kai yanıt verebilir.

Dönen yanıtı bir insanın karşılaması gerekiyorsa bir assignee adlandırın, örneğin bir satış görüşmesinde. Yanıtı Kai karşılayabilirse alanı atlayın, örneğin bir ödeme hatırlatmasında.

Hatalar

`error.type`	Anlamı
`template_missing`	Kanal bu şablonu içermiyor. Eşitleyin ve yeniden deneyin.
`template_unapproved`	Meta bu şablonu onaylamadı veya onayı kaldırdı.
`variables_missing`	Bir değişken boş veya eksik. İpucu taşıyanlar dahil, her değişken zorunludur.
`variables_unknown`	Değerler, bu şablonun taşımadığı bir değişkeni adlandırıyor. Başlığın değişkeni `header.` öneki ister.
`variables_not_named`	Değerler bir nesne, ama bu şablon değişkenlerini numaralıyor. Dizi gönderin.
`no_phone`	`to.contact_id` alanındaki kişinin telefon numarası yok.
`identity_conflict`	Numara, farklı bir kişinin konuşmasına ait.
`recipient_undeliverable`	WhatsApp, son 7 gün içinde bu numaraya son mesajı iletemedi. Bu süre dolana veya müşteri yazana kadar Kai tekrar göndermez. Müşteriyi arayın.
`send_failed`	WhatsApp gönderimi reddetti. Mesaj, Meta’nın gerekçesini içerir.

Hata biçimi ve genel kodlar için Hata yönetimi sayfasına bakın.

Buradan başlayın

Kavramlar

Nasıl yapılır

Şablon mesajı gönderme

1. Kanalı bulun

2. Şablonları ipuçlarıyla listeleyin

Başlıklı şablonlar

İpuçlarını kullanın

3. Şablonu gönderin

Değerler için iki biçim

4. Güvenle yeniden deneyin

5. Yanıtı kimin karşılayacağına karar verin

Hatalar

​1. Kanalı bulun

​2. Şablonları ipuçlarıyla listeleyin

​Başlıklı şablonlar

​İpuçlarını kullanın

​3. Şablonu gönderin

​Değerler için iki biçim

​4. Güvenle yeniden deneyin

​5. Yanıtı kimin karşılayacağına karar verin

​Hatalar

1. Kanalı bulun

2. Şablonları ipuçlarıyla listeleyin

Başlıklı şablonlar

İpuçlarını kullanın

3. Şablonu gönderin

Değerler için iki biçim

4. Güvenle yeniden deneyin

5. Yanıtı kimin karşılayacağına karar verin

Hatalar