ÇözümDevi Geliştirici Dokümantasyonu

Kendi sisteminizden WhatsApp üzerinden müşterilerinize bildirim gönderin: kargo çıktı, sipariş onaylandı, randevu hatırlatması. Gelen cevapları da okuyabilirsiniz.

Bu doküman, API referansının yanında nasıl çalıştığını anlatır — çünkü bir alanın adını bilmek, ne zaman kullanılacağını bilmek demek değildir.

---

1. Uygulama oluşturun

Panelden Uygulamalar → Uygulamalarım altında bir uygulama oluşturun. Size iki değer verilir:

Değer	Ne işe yarar
client_id	Uygulamanızı tanımlar, gizli değildir
client_secret	Yalnız bir kez gösterilir. Kaybederseniz yeniden üretmeniz gerekir

İzinler (scope) iki tanedir: messaging:read (okuma) ve messaging:send (gönderme). Uygulamanıza yalnızca ihtiyacı olanı verin.

2. Access token alın

curl https://api.cozumdevi.com/api/v2/wa/oauth/token \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "cid_…",
    "client_secret": "csec_…"
  }'

Token 1 saat geçerlidir ve Authorization: Bearer <access_token> başlığıyla kullanılır.

:::tip Token yenilemede yarış yoktur Token'lar durumsuzdur (stateless) ve iptal listesi yoktur. Yeni token almak eskisini geçersiz kılmaz — ikisi de kendi süresi dolana kadar çalışır. Bu yüzden yenileme sırasında "eski token 401 verdi mi" diye beklemenize gerek yok; yenisini alıp eskisini bırakabilirsiniz.

Bunun bir sonucu daha var: bir uygulamayı iptal ederseniz, daha önce verilmiş token süresi dolana kadar (en fazla 1 saat) çalışmaya devam edebilir. :::

3. İlk mesajınızı gönderin

Gönderim yapmadan önce anlamanız gereken tek kural şu:

:::warning 24 saatlik pencere WhatsApp'ta müşteriye istediğiniz zaman serbest metin gönderemezsiniz. Müşteri size en son ne zaman yazdıysa, o andan itibaren 24 saat boyunca serbest metin gönderebilirsiniz. Pencere kapandıysa yalnızca Meta tarafından onaylanmış bir şablon gönderebilirsiniz.

Bu bizim koyduğumuz bir kısıt değil, WhatsApp'ın kuralıdır. API bunu sizin adınıza kontrol eder: pencere kapalıyken serbest metin denerseniz 409 messaging_window_closed alırsınız ve yanıtta messaging_state alanı durumu açıklar. :::

Bir kişinin gönderime açık olup olmadığını önceden öğrenmek için GET /contacts/{contact_id} çağırın; messaging.sendable ve messaging.requires_template alanları size ne yapabileceğinizi söyler.

4. Gelen mesajları okuyun

Müşteri cevap verdiğinde mesaj hem panelinizde görünür hem API'den okunabilir:

• GET /conversations — konuşmalar, en son yazana göre sıralı
• GET /contacts/{contact_id}/messages — bir kişinin mesaj geçmişi

:::info preview ve text farkı Mesaj nesnesinde iki metin alanı vardır ve karıştırılmaları gerçek bir entegrasyon hatasına yol açtı, o yüzden net yazıyoruz:

• text — mesajın tam gövdesi. Kırpılmaz, satır sonları korunur, uzunluk sınırı yoktur. Metin işleyen her entegrasyon bunu kullanmalıdır.
• preview — listede göstermek için kısa gösterim. Düz metinde tam gövdedir, ama medya mesajlarında içerik yerine yer tutucu döner ([image: fatura.pdf]).

Yani müşteri bir fotoğrafın açıklamasına sipariş kodunu yazdıysa, o kod preview'de yoktur, text'te vardır. :::

Hız limitleri

Uygulama başına, sabit saniye penceresi:

İşlem	Limit
Okuma	5 istek/sn
Gönderme	3 istek/sn
Token alma	2 istek/sn

Aşarsanız 429 rate_limit_error ve Retry-After başlığı alırsınız. Her yanıtta RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset başlıkları döner — akıllı backoff için bunları okuyun. Ayrıca kanal başına günlük gönderim kotası vardır (quota_exceeded).

Hata zarfı

Bütün hatalar aynı şekilde döner:

{
  "error": {
    "type": "invalid_request_error",
    "code": "messaging_window_closed",
    "message": "24 saatlik pencere kapalı; şablon gönderin.",
    "param": "body",
    "request_id": "req_8f3aK2…"
  }
}

request_id her yanıtta Request-Id başlığında da bulunur. Destek talebi açarken bunu paylaşın — aradığımız ilk şey odur.

Kimlikler

Kimlikler opak ve büyük/küçük harf duyarlıdır: msg_FkR ile msg_Fkr farklı kaynaklardır. Veritabanınızda bu değerleri saklarken harf duyarlı karşılaştırma kullanın; aksi halde iki farklı mesaj aynı satıra düşer.

---

Soldaki WhatsApp API bölümünde her ucun tam referansı, örnek istek/yanıtları ve tarayıcıdan deneme imkânı var.