Widget API'ye Genel Bakış

Widget API, web chat widget'ının backend'idir. Widget görünüm ayarlarını sunar, ziyaretçiyi kaydeder, sohbet geçmişini yükler, mesaj gönderimini işler ve yeni mesajları Socket.IO ile gerçek zamanlı iletir.

Bu dokümantasyon, Widget API'yi ürün ortamında entegre etmek için gereken bilgileri içerir.

Ne işe yarar?

Widget istemcisi (web sayfanıza gömülen chat arayüzü) doğrudan sohbet veritabanına veya bot motoruna bağlanmaz. Tüm ziyaretçi etkileşimi Widget API üzerinden akar:

Sorumluluk	Açıklama
Görünüm & form	Widget'ı modellemek için config (tema, zorunlu alanlar, karşılama)
Kimlik	Ziyaretçi kaydı ve JWT (accessToken) üretimi
Geçmiş	Aktif sohbetin mesaj listesi
Gönderim	Metin veya dosya mesajı gönderme
Canlı akış	Bot / agent cevaplarını Socket.IO ile alma

Entegrasyon akışı

Tipik bir widget oturumu şu sırayla ilerler:

1. GET  /settings/:appId     → widget config
2. POST /register            → accessToken (JWT)
3. Socket.IO  /message       → auth.token = accessToken
4. GET  /message             → geçmiş mesajlar
5. POST /message             → yeni mesaj (text / dosya)
6. Socket "message" event    → bot / agent cevapları

Adım adım mantık

1. Ayarları al — Widget Ayarları ile appId üzerinden config çekin. Form alanları, zorunlu alanlar, tema ve karşılama mesajlarını buradan modelleyin. JWT gerekmez.
2. Ziyaretçiyi kaydet — Ziyaretçi Kaydı ile form verilerini gönderin. Sunucu kullanıcıyı oluşturur veya günceller ve accessToken döner.
3. Socket'e bağlan — Token ile /message namespace'ine bağlanın. Sunucu sizi doğru odaya ({chatAppId}-{chatUserId}) alır.
4. Geçmişi yükle — Mesaj Geçmişi ile mevcut mesajları çekin. type alanına göre data değişir; bkz. Mesaj Tipleri.
5. Mesaj gönder — Mesaj Gönderme ile kullanıcı girdisini gönderin. Socket yalnızca gelen mesajlar içindir.

Temel kavramlar

Kavram	Açıklama
appId	Chat uygulamasının UUID'si. Ayarlar ve kayıt isteklerinde kullanılır.
accessToken	Kayıt sonrası alınan JWT. Mesaj geçmişi, mesaj gönderme ve Socket.IO için zorunludur.
Mesaj tipi (type)	TEXT, IMAGE, VIDEO, AUDIO, FILE, MULTIPLE_CHOICE, MULTIPLE_CHOICE_REPLY, INTERACTIVE, CAROUSEL, TEMPLATE
isFromSupport	true ise mesaj bot/agent tarafından, false ise ziyaretçi tarafından gönderilmiştir.

Base URL

Tüm örneklerde BASE_URL şu adresi ifade eder:

const BASE_URL = 'https://widget-api.chatbot.aithinks.net';

Canlı servis: https://widget-api.chatbot.aithinks.net/

Sonraki adımlar

1. Widget Ayarları — widget config
2. Ziyaretçi Kaydı
3. Kimlik doğrulama — JWT kullanımı
4. Gerçek zamanlı mesajlar
5. Mesaj Geçmişi
6. Mesaj Gönderme
7. Mesaj tipleri