Geliştiriciler için

Chatbot API: aynı asistan, kendi uygulamanızda.

Helovo'da kurduğunuz yapay zeka asistanını tek bir REST uç noktasıyla kendi uygulamanızdan, botunuzdan ya da iç araçlarınızdan kullanın. Asistanın bilgisini ve kurallarını panelden yönetirsiniz; kodunuz yalnızca mesajı gönderip cevabı alır.

Ücretsiz hesap aç Dokümantasyona geç OpenAPI tanımı →

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

Neden Helovo API?

Tek uç nokta

POST /v1/chat ile mesajı gönderin, cevabı JSON olarak alın. SDK kurmanız gerekmez.

Akan cevap (SSE)

"stream": true ile cevap Server-Sent Events olarak parça parça gelir; kullanıcı yazılırken okur.

Konuşma hafızası

conversation_id ile konuşmaya devam edin; önceki mesajları siz saklamak zorunda değilsiniz.

Panelden yönetilen bilgi

Asistanın talimatlarını, üslubunu ve dilini panelden değiştirin; kodunuza dokunmadan güncellenir.

Chatbot bazında anahtarlar

Bir API anahtarını tüm chatbotlara ya da yalnızca seçtiklerinize yetkilendirin, gerektiğinde iptal edin.

Aynı güvenlik kuralları

Asistan API'de de konu dışına çıkmaz, bilmediğini uydurmaz ve kendini işletmenizin asistanı olarak tanıtır.

Neler yapabilirsiniz?

Mobil uygulamanıza müşteri destek asistanı ekleyin
Kendi yazdığınız Telegram, Discord ya da mesajlaşma botuna cevap üretin
Müşterileriniz için site yapan bir ajanssanız, onların asistanlarını kendi panelinize bağlayın
CRM ya da destek aracınızda gelen soruya taslak cevap hazırlayın
Kiosk, tablet menü ya da iç araçlarda şirket bilgisiyle cevap veren asistan kullanın

Üç adımda ilk istek

1
Chatbotu oluşturun
Hesap açın, işletme bilgilerini ve talimatları yazın, panelde test edin.
2
API anahtarı alın
Panelde API sayfasından anahtar oluşturun. Anahtar yalnızca bir kez gösterilir.
3
İstek gönderin
Anahtarı sunucunuzda saklayın ve POST /v1/chat'e bot_id ile mesajı gönderin.

Dokümantasyon

Tek bir uç nokta ile chatbotunuza mesaj gönderin ve cevabı alın.

Kimlik doğrulama

Her isteğe Authorization: Bearer sk_… başlığını ekleyin. API yalnızca sunucudan sunucuya kullanım içindir; tarayıcıdan yapılan istekler (CORS) kabul edilmez. Web sitenizde ziyaretçilerle sohbet için widget'ı kullanın.

POST`https://api.helovo.com/v1/chat`

Alan	Tür	Açıklama
bot_id*	string	Chatbotun kimliği (Chatbot → Kurulum sekmesinde yazar).
message*	string	Kullanıcının mesajı, en fazla 4.000 karakter.
conversation_id	string	Mevcut bir konuşmaya devam etmek için. Boşsa yeni konuşma başlar.
user	string	Kendi sisteminizdeki kullanıcı kimliği; konuşmalarda görünür (en fazla 128 karakter).
stream	boolean	true ise cevap Server-Sent Events ile parça parça gelir.

İstek

curl https://api.helovo.com/v1/chat \
  -H "Authorization: Bearer $HELOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "bot_id": "bot_…",
    "message": "Merhaba",
    "user": "musteri-42"
  }'

Cevap

{
  "id": "msg_01J…",
  "conversation_id": "conv_01J…",
  "answer": "Merhaba, size nasıl yardımcı olabilirim?",
  "model": "standard",
  "finish_reason": "stop",
  "usage": { "input_tokens": 142, "output_tokens": 18 }
}

Akan cevap (stream)

"stream": true ile cevap Server-Sent Events olarak gelir: meta → delta (metin parçaları) → done ya da error.

curl -N https://api.helovo.com/v1/chat \
  -H "Authorization: Bearer $HELOVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "bot_id": "bot_…", "message": "Merhaba", "stream": true }'

Diğer uç noktalar

GET /v1/chatbots — Anahtarın erişebildiği chatbotlar.
GET /v1/conversations/{id} — API ile başlatılmış bir konuşmanın mesajları.

Hatalar ve limitler

Hatalar {"error": {"code": "…", "message": "…", "request_id": "…"}} biçiminde döner. Her cevapta X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıkları bulunur.

400	invalid_request	Geçersiz JSON veya bilinmeyen alan.
401	missing_api_key / invalid_api_key	Anahtar yok, geçersiz, iptal edilmiş veya süresi dolmuş.
404	chatbot_not_found / conversation_not_found	Kaynak yok ya da bu anahtarın erişimi dışında.
409	chatbot_paused	Chatbot duraklatılmış.
422	validation_error	Mesaj boş veya çok uzun.
429	rate_limited / quota_exceeded	Dakikalık limit veya aylık kota aşıldı. Retry-After başlığına bakın.
502–504	ai_error / ai_not_configured / ai_timeout	Asistan yanıt veremedi; tekrar deneyin.

Limitler ve fiyat

API ücretli planda açıktır: ayda 5.000 API isteği ve dakikada 60 istek.
Ücretli plan haftalık, aylık ya da yıllık ödenir; ayrıca kullanıcı başı ya da token başı ücret yoktur.
API yalnızca sunucudan sunucuya kullanım içindir; anahtarı tarayıcı koduna koymayın. Web sitesindeki ziyaretçiler için tek satırlık widget'ı kullanın.

Fiyatları gör →

Sık sorulan sorular

Helovo'nun chatbot API'si var mı?

Evet. Helovo'da kurduğunuz her chatbotu REST API ile kendi uygulamanızdan kullanabilirsiniz: POST /v1/chat ile mesaj gönderir, cevabı JSON ya da Server-Sent Events olarak alırsınız.

Hangi dillerle kullanabilirim?

HTTP isteği gönderebilen her dille: cURL, JavaScript (Node.js), Python, PHP, Go, Java ve diğerleri. Dokümantasyonda cURL, JavaScript ve Python örnekleri var.

API'yi tarayıcıdan doğrudan çağırabilir miyim?

Hayır. API anahtarınızın gizli kalması için API yalnızca sunucudan sunucuya kullanılır; tarayıcı istekleri kabul edilmez. Web sitenizdeki ziyaretçiler için widget'ı kullanın.

API ile gelen konuşmaları görebilir miyim?

Evet. API üzerinden başlayan konuşmalar panelde de görünür; user alanına kendi kullanıcı kimliğinizi gönderirseniz konuşmayı kimin başlattığını görürsünüz.

API ücretsiz planda çalışır mı?

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

Adım adım anlatım için chatbot API rehberimiz. Daha fazla soru için sık sorulan sorular.