REST API

Her asistan HTTPS üzerinden yanıt verebilir. Bir API anahtarı tek bir asistana aittir; bu yüzden isteklerde asistanın adı geçmez. Kendi son kullanıcılarınızı kendi kimliklerinizle tanımlarsınız ve her birinin çağrılar arasında korunan bir konuşması olur. API erişimi Individual, Business ve Enterprise planlarına dahildir.

API erişimini açın ve anahtar oluşturun

1. 1Asistanı Stüdyo → Asistanlar altında açın ve Çıktı Kanalları bölümünü açın.
2. 2API Erişimi anahtarını açın.
3. 3API Anahtarları altında Anahtar Oluştur seçeneğini seçin ve anahtara bir ad verin, örneğin "Production".
4. 4Anahtarı kopyalayın. Anahtar hapi_ ile başlar ve yalnızca bir kez gösterilir.

Anahtarları yalnızca organizasyon yöneticileri oluşturabilir. Uygulamada oluşturulan anahtarların süresi dolmaz. Her ortam ya da uygulama için ayrı bir anahtar kullanın; böylece birini diğerlerine dokunmadan iptal edebilirsiniz.

Kimlik doğrulama ve temel URL

Anahtarı her istekte bearer token olarak gönderin. Harmona Cloud'da temel URL https://api.harmona.ai adresidir; özel bulut ya da kurum içi kurulumlarda kendi dağıtımınızın API adresini kullanın. Tüm uç noktalar /b2c/v1 altındadır.

Authorization: Bearer hapi_your_key

Uç noktalar

Mesaj gönderin

curl -N https://api.harmona.ai/b2c/v1/chat \
  -H "Authorization: Bearer hapi_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "external_user_id": "customer-4821",
    "messages": [{ "role": "user", "content": "Where is my order?" }]
  }'

Akışı okuma

Yanıt bir text/event-stream akışıdır. Her çerçeve, data: ile başlayıp JSON ile devam eden bir satırdır ve akış data: [DONE] ile biter. Çerçeveler asistan çalıştırma olaylarıdır. Göstereceğiniz yanıt, on_chain_stream adlı olaylarda, data.chunk içinde gelir:

• type: printable, yanıt metnini content içinde taşır. is_thinking değeri true olan parçaları atlayın.
• type: tool, yapılandırılmış bir sonucu artifact içinde, artifact.type ve artifact.data ile taşır; örneğin ürün kartları ya da önerilen sonraki sorular.
• Diğer tüm olayları yok sayabilirsiniz.

Bir yanıt, her olay kısaltılmış hâliyle şöyle görünür:

data: {"event": "on_chain_stream", "data": {"chunk": {"type": "printable", "content": "Your order left "}}, ...}
data: {"event": "on_chain_stream", "data": {"chunk": {"type": "printable", "content": "our warehouse today."}}, ...}
data: [DONE]

Asistan yanıtın ortasında hata verirse akış önce printable metin olarak kısa bir özür gönderir, ardından data.error ve data.error_code içeren bir error olayı, sonra da [DONE] gelir. Model sağlayıcısı yoğunsa kod rate_limit_exceeded olur (kısa süre sonra yeniden deneyin), aksi hâlde internal_error olur.

Node.js 18 ve sonrası için en küçük bir okuyucu:

const res = await fetch("https://api.harmona.ai/b2c/v1/chat", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.HARMONA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    external_user_id: "customer-4821",
    messages: [{ role: "user", content: "Where is my order?" }],
  }),
});
if (!res.ok) throw new Error(`Harmona ${res.status}: ${await res.text()}`);

const decoder = new TextDecoder();
let buffer = "";
for await (const bytes of res.body) {
  buffer += decoder.decode(bytes, { stream: true });
  const frames = buffer.split("\n\n");
  buffer = frames.pop();
  for (const frame of frames) {
    const payload = frame.replace(/^data: /, "");
    if (payload === "[DONE]") continue;
    const evt = JSON.parse(payload);
    const chunk = evt.data?.chunk;
    if (evt.event === "on_chain_stream" && chunk?.type === "printable" && !chunk.is_thinking) {
      process.stdout.write(chunk.content);
    }
    if (evt.event === "error") console.error(evt.data.error_code);
  }
}

Konuşmalar ve geçmiş

• GET /chat/rooms?external_user_id=… her konuşmanın room_id, room_name, created_at ve updated_at değerlerini döndürür.
• GET /chat/messages?external_user_id=… geçmişi döndürür. Belirli bir konuşma için room_id, sayfalama için limit (1–200, varsayılan 50) ve offset ekleyin.
• GET /chat/handoff?external_user_id=… agent_name ve messages döndürür; messages, role (human ya da ai) ve content alanlarından oluşan düz bir listedir. Araç adımları dahil edilmez; bu yüzden listeyi doğrudan bir destek temsilcisine iletebilirsiniz.

Hatalar

Hata yanıtları, detail mesajı içeren JSON'dır. Çoğu bir error_code da taşır. Mesaja göre değil, koda göre dallanın: mesaj İngilizcedir ve değişebilir.

{
  "detail": "…",
  "error_code": "usage_limit_exceeded"
}