POST/api/public/widget/message

Ziyaretçinin bir mesajını sohbet botuna gönderir ve onun yanıtını döndürür – sohbet widget'ının merkezi uç noktası.

`widget_code`, `message`, `visitor_id`'yi ve ikinci mesajdan itibaren önceki yanıttan `session_id`'yi gönderin. Yeni bir konuşmanın ilk çağrısında `session_id`'yi boş bırakın veya `null` olarak ayarlayın. Yanıt, `data` nesnesinde `session_id`, yanıt metni `response` ile gerektiğinde düğmeler (`buttons`), ürün önerileri (`products`) ve konuşma durumunu (`state`) içerir. Embed token ile `X-Widget-Token` başlığı ve `widget_code` gereklidir. Belirteç eksikse, sunucu 401 `WIDGET_TOKEN_MISSING` ile yanıt verir, geçersizse 401 `WIDGET_TOKEN_INVALID` ile; onaylanmamış alan adlarından gelen çağrılar 403 `WIDGET_ORIGIN_DENIED`, devre dışı bırakılmış bir widget 404 `WIDGET_DISABLED` alır. `visitor_id` eksikse, sunucu 400 `VISITOR_ID_REQUIRED` ile yanıt verir. Çağrı idempotent değildir: her gönderme başka bir ziyaretçi mesajı ve başka bir yanıt oluşturur. Bir istek sürerken girişi kilitleyin ve otomatik olarak tekrarlamayın.

Genel Bakış

Çağrı: POST /api/public/widget/message. Bu uç nokta, Zentor App API'sinin “Sohbet Widget'ı” grubuna aittir. Geçerli bir widget embed token'ı gerektirir. Çağrı idempotent değildir: Her başarılı çağrı işlemi yeniden tetikler. Zorunlu parametreler: widget_code (Body), message (Body), visitor_id (Body). İsteğe bağlı parametreler: session_id (Body). Belgelenmiş hata durumları: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Aşağıdaki örnek yanıt, JSON formatındaki başarılı bir yanıtın yapısını gösterir.

Kimlik Doğrulama ve Güvenlik

Widget gömme jetonu (X-Widget-Token başlığı) + kaynak onay listesi

İdempotent: Hayır

Parametreler

widget_code(body, string, zorunlu)— Yerleştirme (embed) kodunuzdan widget kodu
message(body, string, zorunlu)— Ziyaretçi mesajının metni
visitor_id(body, string, zorunlu)— Widget'ın oluşturduğu ve tarayıcıda sakladığı ziyaretçi kimliği
session_id(body, string)— Önceki yanıttan gelen oturum kimliği; yeni bir konuşmanın ilk çağrısında boş veya `null`

Örnek İstek

{"widget_code":"...","message":"Merhaba, Zentor App neler yapabilir?","visitor_id":"<UUID veya istemci tarafında oluşturulan kimlik>"}

Örnek Yanıt

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

Hata Kodları

401 WIDGET_TOKEN_MISSING — `X-Widget-Token` başlığı eksik.
401 WIDGET_TOKEN_INVALID — Embed token, widget koduyla eşleşmiyor.
400 VISITOR_ID_REQUIRED — `visitor_id` alanı eksik.

Doğrulanmış davranış

Geçerli bir mesaj, sohbet botunun yanıtıyla 200 döner; eksik veya geçersiz belirteç ile eksik `visitor_id`, belgelenen hata kodlarını döner.

Sohbet Widget'ı

GET /api/public/widget/healthWidget hizmetinin basit bir erişilebilirlik kontrolü.GET /api/public/widget/config/:widget_codeTarayıcıda başlatma için bir widget'ın herkese açık yapılandırmasını (görünen ad, karşılama metni, tasarım, dil, sesli işlev) döndürür.GET /api/public/widget/historyÖrneğin sayfa yeniden yüklendikten sonra, bir widget konuşmasının önceki mesaj geçmişini yükler.POST /api/public/widget/pollBelirli bir zamandan sonra alınan mesajları alır – örneğin, konuşmayı devralan bir çalışanın yanıtı.POST /api/public/widget/ratingZiyaretçinin bir konuşma hakkındaki değerlendirmesini (yararlı veya yararlı değil) kaydeder.POST /api/public/widget/trackDashboard'daki analizler için widget'ın anonim bir kullanım olayını (örn. "widget açıldı") kaydeder.POST /api/public/widget/voice-transcribeWidget için sesli işlev etkinleştirilmişse, ziyaretçinin sesli kaydını metne dönüştürür (sesli giriş).POST /api/public/widget/voice-speakSesli işlev etkinleştirilmişse, metni sesli konuşmaya dönüştürür (widget'ta sesli çıkış).

İlgili makaleler

← Sohbet Widget'ı