Developers
Quickstart
Get a key, make your first request, then build a bot end to end with the API: channel, knowledge source, AI test, automation, webhook and message.
1. Get an API key
- Open Settings → API in the dashboard (the API is available on Pro and higher plans).
- Create a new key. For this guide choose the
Full managementaccess level; in production, grant only what the integration needs. - The key is shown only once at creation, so save it. Don't put it in source code; keep it in an environment variable.
export HIBOTY_API_KEY="hb_live_YOUR_API_KEY"
export TELEGRAM_BOT_TOKEN="YOUR_BOTFATHER_TOKEN"2. Install an SDK (optional)
The JavaScript and Python samples use the SDK; curl needs no setup.
npm install @hiboty/sdk3. Make your first request
The response has the form { data, next_cursor }. If you get 401, check the key; if you get 403 plan_limit, check your plan.
curl "https://hiboty.com/api/v1/bots?limit=5" \
-H "Authorization: Bearer $HIBOTY_API_KEY"4. Build a bot from scratch in 5 minutes
The steps run in order: each one uses the bot ID created earlier. Get the Telegram token from BotFather.
1. Create the bot
The bot starts as a draft. If you pass
template, the persona, welcome message and FAQs come from the gallery template. When the plan's bot limit is reached you get403 plan_limit.Scope:
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":"Store Assistant","channel":"telegram","template":"eticaret","language":"tr"}' \ | jq -r '.data.id') echo "$BOT_ID"2. Connect the Telegram token
The token is validated and stored encrypted, and the Telegram webhook is set up for you; responses never contain the token. On a WhatsApp bot, send
phone_number_id,business_account_idandaccess_token.Scope:
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. Add a knowledge source
The AI answers from this source.
type:text,faq,urlorfile.Scope:
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":"Shipping time","question":"When will my order arrive?","answer":"Orders ship within 1-3 business days."}'4. Try an AI reply
Nothing goes to customers and no conversation opens; the reply counts against the AI quota as a test.
Scope:
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":"When will my order arrive?"}]}'5. Add an automation
The automation starts disabled and is validated with the same rules as the dashboard. Send
active: trueto turn it on. This sample replies to messages containing "fiyat" (price).Scope:
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\":\"Price question\",\"trigger\":\"anahtar_kelime\",\"trigger_config\":{\"kelimeler\":[\"fiyat\"],\"eslesme\":\"icerir\",\"aiBastir\":true,\"tekrarGun\":0},\"steps\":[{\"tur\":\"mesaj\",\"metin\":\"Our price list: 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. Set up a webhook
Receive events in your own system. The signing secret (
secret) is returned only in this response, so store it right away. The address must be public https.Scope:
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. Send a message
The contact must have messaged the bot first: send your bot a message on Telegram so the contact appears in the list.
Idempotency-Keyprevents duplicates on retries. A real message goes to the customer.Scope:
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\":\"Hello!\"}"
End to end in one file
All of the steps above. Before running it, replace https://ornek.com/hiboty-webhook with your own address.
#!/usr/bin/env bash
set -euo pipefail
# You need: 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":"Store Assistant","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":"Shipping time","question":"When will my order arrive?","answer":"Orders ship within 1-3 business days."}'
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":"When will my order arrive?"}]}'
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\":\"Price question\",\"trigger\":\"anahtar_kelime\",\"trigger_config\":{\"kelimeler\":[\"fiyat\"],\"eslesme\":\"icerir\",\"aiBastir\":true,\"tekrarGun\":0},\"steps\":[{\"tur\":\"mesaj\",\"metin\":\"Our price list: 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\":\"Hello!\"}"
Common recipes
WhatsApp template message
On WhatsApp, free-form text can't be sent once 24 hours have passed since the contact's last message; use a Meta-approved template for transactional notifications such as orders, shipping or appointments. It is only sent to contacts who opted in (opted_in). params fill the {{1}}, {{2}} placeholders of the header and body in order; their count must match the template. {{isim}} and custom field keys (such as {{sehir}}) in the values are filled per contact.
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" }Possible errors: template_unsupported (the bot isn't WhatsApp), consent_required (no consent), template_not_found (no approved template), template_params (parameter count mismatch).
Contact and conversation management
Tag a contact from your CRM, then hand the conversation over to an agent.
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":"Jane Smith","add_tags":["vip"],"notes":"Asked for a business quote","attributes":{"sehir":"Izmir","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" } }Campaign audience (segment)
Conditions are combined with AND: include_tags, exclude_tags, match (any, all), last_seen (within_days or older_than_days), order (placed, none), source (acquisition source codes; "-" for contacts without a link) and fields (custom field conditions). If segment is omitted, all of the bot's consenting contacts are selected. An unknown field, invalid value or empty filter returns 400; if no contact matches the filter you get 409 empty_audience and the campaign never falls back to the whole audience.
{
"bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "VIP",
"body": "Hello {{ad}}, a special offer for you!",
"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": "Izmir" }]
}
}The API creates the campaign, but sending only starts after an admin approves it in the dashboard.