API ve webhook

Sol menüde Bağlantılar › API ve webhook, SemAgent'ı kendi sistemlerinize bağladığınız ekrandır: görüşmeleri ve müşterileri API ile okur, yanıt gönderirsiniz; bir şey olduğunda webhook ile anında haber alırsınız.

Kimler kullanabilir?

Ekran Roller ve Yetkiler'deki Ayarlar satırına bağlıdır: görmek için görme, anahtar ve webhook eklemek için düzenleme yetkisi gerekir. Webhook görüşme içeriğini dışarı gönderdiği için kurmak ve düzenlemek ayrıca Sohbetler'i görme izni ister.

API anahtarları

1. Anahtar oluştur'a basın, anahtara bir ad verin (hangi sistem kullanacak? ör. “CRM eşitleme”) ve yetkisini seçin: Yalnız okuma ya da Okuma ve yazma. Okuma ve yazma; görüşmeye yanıt göndermeyi, iç not eklemeyi ve görüşmeyi çözüldü işaretlemeyi de açar.
2. Anahtar yalnız bu anda, bir kez gösterilir: kopyalayıp güvenli bir yerde saklayın. Kaybederseniz yenisini oluşturup eskisini iptal edin.

• Anahtar, onu oluşturan kişinin rol yetkileriyle çalışır. Her istek, kişinin rolünün paneldeki eşdeğer ekranı görüp göremediğine bakar. Kişinin rolü daralırsa anahtarın yetkisi de daralır; kişi pasifleşir ya da silinirse anahtar çalışmaz.
• İptal et anahtarı hemen ve geri alınamaz biçimde kapatır; satır listede İptal edildi olarak kalır.
• Hesap başına en çok 10 etkin anahtar; anahtar başına dakikada 120 istek (aşan istek HTTP 429 alır). Listede her anahtarın son kullanıldığı zaman görünür.
• SemAgent anahtarın kendisini saklamaz; yalnız doğrulamaya yetecek bir özetini tutar.

API'yi kullanmak

Adres https://semagent.ai/api/v1. Her istekte anahtarı Authorization: Bearer başlığıyla gönderin. Yanıtlar JSON'dur ve hangi sürümle yazıldığını api_version alanında söyler (şu an 2026-10-26). Hata yanıtı {"detail": {"code": "…", "message": "…"}} biçimindedir.

curl "https://semagent.ai/api/v1/conversations?status=active&limit=20" \
  -H "Authorization: Bearer $SEMAGENT_API_KEY"

curl -X POST "https://semagent.ai/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer $SEMAGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Merhaba, siparişiniz yarın kargoda."}'

Uç	Ne yapar	Yetki
GET /me	Bağlantı denemesi: hesabın kimliği ve anahtarın yetkisi.	okuma
GET /conversations	Görüşme listesi. Süzgeçler: status, channel, limit (1–100, varsayılan 50), offset.	okuma
GET /conversations/:id	Bir görüşme, mesajlarıyla.	okuma
POST /conversations/:id/messages	Görüşmeye yanıt gönderir ({"text": "…"}, en çok 4.000 karakter). Paneldeki Gönder ile aynı yoldan müşterinin kanalına gider; gerekiyorsa görüşmeyi devralır.	okuma ve yazma
POST /conversations/:id/notes	Ekibe iç not ekler ({"text": "…"}); müşteriye gitmez.	okuma ve yazma
POST /conversations/:id/resolve	Görüşmeyi çözüldü işaretler.	okuma ve yazma
GET /contacts	Müşteriler. q (arama), limit (1–100), offset.	okuma
GET /contacts/:id	Bir müşteri: ad, e-posta, görüşme sayısı, kanallar, etiketler, ilk ve son görülme.	okuma

Webhook'lar

Webhook ekle: https:// ile başlayan, internetten erişilebilen bir adres ve hangi olaylarda haber verileceği. Seçtiğiniz olaylar olduğunda adresinize imzalı bir istek (POST, JSON) gider. Webhook'u kurduğunuz andan sonraki olaylar gönderilir; geçmiş görüşmeler dökülmez.

Olay	Ne zaman
conversation.created	Yeni görüşme açıldığında.
message.created	Yeni mesaj geldiğinde ya da gittiğinde (müşteri, ekip ya da yapay zekâ). data.message mesajın kendisidir: yazan (visitor, agent, ai, system, auto), metin (en çok 4.000 karakter), ekler (ad ve boyut).
conversation.escalated	Görüşme ekibe devredildiğinde.
conversation.resolved	Görüşme çözüldüğünde.
csat.submitted	Müşteri memnuniyet puanı verdiğinde; data.csat puanı ve yorumu taşır.

Her olayın data.conversation alanı görüşmenin özetidir: kanal, durum, devralınıp devralınmadığı, müşterinin adı ve e-postası, açılma, güncellenme ve çözülme zamanı. Örnek bir message.created isteği:

{
  "id": "4b9e0c52-7a1d-4f3e-9c06-2d8e5a1f7b30",
  "event": "message.created",
  "api_version": "2026-10-26",
  "tenant_id": "00000000-0000-4000-8000-000000000000",
  "created_at": "2026-10-26T08:41:10Z",
  "data": {
    "conversation": {
      "id": "0f3c7a91-5e2b-4d8a-b1c4-9a6e2d7f0c11",
      "channel": "whatsapp",
      "status": "active",
      "human_takeover": false,
      "customer": { "name": "Elif Yıldız", "email": null },
      "created_at": "2026-10-26T08:40:52Z",
      "updated_at": "2026-10-26T08:41:09Z",
      "resolved_at": null
    },
    "message": {
      "id": "7d21e6b0-3c4f-4a9e-8b57-1e0f9c2a6d48",
      "author": "visitor",
      "text": "Siparişim ne zaman kargoya verilir?",
      "created_at": "2026-10-26T08:41:09Z",
      "attachments": []
    }
  }
}

• Kimin adına çalışır: webhook, onu kuran (ya da en son adresini veya olaylarını değiştiren, yeniden başlatan) kişinin adına çalışır. O kişinin Sohbetler'i görme izni kalmazsa ya da hesabı kapanırsa webhook kendiliğinden durur (Duraklatıldı · kuranın izni yok); yeniden başlatırsanız sizin adınıza çalışır.
• Deneme gönder gerçek imzayla bir webhook.test olayı yollar ve sonucu (HTTP kodu ve süre) gösterir; deneme kayda geçmez.
• Teslimler son teslimleri listeler: olay, durum (Teslim edildi, Yeniden denenecek, Başarısız, Sırada), deneme sayısı, HTTP kodu ve süre. Teslim kaydı isteğin gövdesini tutmaz ve 7 gün sonra silinir.
• Başarı ve yeniden deneme: 2xx yanıt teslim sayılır; yanıt 10 saniye beklenir. Ulaşmayan istek 1 dakika, 5 dakika, 30 dakika, 2 saat ve 12 saat sonra yeniden denenir. Art arda 20 teslim başarısız olursa webhook duraklatılır; düzeltip Yeniden başlat'a basın.
• Güvenli adres: yalnız internete açık adreslere gönderilir; iç ağa çıkan adreslere gönderilmez ve yönlendirme izlenmez.
• Hesap başına en çok 5 webhook.

İmzayı doğrulamak

Webhook oluşturulunca bir gizli gösterilir; yalnız o an görünür, kaybederseniz Gizliyi yenile deyin. Her istek üç başlık taşır: SemAgent-Event (olay), SemAgent-Delivery (teslim kimliği) ve SemAgent-Signature (t=<unix zamanı>,v1=<imza>). İmza; başlıktaki t değeri, bir nokta ve istek gövdesinin art arda yazılmasından gizlinizle hesaplanan HMAC-SHA256'dır.

• İmzayı gövdenin ham baytlarıyla hesaplayın; JSON'u ayrıştırıp yeniden yazmayın.
• 5 dakikadan eski t taşıyan isteği reddedin.
• Aynı olay nadiren iki kez gelebilir: SemAgent-Delivery kimliğiyle tekrarı ayıklayın.

# Python
import hashlib, hmac, time

def verify(secret: str, header: str, body: bytes) -> bool:
    # header: SemAgent-Signature = "t=<unix>,v1=<hex>" ; body: the raw request body
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300

// Node.js
const crypto = require("crypto")

function verify(secret, header, rawBody) {
  const p = Object.fromEntries(header.split(",").map((x) => x.split("=")))
  const expected = crypto.createHmac("sha256", secret).update(`${p.t}.`).update(rawBody).digest("hex")
  const same = expected.length === p.v1.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1))
  return same && Math.abs(Date.now() / 1000 - Number(p.t)) < 300
}