Geliştiriciler
Hızlı başlangıç
Anahtar alın, ilk isteği atın, ardından botu API ile baştan sona kurun: kanal, bilgi kaynağı, AI testi, otomasyon, webhook ve mesaj.
1. API anahtarı alın
- Panelde Ayarlar → API bölümünü açın (API, Pro ve üzeri planlarda açıktır).
- Yeni anahtar oluşturun. Bu rehber için erişim düzeyi olarak
Tam yönetimseçin; üretimde entegrasyonun ihtiyacı kadar yetki verin. - Anahtar yalnız oluşturulduğu anda gösterilir, kaydedin. Kaynak koda yazmayın, ortam değişkeninde tutun.
export HIBOTY_API_KEY="hb_live_YOUR_API_KEY"
export TELEGRAM_BOT_TOKEN="YOUR_BOTFATHER_TOKEN"2. SDK'yi kurun (isteğe bağlı)
JavaScript ve Python örnekleri SDK'yi kullanır; curl için kurulum gerekmez.
npm install @hiboty/sdk3. İlk isteği atın
Yanıt { data, next_cursor } biçimindedir. 401 alırsanız anahtarı, 403 plan_limit alırsanız planınızı denetleyin.
curl "https://hiboty.com/api/v1/bots?limit=5" \
-H "Authorization: Bearer $HIBOTY_API_KEY"4. 5 dakikada API ile sıfırdan bot
Adımlar sırayla çalışır: her adım önceki adımda oluşan bot kimliğini kullanır. Telegram jetonunu BotFather'dan alın.
1. Botu oluşturun
Bot taslak olarak açılır.
templateverirseniz persona, karşılama ve SSS galeri şablonundan gelir. Plan bot sınırı dolarsa403 plan_limitdöner.Kapsam:
bots:writeBOT_ID=$(curl -s -X POST "https://hiboty.com/api/v1/bots" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"name":"Mağaza Asistanı","channel":"telegram","template":"eticaret","language":"tr"}' \ | jq -r '.data.id') echo "$BOT_ID"2. Telegram jetonunu bağlayın
Jeton doğrulanır, şifreli saklanır ve Telegram webhook'u kendiliğinden kurulur; yanıtlarda jeton dönmez. WhatsApp botunda
phone_number_id,business_account_idveaccess_tokengönderilir.Kapsam:
bots:writecurl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/connect" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"token\":\"$TELEGRAM_BOT_TOKEN\"}"3. Bilgi kaynağı ekleyin
AI bu kaynaktan yanıt verir.
type:text,faq,urlya dafile.Kapsam:
bots:writecurl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/knowledge" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"type":"faq","title":"Kargo süresi","question":"Kargom ne zaman gelir?","answer":"Siparişler 1-3 iş günü içinde kargoya verilir."}'4. AI yanıtını deneyin
Müşteriye mesaj gitmez, sohbet açılmaz; yanıt test olarak AI kotasından düşer.
Kapsam:
bots:writecurl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/ai-test" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"Kargom ne zaman gelir?"}]}'5. Otomasyon ekleyin
Otomasyon kapalı başlar, panelle aynı kurallarla doğrulanır. Etkinleştirmek için
active: truegönderin. Bu örnek "fiyat" geçen mesaja yanıt verir.Kapsam:
automations:write, writeAUTOMATION_ID=$(curl -s -X POST "https://hiboty.com/api/v1/automations" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"bot_id\":\"$BOT_ID\",\"name\":\"Fiyat sorusu\",\"trigger\":\"anahtar_kelime\",\"trigger_config\":{\"kelimeler\":[\"fiyat\"],\"eslesme\":\"icerir\",\"aiBastir\":true,\"tekrarGun\":0},\"steps\":[{\"tur\":\"mesaj\",\"metin\":\"Fiyat listemiz: https://ornek.com/fiyat\"}]}" \ | jq -r '.data.id') curl -X PATCH "https://hiboty.com/api/v1/automations/$AUTOMATION_ID" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"active":true}'6. Webhook kurun
Olayları kendi sisteminize alın. İmza sırrı (
secret) yalnız bu yanıtta döner, hemen saklayın. Adres herkese açık https olmalıdır.Kapsam:
writecurl -X POST "https://hiboty.com/api/v1/webhooks" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"url":"https://ornek.com/hiboty-webhook","events":["message.received","conversation.handoff"]}'7. Mesaj gönderin
Kişi daha önce bota yazmış olmalıdır: Telegram'da botunuza bir mesaj atın, kişi listede görünsün.
Idempotency-Keyyeniden denemede çift mesajı önler. Müşteriye gerçek mesaj gider.Kapsam:
read, messages:sendTO=$(curl -s "https://hiboty.com/api/v1/contacts?bot_id=$BOT_ID&limit=1" \ -H "Authorization: Bearer $HIBOTY_API_KEY" | jq -r '.data[0].external_id') curl -X POST "https://hiboty.com/api/v1/messages" \ -H "Authorization: Bearer $HIBOTY_API_KEY" \ -H "Idempotency-Key: welcome-$TO" \ -H "Content-Type: application/json" \ -d "{\"bot_id\":\"$BOT_ID\",\"to\":\"$TO\",\"message\":\"Merhaba!\"}"
Tek dosyada baştan sona
Yukarıdaki adımların tamamı. Çalıştırmadan önce https://ornek.com/hiboty-webhook adresini kendi adresinizle değiştirin.
#!/usr/bin/env bash
set -euo pipefail
# Gerekenler: curl, jq, HIBOTY_API_KEY, TELEGRAM_BOT_TOKEN
BOT_ID=$(curl -s -X POST "https://hiboty.com/api/v1/bots" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Mağaza Asistanı","channel":"telegram","template":"eticaret","language":"tr"}' \
| jq -r '.data.id')
echo "$BOT_ID"
curl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/connect" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"token\":\"$TELEGRAM_BOT_TOKEN\"}"
curl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/knowledge" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"faq","title":"Kargo süresi","question":"Kargom ne zaman gelir?","answer":"Siparişler 1-3 iş günü içinde kargoya verilir."}'
curl -X POST "https://hiboty.com/api/v1/bots/$BOT_ID/ai-test" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"messages":[{"role":"user","content":"Kargom ne zaman gelir?"}]}'
AUTOMATION_ID=$(curl -s -X POST "https://hiboty.com/api/v1/automations" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"bot_id\":\"$BOT_ID\",\"name\":\"Fiyat sorusu\",\"trigger\":\"anahtar_kelime\",\"trigger_config\":{\"kelimeler\":[\"fiyat\"],\"eslesme\":\"icerir\",\"aiBastir\":true,\"tekrarGun\":0},\"steps\":[{\"tur\":\"mesaj\",\"metin\":\"Fiyat listemiz: https://ornek.com/fiyat\"}]}" \
| jq -r '.data.id')
curl -X PATCH "https://hiboty.com/api/v1/automations/$AUTOMATION_ID" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"active":true}'
curl -X POST "https://hiboty.com/api/v1/webhooks" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://ornek.com/hiboty-webhook","events":["message.received","conversation.handoff"]}'
TO=$(curl -s "https://hiboty.com/api/v1/contacts?bot_id=$BOT_ID&limit=1" \
-H "Authorization: Bearer $HIBOTY_API_KEY" | jq -r '.data[0].external_id')
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: welcome-$TO" \
-H "Content-Type: application/json" \
-d "{\"bot_id\":\"$BOT_ID\",\"to\":\"$TO\",\"message\":\"Merhaba!\"}"
Sık kullanılan tarifler
WhatsApp şablon mesajı
WhatsApp'ta kişinin son mesajından 24 saat geçtiyse serbest metin gönderilemez; sipariş, kargo veya randevu gibi işlemsel bildirimler için Meta onaylı bir şablon kullanın. Yalnız iletişim izni veren (opted_in) kişiye gönderilir. params sırasıyla başlık ve gövdedeki {{1}}, {{2}} yerlerini doldurur; sayısı şablonla eşleşmelidir. Değerlerde {{isim}} ve özel alan anahtarları ({{sehir}} gibi) kişiye göre doldurulur.
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"905321234567","template":{"name":"siparis_kargoda","language":"tr","params":["{{isim}}","HB-10482"]}}'{ "id": "…", "status": "sent", "bot_id": "…", "to": "905321234567", "template": "siparis_kargoda" }Olası hatalar: template_unsupported (bot WhatsApp değil), consent_required (izin yok), template_not_found (onaylı şablon yok), template_params (parametre sayısı uymuyor).
Kişi ve sohbet yönetimi
CRM'inizden kişiyi etiketleyin, ardından sohbeti temsilciye devredin.
curl -X PATCH "https://hiboty.com/api/v1/contacts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Ayşe Yılmaz","add_tags":["vip"],"notes":"Kurumsal teklif istedi","attributes":{"sehir":"İzmir","butce":1500}}'
curl -X POST "https://hiboty.com/api/v1/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/status" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"status":"handoff"}'{ "data": { "id": "…", "status": "handoff", "previous_status": "open" } }Kampanya kitlesi (segment)
Koşullar VE ile birleşir: include_tags, exclude_tags, match (any, all), last_seen (within_days ya da older_than_days), order (placed, none), source (edinme kaynağı kodları; "-" bağlantısız gelenler) ve fields (özel alan koşulları). segment hiç gönderilmezse botun tüm izinli kişileri seçilir. Bilinmeyen alan, geçersiz değer ya da içi boş süzgeç 400 döner; süzgece uyan kişi yoksa 409 empty_audience döner, kampanya tüm kitleye düşmez.
{
"bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "VIP",
"body": "Merhaba {{ad}}, size özel fırsat!",
"segment": {
"include_tags": ["vip"],
"exclude_tags": ["test"],
"match": "any",
"last_seen": { "within_days": 30 },
"order": "placed",
"source": ["instagram"],
"fields": [{ "key": "sehir", "type": "text", "op": "eq", "value": "İzmir" }]
}
}Kampanyayı API oluşturur ama gönderim yalnız panelde yönetici onayıyla başlar.