Dokümantasyon

İki dakika kurulum, kalanı senin.

Widget public API, REST uçları ve socket event kontratı — geliştiricilerin başlaması için yeterli referans burada.

Kurulum

Tek satırlık script etiketiyle ya da npm paketiyle. Kayıt olduktan sonra panelden siteKey'ini kopyala, aşağıdaki snippet'a yapıştır.

<script
  src="https://cdn.iha-chat.com/loader.js"
  data-site-id="SITE_ANAHTARINIZ"
></script>

Data attribute'ları

Attr	Zorunlu	Açıklama
data-site-id	evet	Public siteKey.
data-api-url	hayır	Prod'da `https://api.iha-chat.com`.
data-realtime-url	hayır	Prod'da `https://rt.iha-chat.com`.
data-theme	hayır	`light` veya `dark`.
data-bundle-url	hayır	Özel CDN kullanacaksan.

Widget public API

Widget yüklendikten sonra global window.IhaChat üzerinden komut çağırırsın. Yüklenmeden önce çağırırsan komut queue'ya alınır, hazır olduğunda oynatılır.

Komutlar

IhaChat('open')

Sohbet balonunu programatik olarak açar.

IhaChat('close')

Açık olan sohbet balonunu kapatır.

IhaChat('identify', { externalId, hmac, name?, email?, phone? })

Ziyaretçiyi hesabınızdaki kullanıcıyla eşler. HMAC yoksa isim/e-posta anonim olarak kabul edilir.

IhaChat('on', 'ready', handler)

Widget yüklenip mount edildiğinde tetiklenir.

IhaChat('on', 'open' | 'close', handler)

Sohbet balonu açıldığında / kapandığında tetiklenir.

IhaChat('on', 'message', ({ from, body }) => …)

Yeni gelen mesajlarda tetiklenir; from: 'visitor' | 'agent'.

HMAC identify örneği (Node)

import { createHmac } from "node:crypto";

const hmac = createHmac("sha256", SITE_SECRET)
  .update(user.id)
  .digest("hex");

// Sonra clientside:
IhaChat("identify", {
  externalId: user.id,
  hmac,
  name: user.name,
  email: user.email,
});

Not: SITE_SECRET asla widget'a gönderilmez — yalnız sunucuda hmac üret.

REST API

Panel scope'undaki uçlar httpOnly cookie (ihachat_access) ya da mobil için Bearer token kabul eder. Public uçlar CORS'a açık ve credential taşımaz.

Public uçlar

Method	Path	Auth	Açıklama
GET	/public/widget-config?siteKey=…	public	Widget'ın kendini kurabilmesi için tema, dil, çalışma saatleri ve özellik bayrakları.
GET	/public/conversations/:id/messages	public	Ziyaretçi geçmişi (cursor pagination: before/after, x-visitor-token header).

Panel uçları (yalnız görünüm)

Method	Path	Auth	Açıklama
POST	/auth/login	public	E-posta + şifre ile giriş; client:'panel' \| 'mobile'.
POST	/auth/refresh	cookie	Refresh token rotation (15 sn grace, reuse tespitinde iptal).
GET	/auth/me	cookie	Oturum sahibinin profili + org üyeliği.
GET	/conversations?siteIds=&status=&search=&labels=	cookie	Konuşma listesi. Çoklu-site + arama + etiket filtreleri.
GET	/conversations/:id	cookie	Tek konuşma detayı: ziyaretçi, etiketler, ekip görünürlüğü.
GET	/conversations/:id/messages	cookie	Cursor pagination'lı mesaj geçmişi.
POST	/conversations/:id/labels	cookie	Konuşmaya etiket ekle / çıkar.
GET	/sites	cookie	Organizasyonun siteleri.
POST	/sites	cookie	Yeni site oluştur (Pro planda sınırsız).
PATCH	/sites/:id	cookie	Site ayarları: renk, tema, çalışma saatleri, offline mesaj.
POST	/sites/:id/regenerate-key	cookie	siteKey yenile (OWNER/ADMIN). Eski embed'ler kırılır.
GET	/analytics/summary?from=&to=&siteIds=	cookie	Konuşma hacmi, CSAT, ort. yanıt, kırılım, heatmap.

Hata formatı: REST hataları { code: "…", message: "…" }. Kullanıcıya dönen mesajlar Türkçe ve teknik detaysız; log'lar sunucuda İngilizce ve detaylı.

Rate limit: visitor mesaj limiti Redis sliding window (10 msg / 10 sn / visitor). REST tarafında da IP-bazlı limit vardır.

Socket eventleri

Realtime tamamen websocket üzerinde (polling fallback yok, sticky session gerekmez). Client için Socket.IO 4 uyumlu; widget kendi minik EIO4 istemcisini kullanır. Tüm payload'lar Zod ile @ihachat/shared'da tanımlı.

/visitor namespace

Event	Yön	Açıklama
visitor:session	→ client	Bağlantıda imzalı visitor token + aktif konuşma bilgisi.
visitor:identify	→ server	externalId + HMAC-SHA256(siteSecret, externalId). Doğrulanmazsa anonim devam.
visitor:prechat	→ server	Sohbet öncesi form yanıtları + departman seçimi.
message:send	→ server	{clientMessageId, body, attachmentId?}. Aynı clientMessageId iki kez gitmez.
message:ack	→ client	{clientMessageId, serverId, createdAt, duplicate}. Gönderene tekil.
message:new	→ client	Konuşma odasına yayın.
typing	↔	Yazıyor göstergesi.
conversation:status	→ client	OPEN \| PENDING \| RESOLVED \| ARCHIVED değişimleri.
conversation:rate	→ server	CSAT: 1 (olumlu) / 0 (olumsuz) + isteğe bağlı yorum.

/agent namespace

Event	Yön	Açıklama
conversation:list-delta	→ client	Konuşma listesindeki değişimler (patch).
conversation:assign	→ server	Konuşmayı üstlen.
conversation:resolve	→ server	Konuşmayı RESOLVED olarak kapat.
conversation:transfer	→ server	Konuşmayı başka departmana / agent'a taşı.
conversation:view	→ server	Bir konuşmayı açtığını bildir (viewing:true/false). TTL 30 sn, heartbeat 12 sn.
conversation:viewers	→ client	Site room'unda o an bakan agent'lar.
visitor:presence	→ client	Ziyaretçi online / uzakta / offline + gezdiği URL.
presence:heartbeat	→ server	Agent presence (Redis TTL 60 sn).
server:restart	→ client	Graceful drain: 300ms → disconnect → client otomatik reconnect.

Room modeli: /visitor → conversation:<id>; /agent → site:<siteId> + agent:<agentId>.

Heartbeat: pingInterval: 25000, pingTimeout: 20000. Mesaj tutarlılığı için client her mesajda UUID clientMessageId üretir; duplicate'te message:ack { duplicate: true } döner.

Webhook'lar

Dış sistemlerden gelen olaylar — Instagram Graph ve Stripe.

GET /webhooks/instagram

Meta challenge doğrulama — text/plain hub.challenge cevabı.

POST /webhooks/instagram

Instagram DM olayları. X-Hub-Signature-256 doğrulanır, rawBody + timingSafeEqual.

POST /billing/webhook

Stripe: checkout.session.completed, customer.subscription.*, invoice.*. Idempotency StripeEvent tablosunda.

API URL'leri (bu ortam)

Landing'in NEXT_PUBLIC_* env'lerinden okunur; kendi kurulumunda değiştir.

panel: https://panel.iha-chat.com
api: https://api.iha-chat.com
rt: https://rt.iha-chat.com

Framework'e özel entegrasyon örnekleri ve daha fazlası için:

Entegrasyon rehberleri