WhatsApp Template API

Geliştirici API'si

Onaylı WhatsApp şablonlarını kendi sistemlerinizden tek bir API çağrısıyla gönderin; konuşma ardından MonoChat'te devam eder.

WhatsApp
REST API
Yalnızca API

MonoStore'dan kurun monochat.ai'de inceleyin

Genel bakış

WhatsApp Template API, CRM'inizin, ERP'nizin, e-ticaret sitenizin veya herhangi bir arka ucun MonoChat üzerinden müşteriye onaylı bir WhatsApp şablon mesajı göndermesini sağlar. Tek bir istek, gönderilecek WhatsApp numarasını, müşterinin telefon numarasını, şablonu ve değişkenlerini belirtir.

Müşteri yanıt verdiğinde konuşma, diğerleri gibi MonoChat gelen kutunuza düşer. Uygulamanın kendi ekranı yoktur: her şey üç API uç noktası üzerinden yapılır.

Öne çıkanlar

Tek API çağrısı. Bir şablonu adı ve diliyle gönderin; başlık, gövde, düğme ve karusel değişkenleri verilerinizden doldurulur.
Doğrudan sohbete. Her gönderim, konuşmanın kimliğini ve MonoChat'teki doğrudan bağlantısını döndürür.
Yeni müşterilere açık. Telefon numarası henüz bir müşteri değilse, müşteri gönderdiğiniz adla oluşturulur.

Kurulum

WhatsApp Business numaranızı MonoChat'e bağlayın; numaranın doğrulanmış olduğundan ve Meta onaylı şablonları bulunduğundan emin olun.
WhatsApp Template API uygulamasını Ayarlar › MonoStore › Uygulamalar bölümünden yükleyin ya da kurulum bağlantısını açın: app.monochat.ai/apps/K6u29LpbwCHBozZ8o. MonoChat hesabınız yoksa bağlantı önce kaydolmanızı sağlar ve uygulamayı sizin için yükler.
Profil › API Tokenları altında bir API token'ı oluşturun. Token yalnızca bir kez gösterilir; hemen kopyalayın.
Onaylı şablonlarınızı ve değişkenlerini görmek için template/list.js çağrısını yapın.
İlk şablonunuzu göndermek için müşterinin numarası ve değişken değerleriyle template/send.js çağrısını yapın.

MonoChat ayarlarında MonoStore uygulama listesi ve WhatsApp Template API

MonoStore’da WhatsApp Template API ayrıntıları ve Yükle düğmesi

not

Her mesaj, MonoChat'ten gönderilen herhangi bir şablon mesajı gibi faturalandırılır.
Medya URL'leri, WhatsApp dosyayı alana kadar erişilebilir kalmalıdır.
Sizden haber almayı kabul eden müşterilere gönderin: WhatsApp, mesajları engellenen veya şikâyet edilen numaralara sınırlama getirebilir.

Ekran ekran

WhatsApp Template API'nin kendine ait bir ekranı yoktur ve sol menüye hiçbir şey eklemez. Onu iki yerde görürsünüz: yüklerken ve yüklü uygulamalar listenizde.

Yükleme

MonoStore Uygulama Önizleme çekmecesinde Yükle düğmesine tıklayın. Bundan sonra MonoChat içinde API token'ı dışında ayarlanacak bir şey yoktur.

Yükle düğmesiyle WhatsApp Template API için MonoStore Uygulama Önizleme çekmecesi

Yüklü uygulamalar

Yüklendikten sonra uygulama, Ayarlar › MonoStore › Yüklü Uygulamalar altında sürümü, yayıncısı ve açıklamasıyla bir kart olarak görünür.

Geri kalan her şey API üzerinden yapılır: şablonlarınızı listeleyin, bir şablon gönderin ve başlık için medya yükleyin. Bkz. API başvurusu ve Hatalar.

Özellikler

Şablonları listeleyin

Bir WhatsApp numarasının onaylı şablonları; dili, kategorisi, durumu ve değişkenleriyle birlikte, böylece sisteminiz neyi gönderebileceğini bilir.

Şablon gönderin

Şablon adı ve diliyle, başlık, gövde, düğme ve karusel değişkenleriyle. Eksik bir değer gönderimi durdurur; böylece müşteriye yarım doldurulmuş hiçbir şey ulaşmaz.

Temsilciye ata

Bir temsilcinin e-postasını verin, konuşma onun adına açılır.

Medya başlıkları

Kısa ömürlü bir yükleme bağlantısı alın, bir görseli, videoyu veya belgeyi MonoChat'in depolama alanına koyun ve herkese açık URL'sini şablonun başlığı olarak kullanın.

Konuşma bağlantısı

Her gönderim oturum kimliğini, mesaj kimliğini ve konuşmayı MonoChat'te açan bir bağlantıyı döndürür.

Anlaşılır hatalar

Başarısız bir çağrı neyin ters gittiğini söyler; örneğin “Channel not found” veya “Variable missing”.

Başlamadan önce

WhatsApp Business numaranız MonoChat'e bağlı ve doğrulanmış olmalı. Bkz. Kanallar.
Göndermek istediğiniz şablonlar Meta tarafından onaylanmış olmalı. İlk mesajı siz yazarken ya da 24 saatlik pencerenin dışındaki bir müşteriye ulaşırken şablon kullanılır. Bkz. Şablon Mesajlar.
Profil › API Tokenları bölümünden alınmış bir API token'ınız olmalı. Bkz. API Tokenları.
Tenant slug'ınızı bilmelisiniz: MonoChat adresinizde /tenants/ sonrasındaki kısım. https://app.monochat.ai/tenants/isletmem adresinde slug isletmemdir.

API başvurusu

Uygulamanın kendi ekranı yoktur. Her şey, her biri JSON gövdeli bir POST olan üç uç nokta üzerinden yapılır:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Uç nokta	Ne yapar
`template/list.js`	WhatsApp numaralarınızdan birinin şablonlarını değişkenleriyle listeler.
`template/send.js`	Bir müşteriye şablon gönderir ve konuşmanın bağlantısını döndürür.
`upload/get-upload-url.js`	Başlık görseli, videosu ya da belgesi için kısa ömürlü bir yükleme bağlantısı ve herkese açık URL'yi verir.

Telefon numaraları her zaman ülke koduyla ve + olmadan yazılır, örneğin 905334445566. Başarılı bir çağrı 200 ile yanıt verir ve uç noktanın verisi result altında döner.

1. Şablonları listeleme

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Belirtilen WhatsApp Business numarasının tüm şablonlarını listeler: ad, dil kodu, kategori, bileşenler (başlık, gövde, alt bilgi, düğmeler), değişken türleri ve onay durumu.

Alan	Zorunlu	Açıklama
`phoneNumber`	evet	MonoChat'teki WhatsApp Business numaranız; ülke koduyla, `+` olmadan.
`options`	hayır	Sayfalama ve filtreler, örneğin `{ "pagination": { "currentPage": 1, "pageItems": 50 } }`.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Yanıt (kısaltılmış):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Yanıtı okuma:

name: şablonu gönderirken kullanacağınız sistem adı.
languageCode: gönderimde kullanılacak dil.
category: WhatsApp kategorisi (MARKETING, UTILITY, AUTHENTICATION).
components: şablonu oluşturan bölümler.

Bileşen	İçerik	Açıklama
`HEADER`	`IMAGE`, `VIDEO`, `DOCUMENT` ya da metin	Medya varsa `format` belirtilir; değişkenler `variables` içinde görünür.
`BODY`	Değişkenli metin	Mesaj gövdesi; `{{1}}`, `{{2}}` gibi yer tutucular içerir.
`FOOTER`	Metin	Genellikle değişken içermez.
`BUTTONS`	URL, hızlı yanıt…	Düğme metinleri ve varsa değişkenleri.

Yukarıdaki örnek şablon, başlık için bir görsel ve gövde için iki metin (müşteri adı ve ürün adı) ister. Alt bilgi sabittir ("Teşekkürler") ve düğme yoktur.

2. Şablon gönderme

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Onaylı bir şablonu bir müşteriye gönderir. Telefon numarası henüz bir müşteri değilse müşteri oluşturulur; konuşma açılır (ya da mevcut konuşma kullanılır) ve şablon bu konuşmada gönderilir.

Alan	Zorunlu	Açıklama
`phoneNumber`	evet	Gönderimin yapılacağı WhatsApp Business numarası. MonoChat'e bağlı ve doğrulanmış olmalıdır.
`templateMessageName`	evet	Şablonun `name` değeri; listede döndüğü gibi.
`languageCode`	evet	Şablonun dili; listede döndüğü gibi (örneğin `tr-TR`).
`customerPhoneNumber`	evet	Müşterinin WhatsApp numarası.
`variables`	şablonda değişken varsa	Şablon değişkenlerinin değerleri (aşağıya bakın).
`customerFirstName`, `customerLastName`	hayır	Müşteri MonoChat'te yeniyse kullanılır.
`agentEmailAddress`	hayır	Konuşmayı bu e-postaya sahip temsilciye atar.

Değişkenler. variables dizisindeki her öğenin bir type değeri ve şablondaki yer tutucuların sırasıyla verilen bir parameters listesi vardır:

`type`	`parameters`
`HEADER`	Başlıktaki metin değişkeni ya da başlık görselinin, videosunun veya belgesinin herkese açık URL'si. Belge için `parameters`'ın yanında `filename` da verin (örneğin `"filename": "Offer.pdf"`): WhatsApp'ın dosya için gösterdiği ad budur.
`BODY`	Gövdedeki `{{1}}`, `{{2}}`, … sırasıyla.
`BUTTONS`	Değişkeni olan her düğme için bir değer (örneğin URL düğmesinin değişken kısmı ya da kupon kodu), düğme sırasıyla.
`CAROUSEL`	`parameters` yerine, her karusel kartı için kendi `components` değerleriyle bir öğe içeren `cards` dizisi.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Eksik bir değer gönderimi Variable missing hatasıyla durdurur; böylece müşteriye yarım doldurulmuş bir mesaj gitmez. FOOTER nadiren değişken içerir.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@sirketiniz.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/urun.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Telefon"] }
  ]
}

Yanıt:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

url: konuşmayı MonoChat'te açar; oturum açmış ve konuşmayı görme yetkisi olan kişiler için.
sessionId: konuşmanın kimliği.
messageId: mesajın MonoChat'teki kimliği. İletilme ve okunma durumu, diğer mesajlarda olduğu gibi sohbette görünür.

Şablonlarda medya. WhatsApp başlık medyasını verdiğiniz URL'den indirir; bu yüzden URL geçerli ve herkese açık olmalıdır. Oturum açmayı gerektiren bağlantılar çalışmaz. Dosyayı upload/get-upload-url.js ile yüklediyseniz, o yanıttaki downloadUrl değerini kullanın.

3. Başlık için medya yükleme

POST /api/<slug>/custom-functions/template-app/api/upload/get-upload-url.js

Bir şablonun başlığı görsel, video ya da belge olduğunda dosyanın WhatsApp'ın indirebileceği herkese açık bir adresi olmalıdır. Bu uç nokta, dosyayı MonoChat depolamasına koymanız için kısa ömürlü bir bağlantı verir.

Alan	Zorunlu	Açıklama
`fileName`	evet	Uzantısıyla dosya adı, örneğin `urun.jpg` ya da `kampanya.pdf`.
`contentType`	evet	Dosyanın türü, örneğin `image/jpeg`, `video/mp4` ya da `application/pdf`.

Dosyalar her zaman çalışma alanınızın chat-assets klasörüne kaydedilir.

POST /api/<slug>/custom-functions/template-app/api/upload/get-upload-url.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "urun.jpg",
  "contentType": "image/jpeg"
}

Yanıt (kısaltılmış):

{
  "result": {
    "uploadUrl": "https://s3.monochat.ai/app-monochat/store/2026/<slug>/chat-assets/…-urun.jpg?X-Amz-…",
    "downloadUrl": "https://s3.monochat.ai/app-monochat/store/2026/<slug>/chat-assets/…-urun.jpg"
  }
}

Alan	Açıklama
`uploadUrl`	Dosyanın yükleneceği adres, 15 dakika geçerlidir.
`downloadUrl`	Dosyanın herkese açık adresi.

Dosyayı hemen düz bir PUT isteğiyle uploadUrl adresine yükleyin: gövde olarak dosyanın kendisini, Content-Type başlığı olarak da aynı contentType değerini gönderin. S3 istemcisine ya da kimlik bilgilerine gerek yoktur:

curl -X PUT -H "Content-Type: image/jpeg" --data-binary @urun.jpg "<uploadUrl>"

Ardından şablonu gönderirken downloadUrl değerini HEADER parametresi olarak verin. Çok büyük dosyalar ya da WhatsApp'ın desteklemediği biçimler (yaygın görsel, video ve PDF biçimlerini kabul eder) başarısız olur.

not

Eski entegrasyonlar upload/get-token.js çağırıyor olabilir. Yeni entegrasyonlar upload/get-upload-url.js kullanır.

Örnek: görsel başlıklı bir şablon

Görsel başlığı ve iki gövde değişkeni (müşteri adı ve ürün adı) olan, onaylı new_product_announcement şablonunu bir müşteriye göndermek istediğinizi düşünelim.

Şablonları listeleyin. WhatsApp numaranızla template/list.js çağrısı yapın ve new_product_announcement şablonunu bulun. Bileşenleri, başlıkta bir IMAGE ve gövdede iki TEXT değişkeni olduğunu gösterir.
Görseli yükleyin. { "fileName": "urun.jpg", "contentType": "image/jpeg" } ile upload/get-upload-url.js çağrısı yapın, dosyayı dönen uploadUrl adresine yükleyin ve downloadUrl değerini saklayın.
Şablonu gönderin. template/send.js çağrısında downloadUrl değerini HEADER parametresi, ["Ayşe", "XYZ Telefon"] dizisini de BODY parametreleri olarak verin ({{1}} → Ayşe, {{2}} → XYZ Telefon). Şablonda düğme değişkenleri olsaydı aynı şekilde bir BUTTONS öğesi eklerdiniz.
Sohbeti açın. Yanıttaki url konuşmayı açar; müşteri yanıt verdiğinde konuşma MonoChat gelen kutunuzda devam eder.

Hatalar

Başarısız bir çağrı, hata durum kodu ve neyin yanlış gittiğini söyleyen bir mesajla yanıt verir. Bu mesajları sisteminizde kaydedin ve gerektiğinde kullanıcılarınıza anlamlı bir mesaj gösterin.

Mesaj	Nedeni
`phoneNumber field is required`	`template/list.js`, `phoneNumber` olmadan çağrıldı.
`phoneNumber, templateMessageName, customerPhoneNumber fields are required`	`template/send.js` için zorunlu bir alan eksik.
`Channel not found`	`phoneNumber`, çalışma alanınızın bir WhatsApp numarası değil.
`Channel is not verified`	WhatsApp numarası bağlı ama doğrulanmamış.
`Template message not found`	Numarada bu ad ve dilde onaylı bir şablon yok. Yazımı ve `languageCode` değerini kontrol edin.
`Template message is not approved`	Şablon var ama Meta tarafından onaylanmamış.
`Variable missing: …`	`variables`, şablonla eşleşmiyor; örneğin şablon iki gövde değeri istiyor, siz bir tane gönderdiniz.
`Agent user not found`	`agentEmailAddress` içindeki e-postaya sahip bir temsilci yok.
`Customer Channel not found`	Müşterinin WhatsApp kimliği oluşturulamadı ya da bulunamadı.
`fileName is required`, `contentType is required`	`upload/get-upload-url.js` için zorunlu bir alan eksik.

Karşılaşabileceğiniz HTTP durum kodları:

401 Unauthorized: Authorization: Bearer <API_TOKEN> başlığı eksik ya da token yanlış veya süresi dolmuş. Hesabınızdan geçerli bir token kullanın.
403 Forbidden: token'ın bu çalışma alanına ya da uygulamaya erişimi yok; örneğin tenant slug yanlış.
404 Not Found: uç nokta adresi yanlış. Tam yolu kontrol edin: /api/<slug>/custom-functions/template-app/api/....
500 Internal Server Error: MonoChat'te ya da WhatsApp sağlayıcısında beklenmeyen bir sorun veya WhatsApp tarafında bir ret (numara WhatsApp'ta değil, müşteri sizi engellemiş, kalite ya da hız sınırları). Daha sonra yeniden deneyin; sorun sürerse MonoChat destek ekibine başvurun.

Ekran görüntüleri

Onaylı bir WhatsApp şablonunu bir CRM, ERP veya e-ticaret sisteminden MonoChat üzerinden tek bir API çağrısıyla gönderme

Onaylı WhatsApp şablonlarının değişkenleriyle birlikte listesi

Yeni bir numaraya şablon göndermek müşteriyi otomatik olarak oluşturur

Birden fazla dilde gönderilen tek bir şablon

Görsel, video, belge ve PDF başlıklı şablonlar

Sık sorulan sorular

WhatsApp Template API'nin kullanıcı arayüzü var mı?

Hayır. Üç uç noktası olan, yalnızca API'den oluşan bir uygulamadır: şablonları listeleme, şablon gönderme ve medya başlıkları için yükleme bağlantısı alma.

Kullanmadan önce neye ihtiyacım var?

MonoChat'e bağlı ve doğrulanmış bir WhatsApp Business numarası, Meta tarafından onaylanmış şablonlar ve Profil › API Token'ları altından alınan bir API token'ı.

Müşteri yanıt verdiğinde ne olur?

Konuşma, diğerleri gibi MonoChat gelen kutunuza düşer. Her gönderim ayrıca konuşmanın doğrudan bağlantısını döndürür ve konuşmayı e-posta ile bir temsilciye atayabilirsiniz.

Henüz müşteri olmayan bir numaraya gönderebilir miyim?

Evet. Telefon numarası henüz bir müşteri değilse, müşteri gönderdiğiniz adla oluşturulur.

Şablon mesajlarının maliyeti nedir?

Her mesaj, MonoChat'ten gönderilen herhangi bir şablon mesajı gibi faturalandırılır. Meta, şablonları kategoriye ve alıcının ülkesine göre fiyatlandırır; bir gönderimin maliyetini tahmin etmek için WhatsApp toplu mesaj maliyet hesaplayıcısını kullanın.

Genel bakış​

Öne çıkanlar​

Kurulum​

Ekran ekran​

Yükleme​

Yüklü uygulamalar​

Özellikler​

Şablonları listeleyin​

Şablon gönderin​

Temsilciye ata​

Medya başlıkları​

Konuşma bağlantısı​

Anlaşılır hatalar​

Başlamadan önce​

API başvurusu​

1. Şablonları listeleme​

2. Şablon gönderme​

3. Başlık için medya yükleme​

Örnek: görsel başlıklı bir şablon​

Hatalar​

Ekran görüntüleri​

Sık sorulan sorular​

WhatsApp Template API'nin kullanıcı arayüzü var mı?​

Kullanmadan önce neye ihtiyacım var?​

Müşteri yanıt verdiğinde ne olur?​

Henüz müşteri olmayan bir numaraya gönderebilir miyim?​

Şablon mesajlarının maliyeti nedir?​

İlgili sayfalar​