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 ve oturum işlemleri için panelden aldığınız API key gereklidir.

Kimlik doğrulama

API key'inizi panelden, kullanacağınız WhatsApp numarasını seçerek oluşturun. Public API isteklerinde Authorization: Bearer YOUR_API_KEY header'ı kullanılır. API key'i istemci tarafında veya mobil uygulama içinde paylaşmayın.

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

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

Hızlı başlangıç

İlk mesaj için önce panelden hesap oluşturun, WhatsApp numaranızı QR ile bağlayın, o numaraya bağlı bir API key üretin ve aşağıdaki metin mesajı isteğini gönderin.

Oturumlar

Her WhatsApp numarasının panelde görünen bir sessionId değeri vardır. API key bir numaraya bağlıysa isteklerde yalnızca o oturum kullanılabilir.

Mesajlar

Bağlı WhatsApp oturumunuzdan tek alıcıya metin mesajı gönderir. Başarılı istekler işlenmek üzere kuyruğa alınır ve 202 yanıtı döner.

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."
  }'

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

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

Public olarak erişilebilen 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" }'

Konuşma okuma

CRM veya destek sisteminiz konuşmaları kendi tarafında işlerken Tiko'dan ham konuşma akışını okuyabilir. source alanı customer, api veya manual olarak döner.

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

Webhook

Her WhatsApp numarası için panelde ayrı HTTPS webhook adresleri tanımlanır. Bir endpoint yalnız seçildiği numaradan çıkan olayları alır; aynı URL farklı numaralara ayrı olay seçimleriyle kaydedilebilir. Secret girildiyse istekler X-Tiko-Signature: sha256=... header'ı ile imzalanır.

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

Panel API

Panel, giriş, API key yönetimi, WhatsApp numarası ve webhook ayarları için aynı API üzerinde çalışır. Bu endpointler panel oturum token'ı ile kullanılır.

Hata kodları

Yardıma mı ihtiyacınız var? Ekibimize yazın →