API Dokümantasyonu

Giriş

Tiko WhatsApp API REST tabanlıdır, JSON gövdeleriyle çalışır ve standart HTTP durum kodları döndürür. Mesaj gönderme endpointleri için panelden aldığınız API key gereklidir.

Kimlik doğrulama

Public API isteklerinde Authorization: Bearer YOUR_API_KEY header'ı kullanılır. Panel endpointleri ise panel girişinden dönen oturum token'ı ile çalışır.

curl https://whatsapp.tikoapi.com/health

Oturum

Her WhatsApp numarasının panelde görünen bir sessionId değeri vardır. API key panelde seçilen numaraya bağlı oluşturulur.

curl https://whatsapp.tikoapi.com/v1/sessions/YOUR_SESSION_ID/status \
  -H "Authorization: Bearer YOUR_API_KEY"

Mesajlar

Bağlı WhatsApp oturumunuzdan tek alıcıya metin mesajı gönderir.

curl -X POST https://whatsapp.tikoapi.com/v1/messages/text \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "905xxxxxxxxx",
    "text": "Merhaba, Tiko WhatsApp API aktif."
  }'

Public olarak erişilebilir bir görsel URL'sini WhatsApp mesajı olarak gönderir.

Public olarak erişilebilir bir doküman URL'sini WhatsApp mesajı olarak gönderir. Başarılı istek 202 durumuyla kuyruğa alınır.

Dosya adı URL path'inin son bölümünden güvenli biçimde üretilir. Dosyayı sunan origin Content-Disposition döndürüyorsa filename değerini URL'deki dosya adıyla uyumlu tutun. Bilinmeyen dosya uzantıları application/octet-stream olarak gönderilir.

Görsel ve doküman URL'lerinde localhost, .local alanları ile literal private/reserved IP hedefleri kabul edilmez.

curl -X POST https://whatsapp.tikoapi.com/v1/messages/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "905xxxxxxxxx",
    "documentUrl": "https://cdn.example.com/docs/teklif.pdf",
    "caption": "Teklif dosyanız"
  }'

{
  "id": 4821,
  "status": "queued",
  "chatId": "905xxxxxxxxx@c.us"
}

Anket mesajı

WhatsApp'ta tıklanarak seçilen bir anket gönderir. Müşterinin seçimi, verdiğiniz seçenek id değeriyle webhook'a gelir. Başarılı istek 202 ile kuyruğa alınır ve paket mesaj sayacına bir mesaj olarak yazılır.

curl -X POST https://whatsapp.tikoapi.com/v1/messages/poll \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "YOUR_SESSION_ID",
    "to": "905xxxxxxxxx",
    "question": "Randevunuzu onaylıyor musunuz?",
    "options": [
      { "id": "confirm", "title": "Evet, onaylıyorum" },
      { "id": "reschedule", "title": "Başka gün" }
    ]
  }'

Seçim messages.received olayıyla gelir: data.message.type değeri poll_vote olur, data.message.poll.messageId anket gönderim yanıtındaki id ile eşleşir ve poll.selected seçilen seçenekleri id ile taşır. Seçim kaldırılırsa selected boş dizi gelir.

{
  "event": "messages.received",
  "data": {
    "message": {
      "direction": "inbound",
      "type": "poll_vote",
      "phone": "905xxxxxxxxx",
      "poll": {
        "type": "vote",
        "messageId": "ANKET_GONDERIM_ID",
        "question": "Randevunuzu onaylıyor musunuz?",
        "status": "resolved",
        "selected": [ { "id": "confirm", "title": "Evet, onaylıyorum" } ]
      }
    }
  }
}

Yazıyor göstergesi

Alıcının WhatsApp ekranında "yazıyor…" göstergesini açar veya kapatır. Gösterge mesaj gönderildiğinde ya da stop ile kapanır; WhatsApp bir süre sonra kendiliğinden de kaldırır. Mesaj sayacına yazılmaz; numara başına dakikada 120 istek sınırı vardır.

curl -X POST https://whatsapp.tikoapi.com/v1/messages/typing \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "sessionId": "YOUR_SESSION_ID", "to": "905xxxxxxxxx", "action": "start" }'

CRM'iniz ticket kaydını kendi tarafında tutarken Tiko'dan ham konuşma akışını okuyabilir. source alanı customer, api veya manual döner; böylece telefon/WhatsApp Web üzerinden atılan manuel mesajlar API çıkışlarından ayrılır.

curl https://whatsapp.tikoapi.com/v1/messages?phone=905xxxxxxxxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Panel API

Kullanıcı paneli; giriş, API key yönetimi ve webhook ayarları için aynı API üzerinde çalışır.

Webhook

Gelen mesajları veya mesaj durumlarını sisteminize aktarmak için panelden HTTPS webhook adresi tanımlayın.

Webhook isteklerinde X-Tiko-Event, X-Tiko-Delivery ve secret tanımlıysa X-Tiko-Signature header'ları gönderilir. İmza formatı sha256=... şeklindedir.

{
  "event": "messages.received",
  "timestamp": "2026-06-01T04:42:00.000Z",
  "tenant": { "slug": "tiko-demo" },
  "session": { "id": "wa-905...", "phone": "905..." },
  "data": {
    "message": {
      "direction": "inbound",
      "source": "customer",
      "phone": "905xxxxxxxxx",
      "text": "Merhaba",
      "status": "received"
    }
  }
}

Hata kodları