WhatsApp API

Bu bölümde, app.postacell.com.tr üzerinde tanımlı WhatsApp Business hesabınıza ait onaylı şablonlar (template) üzerinden 1:1 işlemsel (transactional) WhatsApp mesajı göndermenizi sağlayan API uç noktaları yer almaktadır.

Not

Bu uç noktalar sadece category değeri UTILITY veya AUTHENTICATION olan ve status değeri APPROVED olan şablonlar için kullanılabilir. MARKETING kategorisindeki şablonlar bu API ile gönderilemez.

Not

Tüm uç noktalar için app_id parametresi, Postacell WhatsApp panelinizde görünenen App ID’dir.

Şablon Servisleri

Gönderim yapmadan önce, hesabınıza tanımlı ve transactional API ile gönderilebilecek şablonları ve bu şablonların değişken (variable) yapısını bu servisten öğrenebilirsiniz.

GET waba/transactional/templates

GET waba/transactional/templates

Transactional API ile gönderilebilecek (UTILITY/AUTHENTICATION, APPROVED) şablonları, header/body/footer/button değişken yapılarıyla birlikte listeler.

POST waba/transactional/send isteğinde hangi template_id / template_name’i ve hangi sırayla header_variables / body_variables göndermeniz gerektiğini bu uç noktadan öğrenebilirsiniz.

Example request:

GET v1/waba/transactional/templates/?app_id=d32e3e6f-a0a6-4552-b7ad-44956aa95765 HTTP/1.1
Host: app.postacell.com.tr/api/
Accept: application/json

Query Parameters:

app_id – required. WhatsApp Business hesabınızın App ID’si.
category – Filtre. Alabileceği değerler UTILITY, AUTHENTICATION
search – Şablon adında (template_name) arama yapar.
page – Sayfa numarası. default 1
page_size – Sayfa başına kayıt sayısı. default 20, max 1000

Request Headers:

Authorization – required OAuth token to authenticate. Bkz: Kimlik Doğrulama ve Token Alma

Status Codes:

200 OK –
400 Bad Request – app_id gönderilmediyse veya category geçersizse, json object döner
404 Not Found – App bulunamadıysa

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "count": 1,
   "total_pages": 1,
   "results": [
      {
         "template_id": 174,
         "template_name": "siparis_durumu",
         "category": "UTILITY",
         "language_code": "tr",
         "status": "APPROVED",
         "header": {
            "type": "image",
            "variables": []
         },
         "body": {
            "text": "Merhaba {{1}}, {{2}} numaralı siparişiniz kargoya verildi. Takip linki: {{3}}",
            "variables": [
               {"position": 1, "example": "Ahmet"},
               {"position": 2, "example": "12345"},
               {"position": 3, "example": "https://kargotakip.com/12345"}
            ]
         },
         "footer": {
            "text": "Postacell İletişim Hizmetleri"
         },
         "buttons": [
            {
               "type": "URL",
               "text": "Kargo Takip",
               "url": "https://kargotakip.com/{{1}}",
               "variables": [
                  {"position": 1, "example": "value"}
               ]
            }
         ],
         "variable_count": 4
      }
   ]
}

count:: Toplam şablon sayısı
total_pages:: Toplam sayfa sayısı
results:: Şablon listesi
template_id:: POST waba/transactional/send isteğinde template_id olarak kullanılır
template_name:: POST waba/transactional/send isteğinde template_name olarak kullanılabilir
category:: UTILITY veya AUTHENTICATION
language_code:: Şablonun dil kodu (örn. tr, en)
status:: Her zaman APPROVED (bu uç nokta sadece onaylı şablonları döner)
header:: Şablonun header bilgisi. Header yoksa null döner. type alanı text, image, video veya document olabilir.
body:: Şablonun ana metni ve içindeki {{n}} değişkenlerinin örnek değerleri
footer:: Şablonun sabit alt metni. Footer yoksa null döner.
buttons:: Şablona tanımlı butonlar. Sadece dinamik (URL tipi, içinde {{1}} olan) butonlar variables alanı dolu döner.
variable_count:: Şablondaki toplam değişken sayısı (header + body + buttons)

Not

header, body ve buttons içindeki variables alanlarındaki position değeri, ilgili alan içindeki {{n}} numarasını gösterir; gönderim sırasını belirtmez. Gönderim sırası, POST waba/transactional/send isteğindeki header_variables ve body_variables dizilerinin kendi sırasıdır: önce header (varsa, tek eleman), sonra body içindeki değişkenler {{1}}, {{2}}… sırasıyla.

Gönderim Servisleri

Bir şablon kullanarak tek bir alıcıya WhatsApp mesajı gönderir ve gönderdiğiniz mesajların durumunu takip edersiniz.

POST waba/transactional/send

POST waba/transactional/send

Tek bir alıcıya (1:1) UTILITY/AUTHENTICATION kategorisinde bir WhatsApp şablon mesajı gönderir.

Gönderim işlemi asenkron olarak kuyruğa alınır; mesajın gerçek gönderim durumu GET waba/transactional/send/(str:ObjectId) ile sorgulanmalıdır.

Not

Bu servis sadece Accept: application/json veriyi kabul eder.

Example request:

POST v1/waba/transactional/send HTTP/1.1
Host: app.postacell.com.tr/api/
Accept: application/json

{
   "app_id": "d32e3e6f-a0a6-4552-b7ad-44956aa95765",
   "to": "905551234567",
   "template_name": "siparis_durumu",
   "header_variables": [],
   "body_variables": ["Ahmet", "12345", "https://kargotakip.com/12345"],
   "buttons": [
      {"index": 0, "type": "url", "value": "12345"}
   ],
   "callback_data": {"order_id": "12345"}
}

Form Parameters:

app_id – required. WhatsApp Business hesabınızın App ID’si.
to – required. Alıcı telefon numarası. E.164 formatında, başında + ile veya olmadan gönderilebilir.
template_id – Gönderilecek şablonun ID’si. template_name ile birlikte ikisinden biri zorunludur.
template_name – Gönderilecek şablonun adı (element_name). template_id ile birlikte ikisinden biri zorunludur.
header_variables – Type = array. Şablonun header’ında {{1}} varsa, tek elemanlı bir dizi olarak gönderilmelidir. Header yoksa veya medya (image/video/document) tipindeyse boş dizi [] gönderilmelidir.
body_variables – Type = array. Şablonun body’sindeki {{n}} sayısı kadar, sırasıyla gönderilmelidir. Değişken yoksa boş dizi [] gönderilebilir.
buttons – Type = array, opsiyonel. Sadece şablonda tanımlı dinamik butonlar için gönderilir. Aşağıdaki nota bakınız.
callback_data – Type = object, opsiyonel. Sizin tarafınızdan belirlenen ve mesajla birlikte Gupshup’a iletilen (biz_opaque_callback_data) serbest formatlı bir json.

Request Headers:

Authorization – required OAuth token to authenticate. Bkz: Kimlik Doğrulama ve Token Alma

Status Codes:

202 Accepted – İstek kuyruğa alındı
400 Bad Request – Eksik/hatalı parametre, json object döner
402 Payment Required – Bakiye yetersiz
403 Forbidden – App mesaj göndermeye kapalı veya aktif bir WhatsApp planınız yok
404 Not Found – App veya şablon bulunamadı
429 Too Many Requests – Aynı şablon, aynı numaraya 60 saniye içinde tekrar gönderilmeye çalışıldı

Example response:

HTTP/1.1 202 Accepted
Vary: Accept
Content-Type: application/json

{
   "id": "665abf12c8a1f4e9d8b2a111",
   "status": "waiting",
   "to": "905551234567",
   "template_name": "siparis_durumu",
   "estimated_cost": 0.0691
}

id:: Gönderim kaydının ID’si. GET waba/transactional/send/(str:ObjectId) ile durumu sorgulamak için kullanılır.
status:: Gönderimin anlık durumu. Bkz: GET waba/transactional/send/(str:ObjectId)
to:: Alıcı numarası (E.164, + olmadan)
template_name:: Gönderilen şablonun adı
estimated_cost:: Bu gönderim için bakiyenizden düşülen tahmini tutar (USD)

Not

buttons alanı için örnek:

[
   {"index": 0, "type": "url", "value": "12345"},
   {"index": 1, "type": "quick_reply", "payload": "SIPARIS_IPTAL"}
]

index: Şablondaki butonun sırası (0’dan başlar). GET waba/transactional/templates yanıtındaki buttons dizisindeki sıraya karşılık gelir.

type: url veya quick_reply.

url: Şablonda dinamik ({{1}} içeren) bir URL butonu için. value alanı, butonun URL’sindeki {{1}} yerine geçecek değerdir.
quick_reply: Şablonda bir QUICK_REPLY butonu için. payload alanı, bu butona tıklandığında webhook üzerinden size geri dönecek serbest metindir.

Şablonda sabit (değişkeni olmayan) butonlar için buttons alanına herhangi bir şey göndermenize gerek yoktur; bu butonlar mesajla birlikte otomatik olarak gönderilir.

Not

Mükerrer / spam koruması: aynı to + template kombinasyonu için 60 saniye içinde yapılan tekrar istekleri 429 Too Many Requests ile reddedilir.

GET waba/transactional/send/(str:ObjectId)

GET waba/transactional/send/(str: ObjectId)

POST waba/transactional/send ile gönderilmiş tek bir mesajın güncel durumunu (status, gupshup_message_id, hata bilgileri vb.) döner.

Example request:

GET v1/waba/transactional/send/665abf12c8a1f4e9d8b2a111 HTTP/1.1
Host: app.postacell.com.tr/api/
Accept: application/json

Parameters:

ObjectId (str) – POST waba/transactional/send yanıtındaki id

Request Headers:

Authorization – required OAuth token to authenticate. Bkz: Kimlik Doğrulama ve Token Alma

Status Codes:

200 OK –
404 Not Found –

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "id": "665abf12c8a1f4e9d8b2a111",
   "app_id": "d32e3e6f-a0a6-4552-b7ad-44956aa95765",
   "template_id": 174,
   "template_name": "siparis_durumu",
   "language_code": "tr",
   "category": "UTILITY",
   "to_number": "905551234567",
   "variables": ["Ahmet", "12345", "https://kargotakip.com/12345"],
   "status": "read",
   "gupshup_message_id": "ABGGFlA5FpafAgo6tHcNmNjXmuSNZ8YOlAU",
   "error_code": null,
   "error_message": null,
   "estimated_cost": 0.0691,
   "callback_data": {"order_id": "12345"},
   "gupshup_response": {
      "status": "submitted",
      "messageId": "ABGGFlA5FpafAgo6tHcNmNjXmuSNZ8YOlAU"
   },
   "created_at": "2026-06-13T10:15:30.000000Z",
   "updated_at": "2026-06-13T10:16:05.000000Z",
   "sent_at": "2026-06-13T10:15:31.500000Z",
   "delivered_at": "2026-06-13T10:15:35.000000Z",
   "read_at": "2026-06-13T10:16:05.000000Z"
}

id:: Gönderim kaydının ID’si
app_id:: WhatsApp Business hesabının App ID’si
template_id:: Gönderilen şablonun ID’si
template_name:: Gönderilen şablonun adı
language_code:: Şablonun dil kodu
category:: UTILITY veya AUTHENTICATION
to_number:: Alıcı numarası (E.164, + olmadan)
variables:: İstekte gönderilen header_variables + body_variables (sıralı)
status:: Gönderimin durumu. waiting: Kuyrukta/işleniyor, sent: Gupshup’a iletildi, delivered: Alıcının cihazına ulaştı, read: Alıcı tarafından okundu, failed: Gönderilemedi
gupshup_message_id:: Gupshup tarafından dönen mesaj ID’si. status=sent olduğunda dolu gelir.
error_code:: status=failed olduğunda Gupshup’tan dönen hata kodu
error_message:: status=failed olduğunda hata açıklaması
estimated_cost:: Bu gönderim için bakiyenizden düşülen tahmini tutar (USD)
callback_data:: İstekte gönderilen callback_data
gupshup_response:: Gupshup API’sinin ham yanıtı. status=sent veya status=failed olduğunda dolu gelir.
created_at:: Gönderim isteğinin alındığı zaman
updated_at:: Son güncelleme zamanı
sent_at:: Gupshup’a iletildiği zaman. status=waiting ise null döner.
delivered_at:: Alıcının cihazına ulaştığı zaman. status henüz delivered/read değilse null döner.
read_at:: Alıcı tarafından okunduğu zaman. status=read değilse null döner.

Not

status alanı, mesaj alıcıya iletildikçe webhook üzerinden otomatik güncellenir: sent → delivered → read. Güncel durumu görmek için bu uç noktayı periyodik olarak sorgulayabilirsiniz.

GET waba/transactional

GET waba/transactional

Transactional API ile yapılan gönderimlerin listesini, filtreleme ve sayfalama ile döner.

Example request:

GET v1/waba/transactional?app_id=d32e3e6f-a0a6-4552-b7ad-44956aa95765&status=sent&page=1 HTTP/1.1
Host: app.postacell.com.tr/api/
Accept: application/json

Query Parameters:

app_id – Filtre. WhatsApp Business hesabının App ID’si.
status – Filtre. Alabileceği değerler waiting, sent, delivered, read, failed
to – Filtre. Alıcı numarasına göre (E.164, + olmadan)
page – Sayfa numarası. default 1
page_size – Sayfa başına kayıt sayısı. default 20, max 100

Request Headers:

Authorization – required OAuth token to authenticate. Bkz: Kimlik Doğrulama ve Token Alma

Status Codes:

200 OK –
400 Bad Request – status geçersizse, json object döner

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
   "count": 2,
   "total_pages": 1,
   "results": [
      {
         "id": "665abf12c8a1f4e9d8b2a111",
         "app_id": "d32e3e6f-a0a6-4552-b7ad-44956aa95765",
         "template_id": 174,
         "template_name": "siparis_durumu",
         "language_code": "tr",
         "category": "UTILITY",
         "to_number": "905551234567",
         "variables": ["Ahmet", "12345", "https://kargotakip.com/12345"],
         "status": "delivered",
         "gupshup_message_id": "ABGGFlA5FpafAgo6tHcNmNjXmuSNZ8YOlAU",
         "error_code": null,
         "error_message": null,
         "estimated_cost": 0.0691,
         "callback_data": {"order_id": "12345"},
         "created_at": "2026-06-13T10:15:30.000000Z",
         "updated_at": "2026-06-13T10:15:35.000000Z",
         "sent_at": "2026-06-13T10:15:31.500000Z",
         "delivered_at": "2026-06-13T10:15:35.000000Z",
         "read_at": null
      },
      {
         "id": "665abf0a1234f4e9d8b2a0ff",
         "app_id": "d32e3e6f-a0a6-4552-b7ad-44956aa95765",
         "template_id": 174,
         "template_name": "siparis_durumu",
         "language_code": "tr",
         "category": "UTILITY",
         "to_number": "905559876543",
         "variables": ["Mehmet", "12346", "https://kargotakip.com/12346"],
         "status": "failed",
         "gupshup_message_id": null,
         "error_code": "1013",
         "error_message": "Recipient number is not a valid WhatsApp number",
         "estimated_cost": 0.0691,
         "callback_data": {},
         "created_at": "2026-06-13T10:10:00.000000Z",
         "updated_at": "2026-06-13T10:10:02.000000Z",
         "sent_at": null,
         "delivered_at": null,
         "read_at": null
      }
   ]
}

count:: Toplam kayıt sayısı
total_pages:: Toplam sayfa sayısı
results:: Gönderim listesi. Alanların açıklaması için Bkz: GET waba/transactional/send/(str:ObjectId)

Not

Liste yanıtında gupshup_response alanı yer almaz; bu alana sadece tekil kayıt (GET waba/transactional/send/(str:ObjectId)) üzerinden ulaşılabilir.