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 management access 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.
Environment variables
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/sdk

3. 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. 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 get 403 plan_limit.

    Scope: 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":"Store Assistant","channel":"telegram","template":"eticaret","language":"tr"}' \
      | jq -r '.data.id')
    echo "$BOT_ID"
  2. 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_id and access_token.

    Scope: 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. Add a knowledge source

    The AI answers from this source. type: text, faq, url or file.

    Scope: 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":"Shipping time","question":"When will my order arrive?","answer":"Orders ship within 1-3 business days."}'
  4. 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: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":"When will my order arrive?"}]}'
  5. 5. Add an automation

    The automation starts disabled and is validated with the same rules as the dashboard. Send active: true to turn it on. This sample replies to messages containing "fiyat" (price).

    Scope: 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\":\"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. 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: 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. 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-Key prevents duplicates on retries. A real message goes to the customer.

    Scope: 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\":\"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
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"]}}'
Response
{ "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
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"}'
Response
{ "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.

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

Next steps