Bu sayfa widget'ı elle gömen geliştiriciler için teknik referanstır. Adım adım kurulum anlatımı widget kurulumu sayfasında; burada yalnızca nitelikler, uç noktalar ve gereksinimler var.
Script ve element
<giizo-convai agent-id="ASISTAN_ID" signed-url="wss://api.giizo.ai/convai/v1/ws?..."></giizo-convai>
<script src="https://cdn.giizo.ai/convai-widget/index.js" async type="text/javascript"></script>
Script async yüklenebilir. Sayfada birden fazla giizo-convai elementi varsa yalnızca ilki işlenir; çoklu widget desteklenmiyor.
HTML nitelikleri
Widget yalnızca aşağıdaki beş niteliği okur. Bunların dışında bir nitelik (renk, dil, data-* vb.) vermenin etkisi yoktur.
Nitelik
Zorunlu
Varsayılan
Açıklama
agent-id
Evet
—
Asistan kimliği. Verilmezse widget hiç başlamaz.
signed-url
Pratikte evet
—
İmzalı WebSocket adresi. Geçersizse bağlantı kurulmaz.
base-url
Hayır
https://api.giizo.ai
API kök adresi.
theme
Hayır
light
Tema. Panelde karşılığı yok, yalnızca burada verilir.
position
Hayır
bottom-right
Widget konumu. Panelde yalnızca boşluk değeri ayarlanır.
signed-url teknik olarak zorunlu değildir — verilmediğinde widget yüklenir ve arayüzü çizilir, ancak sohbet başlatıldığında bağlantı kurulamaz. Yani çalışan bir kurulum için gereklidir.
İmzalı bağlantı üretimi
İmzalı adres, API anahtarıyla kimlik doğrulaması yapan bir uçtan alınır:
GET https://api.giizo.ai/convai/v1/conversation/get-signed-url?agent_id=ASISTAN_ID
İstek API anahtarı gerektirir. Bu çağrı sunucu tarafında yapılmalıdır; API anahtarı hesabınızın tamamına erişim verdiği için tarayıcıya gönderilen koda konmamalıdır.
Dönen değer şu biçimdedir:
wss://api.giizo.ai/convai/v1/ws?agent_id=ASISTAN_ID&conversation_signature=<JWT>
Bu adresi olduğu gibi signed-url niteliğine yazarsınız.
Süre ve yenileme
conversation_signature süreli bir JWT'dir; widget içindeki geçerlilik süresini token'dan okur. Bağlantı koptuğunda ve kalan süre beş dakikanın altındaysa widget yapılandırmayı yeniden çekmeyi dener.
Ancak yapılandırma ucu imzalı adres döndürmez (aşağıya bakın); bu nedenle otomatik yenileme pratikte tamamlanmaz. Uzun süre açık kalan sayfalarda çalışan yaklaşım, sayfayı her yüklemede sunucu tarafında taze bir imzalı adres üretmektir.
Yapılandırma ucu
GET https://api.giizo.ai/widget/public-config/{agentId}
Kimlik doğrulaması gerektirmez, ancak:
- İstek
OriginveyaRefererbaşlığı taşımalıdır. İkisi de yoksa yanıt 403 döner. - Asistanın izinli alan adları listesi doldurulmuşsa istek yapan alan adı listede olmalıdır. Liste boşsa tüm alan adlarına izin verilir.
- Asistan pasif durumdaysa yanıt 404 döner.
Accept-Languagebaşlığı okunur; karşılama mesajının dili buna göre seçilir.
Yanıt gövdesi widget'ın görünüm ayarlarını (renkler, varyant, köşe yarıçapları, boşluklar, metinler, avatar adresi, oturum zaman aşımı) taşır. İmzalı adres bu yanıtta yer almaz.
Site tarafında gereken izinler
Sitenizde içerik güvenlik politikası veya izin politikası kullanıyorsanız aşağıdaki izinleri tanımlamanız gerekir:
Yönerge
Değer
script-src
https://cdn.giizo.ai
connect-src
https://api.giizo.ai ve wss://api.giizo.ai
media-src
Sesli konuşma için blob:
Permissions-Policy
Sesli konuşma için microphone izni
Sesli konuşma ayrıca tarayıcının ses kaydı desteğini ve ziyaretçinin mikrofon iznini gerektirir.
Diğer genel uç noktalar
Widget'ın kullandığı, kimlik doğrulaması gerektirmeyen diğer uçlar:
GET /widget/rating/{agentId}vePOST /widget/rating/{agentId}— konuşma değerlendirmesiGET /widget/conversation-history/{sessionId}— oturum geçmişi
Kapsam dışı olanlar
Bu bölüm açıkça belirtilsin diye var: bugün müşteriye açık, dokümante edilmiş bir genel API yüzeyi bulunmuyor. Widget'ın kullandığı uçlar dışında dışa açık bir REST API, giden webhook (olay bildirimi) veya kendi araç sunucunuzu bağlama yolu sunulmuyor. Bu sayfadaki uçlar widget'ı gömmek için gerekli olanlarla sınırlıdır.
İlgili sayfalar
- Widget kurulumu — adım adım kurulum
- Hazır platform eklentileri — imzalı bağlantı adımını sizin yerinize yapan eklentiler