Özel kanal — kendi yazılımını bağla

Özel kanal, kendi yazılımını CRM'in gelen kutusuna bağlamanın yoludur. Hazır bir entegrasyonu olmayan her şey buradan girer: kendi sitenin teklif formu, bir lead toplama aracı, mobil uygulamanın içindeki sohbet, bir kiosk.

İki türü var; kanalı açarken birini seçersin:

#Kanalı aç

CRM → Ayarlar → Çalışma alanı → Kanallar → Özel kanal → Bağlantı kur

Türü ve kanalın adını seçersin (sohbette bir de webhook adresi). Karşılığında:

• Kanal anahtarı (bck_ önekli) — gelen uçları bununla çağırırsın.
• Gelen uç adresi — çalışma alanının CRM adresinde.
• Sohbet türünde ayrıca imza sırrı (bcs_ önekli) — webhook isteklerini doğrularsın.

Kanal anahtarı için çekirdek panelden ayrıca API anahtarı almana gerek yoktur. Anahtar yalnız kendi kanalının uçlarına girer: kişi listesini okuyamaz, başka konuşmalara dokunamaz. Bunun yerine conversations.write kapsamlı bir API anahtarı da kullanabilirsin (bkz. Kimlik doğrulama).

[!İPUCU] Anahtarı sunucunda tut, sitenin tarayıcıda çalışan JavaScript'ine gömme. Formu kendi sunucuna gönder, oradan bize ilet. Anahtar sızarsa en kötü ihtimalle o kanala sahte gönderim düşer; panelden yenileyip kapatırsın.

#Form gönderimi

curl -X POST 'https://<çalışma-alanın>.crm.blesyum.app/api/crm/public/v1/channels/custom/<kanal>/submissions' \
  -H 'Authorization: Bearer bck_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "lead-1001",
    "form": "Teklif formu",
    "contact": { "name": "Deniz Kaya", "email": "deniz@ornek.com", "phone": "0532 111 22 33" },
    "fields": [
      { "label": "Bütçe", "value": "10.000 TL" },
      { "label": "Modüller", "value": ["CRM", "ERP"] }
    ],
    "message": "Pazartesi arayın.",
    "page_url": "https://ornek.com/teklif",
    "utm": { "utm_source": "google" },
    "deal": {}
  }'

Adresi panelden kopyala: kanal ekranı tam adresi verir (kendi alan adını bağladıysan onu taşır).

Gövdedeki alanların adı bir sözleşmedir: tanınmayan bir alan ("email" kökte, contact altında değil) sessizce yok sayılmaz, 400 alır.

#Yanıt

Yeni talep 201, aynı id ile tekrar 200 döner:

{
  "conversation_id": "0193c4e2-…",
  "duplicate": false,
  "deal_id": null,
  "deal_note": "pipeline_not_set_up"
}

Talep gelen kutusuna Web formu kanalıyla düşer; temsilcinin yanıtı müşteriye e-postayla gider. Kanal ilk gönderim gelince panelde "Bağlı" görünür.

#Sohbet mesajı (iki yönlü)

curl -X POST 'https://<çalışma-alanın>.crm.blesyum.app/api/crm/public/v1/channels/custom/<kanal>/messages' \
  -H 'Authorization: Bearer bck_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": { "external_id": "user-42", "name": "Deniz Kaya", "email": "deniz@ornek.com" },
    "message": { "id": "msg-1", "body": "Merhaba, siparişim nerede?" },
    "attachments": [{ "url": "https://cdn.ornek.com/fatura.pdf", "name": "fatura.pdf" }]
  }'

• contact.external_id senin sistemindeki kişi kimliğidir; aynı kişi hep aynı konuşmaya düşer (kapalıysa yeniden açılır).
• message.id mükerrer korumasıdır: aynı kimlik ikinci kez yazılmaz.
• Ek adresleri herkese açık olmalı (iç ağ adresleri reddedilir); dosyayı biz indirip saklarız (en çok 25 MB, 10 ek).

Yanıt 201:

{ "conversation_id": "0193c4e2-…", "message_id": "0193c4e3-…", "new_conversation": true, "duplicate": false }

#Yanıtlar senin webhook'una

Temsilci (ya da AI) yanıt verince adresine imzalı bir POST gelir:

POST /senin-ucun HTTP/1.1
Content-Type: application/json
X-Blesyum-Event: message.created
X-Blesyum-Signature: t=1790000000,v1=5f3a9c…

{
  "event": "message.created",
  "channel_id": "cc_…",
  "conversation_id": "0193c4e2-…",
  "contact": { "external_id": "user-42" },
  "message": {
    "id": "0193c4e4-…",
    "author": { "type": "agent", "name": "Temsilci Can" },
    "text": "Kargoda, yarın elinizde.",
    "html": "<p>Kargoda, <b>yarın</b> elinizde.</p>",
    "attachments": []
  },
  "sent_at": "2026-10-03T12:00:00Z"
}

2xx dönmezsen gönderim temsilciye "iletilemedi" olarak görünür. Yanıt gövdende {"id": "…"} döndürürsen o kimliği saklarız.

Kapanış, yeniden açılış ve AI'dan insana devir de aynı adrese olay olarak gelir: conversation.closed · conversation.reopened · conversation.handed_off. Bunlar kuyruktan teslim edilir ve tutmazsa üstel beklemeyle birkaç saat boyunca yeniden denenir.

#İmzayı doğrula

v1, imza sırrıyla "<t>.<ham gövde>" metninin HMAC-SHA256'sıdır (hex). t beş dakikadan eskiyse reddet — tekrar oynatılan istek budur.

import { createHmac, timingSafeEqual } from "node:crypto";

export function imzaGecerli(hamGovde: string, baslik: string, sir: string): boolean {
  const parca = Object.fromEntries(baslik.split(",").map(p => p.trim().split("=")));
  const t = Number(parca.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const beklenen = createHmac("sha256", sir).update(`${t}.${hamGovde}`).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(String(parca.v1 ?? ""));
  return a.length === b.length && timingSafeEqual(a, b);
}

#Müşterinin arayüzünden iki eylem

#Hatalar

Gövde her zaman aynı biçimdedir:

{ "type": "error.list", "errors": [{ "code": "parameter_invalid", "message": "Send at least one field or a message." }] }