Chatbot API Nedir? Yapay Zeka Asistanını Kendi Uygulamanıza Bağlama

Chatbot API, bir chatbotla hazır bir sohbet penceresi yerine kendi kodunuz üzerinden konuşmanızı sağlayan arayüzdür. Uygulamanız kullanıcının mesajını API'ye gönderir, API chatbotun cevabını döndürür; cevabı nerede ve nasıl göstereceğinize siz karar verirsiniz. Bu sayede aynı asistanı web sitenizin yanında mobil uygulamanızda, kendi yazdığınız bir mesajlaşma botunda ya da şirket içi araçlarda da kullanabilirsiniz.

Bu yazıda chatbot API'nin ne zaman widget'tan daha doğru bir seçim olduğunu, Helovo Chatbot API ile ilk isteği nasıl göndereceğinizi ve dikkat etmeniz gereken güvenlik kurallarını anlatıyoruz.

Widget mı, API mi?

Web sitenizde ziyaretçilerle konuşmak istiyorsanız widget her zaman daha kolaydır. API'ye, sohbet penceresinin sitenizde değil kendi ürününüzün içinde olması gerektiğinde ihtiyaç duyarsınız.

Chatbot API ile neler yapılır?

• Mobil uygulama içinde destek: Uygulamanızın "Yardım" ekranında, işletmenizin bilgileriyle yanıt veren bir asistan.
• Kendi mesajlaşma botunuz: Telegram ya da Discord gibi bir platform için yazdığınız botun cevaplarını chatbotun üretmesi.
• Ajanslar: Müşterileriniz için kurduğunuz asistanları kendi panelinize ya da ürününüze bağlamak.
• Destek araçları: Gelen e-posta ya da talebe, asistanın bilgisiyle taslak cevap hazırlamak.
• Kiosk ve iç araçlar: Mağaza içi ekranlarda ya da şirket intranetinde şirket bilgisiyle yanıt veren asistan.

API'nin en büyük avantajı, asistanın bilgisini koddan ayırmasıdır. Fiyat değiştiğinde ya da yeni bir kural eklemek istediğinizde paneldeki talimatı güncellersiniz; kodunuza dokunmanız gerekmez.

Helovo API nasıl çalışır?

Helovo'da her chatbotu hem widget hem API üzerinden kullanabilirsiniz. Akış şöyledir:

1. Hesap açın, chatbotu oluşturun, talimatlarını yazıp panelde test edin.
2. Panelde API sayfasından bir anahtar oluşturun. Anahtarı tüm chatbotlara ya da yalnızca seçtiklerinize yetkilendirebilirsiniz. Anahtar yalnızca bir kez gösterilir.
3. Anahtarı sunucunuzda bir ortam değişkeninde saklayın ve POST /v1/chat uç noktasına istek gönderin.

API ücretli planda açıktır: ayda 5.000 API isteği ve dakikada 60 istek. Güncel seçenekler fiyatlar sayfasında.

İlk istek

curl https://api.helovo.com/v1/chat \
  -H "Authorization: Bearer $HELOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "bot_…", "message": "Cumartesi açık mısınız?", "user": "musteri-42" }'

Cevap:

{
  "id": "msg_01J…",
  "conversation_id": "conv_01J…",
  "answer": "Evet, cumartesi 10:00–16:00 arası açığız.",
  "model": "standard",
  "finish_reason": "stop",
  "usage": { "input_tokens": 142, "output_tokens": 18 }
}

bot_id chatbotun kimliğidir ve panelde chatbotun Kurulum sekmesinde yazar. user isteğe bağlıdır; kendi sisteminizdeki kullanıcı kimliğini gönderirseniz konuşmalar panelde bu kimlikle görünür.

Konuşmayı sürdürmek

Asistanın önceki mesajları hatırlaması için ilk cevaptaki conversation_id değerini sonraki isteklere ekleyin. Konuşma geçmişini sizin saklamanız gerekmez.

// Node.js 18+ (sunucu tarafı)
let conversationId;

async function ask(message) {
  const res = await fetch("https://api.helovo.com/v1/chat", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.HELOVO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ bot_id: "bot_…", message, conversation_id: conversationId }),
  });
  const data = await res.json();
  if (!res.ok) throw new Error(data.error.message);
  conversationId = data.conversation_id;
  return data.answer;
}

console.log(await ask("Kargo kaç günde gelir?"));
console.log(await ask("Peki iade süresi?"));

Akan cevap (streaming)

Kullanıcı cevabın tamamını beklemeden okumaya başlasın istiyorsanız "stream": true gönderin. Cevap Server-Sent Events olarak gelir: önce meta (konuşma kimliği), ardından metin parçaları içeren delta olayları, en sonda done ya da error.

import json, os
import requests

with requests.post(
    "https://api.helovo.com/v1/chat",
    headers={"Authorization": f"Bearer {os.environ['HELOVO_API_KEY']}"},
    json={"bot_id": "bot_…", "message": "Merhaba", "stream": True},
    stream=True,
    timeout=90,
) as res:
    event = None
    for line in res.iter_lines(decode_unicode=True):
        if line.startswith("event: "):
            event = line[7:]
        elif line.startswith("data: ") and event == "delta":
            print(json.loads(line[6:])["text"], end="", flush=True)

Güvenlik kuralları

• Anahtarı asla tarayıcı ya da mobil uygulama koduna koymayın. Uygulamanız kendi sunucunuza istek atsın, sunucunuz Helovo API'yi çağırsın. Helovo API zaten tarayıcıdan gelen (CORS) istekleri kabul etmez.
• Anahtarları kısıtlayın: Her entegrasyon için ayrı anahtar oluşturun ve yalnızca gereken chatbotlara yetki verin.
• Anahtarı ortam değişkeninde saklayın, kod deposuna eklemeyin. Sızdığından şüphelenirseniz panelden iptal edip yenisini oluşturun.

Hatalar ve limitler

Hatalar {"error": {"code": "…", "message": "…"}} biçiminde döner. En sık karşılaşacaklarınız:

• 401 invalid_api_key: Anahtar hatalı, iptal edilmiş ya da süresi dolmuş.
• 404 chatbot_not_found: Chatbot yok ya da anahtarın o chatbota yetkisi yok.
• 429 rate_limited ya da quota_exceeded: Dakikalık limit ya da aylık kota doldu. Retry-After başlığındaki süre kadar bekleyin.

Her cevapta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur. Tüm hata kodları ve alanlar geliştirici sayfasındaki dokümantasyonda, makinece okunabilir tanım ise OpenAPI dosyasında.

Asistan API'de de aynı kurallarla çalışır

API üzerinden gelen mesajlar da web sitesindeki widget ile aynı kurallara tabidir: asistan yalnızca sizin yazdığınız bilgilerle yanıt verir, konu dışı istekleri geri çevirir ve kendini işletmenizin asistanı olarak tanıtır. Talimatları nasıl yazacağınız için chatbot talimatı şablonlarımıza bakabilirsiniz.

Sık sorulan sorular

Hangi programlama dilleriyle kullanabilirim?

HTTP isteği gönderebilen her dille: JavaScript (Node.js), Python, PHP, Go, Java, C# ve diğerleri. SDK kurmanız gerekmez.

API ile başlayan konuşmaları panelde görebilir miyim?

Evet. API konuşmaları da panelde listelenir ve kaynağa göre filtrelenebilir.

API'yi ücretsiz deneyebilir miyim?

Chatbotu kurup panelde ücretsiz test edebilirsiniz; API istekleri ücretli planda açılır.