← API referansına dön

Gateway Mesaj Entegrasyon Rehberi

Müşteri mesajlarını kendi CRM, destek masası veya otomasyonunuzda işlemek için Polling ya da Webhook yöntemlerinden birini kullanın.

Hızlı başlangıç

  1. Çalışma alanını Gateway moduna alın.
  2. Çalışma alanı profilindeki Outbound Gateway API Token değerini güvenli sunucu ortamınıza ekleyin.
  3. Polling veya Webhook yöntemini seçin. Aynı çalışma alanında tek yöntem aktiftir.
  4. Yanıt vermek için POST /api/v1/gateway/send-message çağrısını kullanın.

Kimlik doğrulama

Tüm Gateway endpoint’leri çalışma alanına ait Gateway token ile çağrılır. Tercih edilen yöntem Bearer header’ıdır:

Authorization: Bearer gw_...

Alternatif olarak X-Gateway-Api-Token header’ı veya api_token parametresi kabul edilir. Token’ı istemci tarafına veya kaynak koda koymayın.

Polling

Sisteminiz belirli aralıklarla yeni müşteri mesajlarını kendisi çeker. Ağınız dışarıdan erişilebilir değilse iyi bir seçenektir.

Akış

  1. Yeni mesajları çekin.
  2. Mesajı kendi sisteminizde güvenle işleyin.
  3. Başarıyla işlendiğinde mesajı acknowledge edin.

Webhook

Yeni müşteri mesajı oluştuğunda sisteminizin HTTPS endpoint’ine anında POST yapılır. Düşük gecikmeli akışlar için uygundur.

Akış

  1. Webhook URL ve HMAC secret tanımlayın.
  2. İmzayı ham istek gövdesi üzerinden doğrulayın.
  3. message.id ile idempotent işleyin ve hızlı bir 2xx yanıtı dönün.

Polling ile gelen mesajları çekme

curl --request GET 'https://asistan.in/api/v1/gateway/poll-messages?unread_only=true&limit=50' \
  --header 'Authorization: Bearer gw_...'

unread_only varsayılan olarak true, limit varsayılan olarak 50 ve en çok 200’dür. Sıralı devam etmek için son işlenen mesajın ID’sini since_id olarak gönderin. İsterseniz auto_ack=true ile sonuçları çekilir çekilmez okundu işaretleyebilirsiniz; hata toleransı için ayrı acknowledge çağrısı önerilir.

{
  "success": true,
  "count": 1,
  "messages": [{
    "id": 481,
    "chat_id": 73,
    "sender_type": "customer",
    "body": "Siparişim nerede?",
    "status": "delivered",
    "created_at": "2026-08-16T12:34:56.000000Z",
    "chat": {
      "id": 73,
      "customer_name": "Ayşe Yılmaz",
      "channel_type": "whatsapp",
      "channel_chat_id": "905551234567"
    }
  }]
}

İşlendikten sonra acknowledge etme

curl --request POST 'https://asistan.in/api/v1/gateway/acknowledge-messages' \
  --header 'Authorization: Bearer gw_...' \
  --header 'Content-Type: application/json' \
  --data '{"message_ids":[481]}'

Başarılı sonuç {"success":true,"acknowledged_count":1} döner. Acknowledge edilen mesajlar, unread_only=true sorgusunda tekrar listelenmez.

Webhook kurulumu ve doğrulama

curl --request POST 'https://asistan.in/api/v1/gateway/webhook/set' \
  --header 'Authorization: Bearer gw_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "webhook_url":"https://crm.example.com/webhooks/meniyo",
    "webhook_secret":"sunucunuzda-saklayin",
    "sync_method":"webhook"
  }'

Webhook URL HTTPS olmalıdır. Secret verilirse her istekte X-Gateway-Signature ve X-Gateway-Secret header’ları gönderilir. Secret olmadan imza header’ı gönderilmez; canlıda secret kullanın.

{
  "event": "message.received",
  "workspace_id": 12,
  "workspace_name": "Destek Ekibi",
  "chat_id": 73,
  "customer_name": "Ayşe Yılmaz",
  "channel_type": "whatsapp",
  "channel_chat_id": "905551234567",
  "message": {
    "id": 481,
    "body": "Siparişim nerede?",
    "created_at": "2026-08-16T12:34:56+00:00"
  }
}

Node.js ile HMAC doğrulama

import crypto from 'node:crypto';

function verifyGatewaySignature(rawBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expected, 'hex'),
  );
}

İmzayı JSON parse edilmeden önceki ham gövde ile doğrulayın. message.id değerini benzersiz anahtar olarak kaydedin; bu, webhook’u kendi tarafınızda idempotent işlemenizi sağlar. Sistem 5 saniye içinde yanıt bekler ve başarısız webhook gönderimlerini loglar; otomatik tekrar denemesi yapmaz.

curl --request DELETE 'https://asistan.in/api/v1/gateway/webhook' \
  --header 'Authorization: Bearer gw_...'

Webhook kaldırıldığında çalışma alanı otomatik olarak Polling moduna geçer.

Müşteriye yanıt gönderme

curl --request POST 'https://asistan.in/api/v1/gateway/send-message' \
  --header 'Authorization: Bearer gw_...' \
  --header 'Content-Type: application/json' \
  --data '{
    "chat_id":73,
    "message":"Merhaba Ayşe, siparişinizi kontrol ediyorum.",
    "sender_type":"operator"
  }'

Alternatif olarak chat_id yerine channel_type ve channel_chat_id gönderilebilir. Bu çağrı için ilgili platformda aktif bir kanal bulunmalıdır.

Hata kodları