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önetim seç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.
Ortam değişkenleri
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/sdk

3. İ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. 1. Botu oluşturun

    Bot taslak olarak açılır. template verirseniz persona, karşılama ve SSS galeri şablonundan gelir. Plan bot sınırı dolarsa 403 plan_limit döner.

    Kapsam: bots:write

    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"
  2. 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_id ve access_token gönderilir.

    Kapsam: bots:write

    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\"}"
  3. 3. Bilgi kaynağı ekleyin

    AI bu kaynaktan yanıt verir. type: text, faq, url ya da file.

    Kapsam: bots:write

    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."}'
  4. 4. AI yanıtını deneyin

    Müşteriye mesaj gitmez, sohbet açılmaz; yanıt test olarak AI kotasından düşer.

    Kapsam: bots:write

    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?"}]}'
  5. 5. Otomasyon ekleyin

    Otomasyon kapalı başlar, panelle aynı kurallarla doğrulanır. Etkinleştirmek için active: true gönderin. Bu örnek "fiyat" geçen mesaja yanıt verir.

    Kapsam: automations:write, write

    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}'
  6. 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: write

    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"]}'
  7. 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-Key yeniden denemede çift mesajı önler. Müşteriye gerçek mesaj gider.

    Kapsam: read, messages:send

    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!\"}"

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
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"]}}'
Yanıt
{ "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
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"}'
Yanıt
{ "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.

JSON
{
  "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.

Sonraki adımlar