Web SDK

Web SDK, yani @harmona-ai/chat-sdk, bir asistanı sitenize bir açma düğmesi ve bir sohbet paneli olarak yerleştirir. Yanıtları akışla gösterir, zengin kartlar çizer ve kendi Shadow DOM'u içinde çalışır; böylece sayfanızın stilleri ile widget'ın stilleri hiçbir zaman çakışmaz. React, Vue, Angular, Svelte ya da düz HTML ile çalışır.

Harmona'da açın

1. 1Asistanı Stüdyo → Asistanlar altında açın ve Çıktı Kanalları bölümünü açın.
2. 2Web SDK anahtarını açın. Widget API üzerinden konuştuğu için API Erişimi de onunla birlikte açılır.
3. 3API Anahtarları altında widget için bir anahtar oluşturun. Bkz. REST API.
4. 4Görünümünü ve metinlerini ayarlamak için Widget'ı yapılandır seçeneğini seçin.

npm ile kurun

Paket özeldir ve GitHub Packages üzerindedir. Harmona size bunun için salt okunur bir erişim token'ı verir. Token'ı bir .npmrc dosyasına ekleyin, ardından kurun:

# .npmrc (bu token'ı kaynak kontrolüne eklemeyin)
@harmona-ai:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${HARMONA_ACCESS_TOKEN}

npm install @harmona-ai/chat-sdk

import HarmonaChat from "@harmona-ai/chat-sdk";

const chat = HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
});

İhtiyacınız olan kodun tamamı bu. Açma düğmesi sağ altta görünür; geri kalan her şey Harmona'da yaptığınız yapılandırmadan gelir. init fonksiyonunu bir kez çağırın, örneğin kök layout'unuzda, ve bileşeni kaldırırken chat.destroy() çağırın. Next.js'te tarayıcı penceresine ihtiyaç duyduğu için onu bir istemci bileşeninden çağırın.

Script etiketiyle kullanın

Paket ayrıca window.HarmonaChat tanımlayan bağımsız bir tarayıcı derlemesi içerir: dist/harmona-chat.global.js. Bu dosyayı kendi sitenizden sunun ve bir script etiketiyle yükleyin:

<script src="/assets/harmona-chat.global.js"></script>
<script>
  HarmonaChat.init({
    baseUrl: "https://api.harmona.ai",
    apiKey: "hapi_your_widget_key",
  });
</script>

Kod yazmadan yapılandırın

Widget'ı yapılandır, gerçek widget'ın canlı önizlemesini içeren bir düzenleyici açar. Widget bu yapılandırmayı başlarken çeker; bu yüzden değişiklikleriniz sitenize yeni bir dağıtım yapmadan ulaşır.

init'e verdiğiniz değerler alan alan her zaman önceliklidir: önce SDK varsayılanları, sonra Harmona yapılandırması, en son sizin kodunuz. Harmona yapılandırmasını tamamen yok saymak için remoteConfig: false verin.

Init seçenekleri

init; open, close, toggle, show, hide, destroy, setColorScheme, setUser, setFallback ve setAgent içeren bir tanıtıcı döndürür. Widget hiçbir zaman kendi başına sayfa değiştirmez: bağlantılar ve bağlantı kartları sizin onRedirect hook'unuzdan geçer. Her widget oturumu yeni bir konuşma başlatır.

Canlı destek çubuğu

Devretme çubuğu, ziyaretçinin bir kişiyle görüşmek istemesini sağlar. Çubuğu Canlı destek sekmesinden açın; başlığını, alt başlığını, rengini ve simgesini (destek, WhatsApp, telefon, e-posta ya da kendi görseliniz) orada ayarlarsınız. Ziyaretçi çubuğu seçtiğinde widget sizin onHandoff hook'unuzu çağırır. Hook yoksa ayarladığınız hedef bağlantıyı açar; örneğin bir WhatsApp bağlantısını.

HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
  handoff: { enabled: true, label: "Talk to a representative" },
  fallbacks: {
    onHandoff(ctx) {
      // ctx.transcript: { agent_name, messages: [{ role, content }] }
      sendToSupportDesk(ctx.transcript);
      window.open("https://wa.me/15550000000", "_blank");
    },
  },
});

Hook, o ana kadarki konuşmayı ctx.transcript içinde alır: asistanın adı ve ziyaretçi ile asistanın mesajlarından oluşan düz bir liste; destek ekibinize iletmeye hazırdır. Bu, REST API içindeki GET /b2c/v1/chat/handoff ile aynı veridir.

Dil

Widget'ın etiketleri İngilizce ve Türkçe olarak gelir. İçerik sekmesinde Widget dili ayarını ya da kodda locale değerini belirleyin. Bu ayar, Harmona'yı kullandığınız dilden bağımsızdır.

Olaylar ve faturalama hataları

fallbacks.onEvent, dikkate değer her etkileşimi { name, data } olarak alır: open, close, session_start, response_start, response_end, response_error, grid_click, starter_click, quick_reply_click, message_send, redirect ve handoff.

Çalışma alanı harcama yapamıyorsa (HTTP 402), ziyaretçiler Türkçe widget'ta “Asistan şu anda geçici olarak kullanılamıyor. Lütfen daha sonra tekrar deneyin.” mesajını görür ve yazdıkları metin kaybolmaz. Kodunuz payment_required koduyla response_error alır; böylece ekibinizi uyarabilirsiniz:

HarmonaChat.init({
  baseUrl: "https://api.harmona.ai",
  apiKey: "hapi_your_widget_key",
  fallbacks: {
    onEvent({ name, data }) {
      if (name === "response_error" && data?.code === "payment_required") {
        reportToOps("Harmona chat unavailable: " + data.error);
      }
    },
  },
});