API reference

Bots

68 endpoints in this group.

Lists the organization's bots

GET/api/v1/bots

Scope
read
SDK method
listBots · list_bots
MCP tool
listBotsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 100); 400 if it isn't an integerval 1–200, default 100
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "telegram",
      "status": "string",
      "telegram_username": "string",
      "whatsapp_phone": "string",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Creates a bot

POST/api/v1/bots

The plan's bot limit applies, as in the dashboard (403 plan_limit). With template, omitted persona, welcome message, handoff keyword and faqs come from the gallery template (language: template language). The bot starts as a draft; connect it with connectBot. Scope: bots:write.

Scope
bots:write
SDK method
createBot · create_bot
MCP tool
createBot

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
namestringyeslen 2–80
channelenumyestelegram | whatsapp
templateenumnoGallery template (listBotTemplates)eticaret | restoran | randevu | egitim | destek | guzellik | klinik | emlak | otel | otomotiv | etkinlik | spor
languageenumnoTemplate and FAQ language; the request's language if omittedtr | en
faqsobject[]noReplaces the template's FAQs when givenitems ≤ 10
faqs[].questionstringyeslen 2–160
faqs[].answerstringyeslen 1–2000
personastringnolen ≤ 6000
welcome_messagestringnolen ≤ 1000
handoff_keywordstringnolen 2–40
ai_enabledbooleannodefault true
voice_transcriptionbooleannodefault false
image_understandingbooleannodefault false
ai_toolsbooleannodefault true

Example request

curl -X POST "https://hiboty.com/api/v1/bots" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"Store Assistant","channel":"telegram","template":"eticaret","language":"tr"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limit
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists gallery templates

GET/api/v1/bots/templates

Template codes for createBot. Scope: bots:read.

Scope
bots:read
SDK method
listBotTemplates · list_bot_templates
MCP tool
listBotTemplatesread-only

Parameters

NameTypeRequiredDescription
sectorqueryenumnoSector filterperakende | yeme_icme | hizmet | saglik | emlak | turizm | egitim | genel
languagequeryenumnoText language; the request's language if omittedtr | en

Example request

curl -X GET "https://hiboty.com/api/v1/bots/templates" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "code": "ornek",
      "sector": "string",
      "name": "Hiboty",
      "description": "string",
      "persona": "string",
      "welcome_message": "string",
      "handoff_keyword": "string",
      "faqs": [
        {
          "question": "string",
          "answer": "string"
        }
      ]
    }
  ]
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Generates a bot draft with AI (saves nothing)

POST/api/v1/bots/draft

Suggests a persona, welcome message and FAQs from a description or website; save the result with createBot. The website passes the SSRF check. Counts against the AI quota. Scope: bots:write.

Scope
bots:write
SDK method
createBotDraft · create_bot_draft
MCP tool
createBotDraftexternal effect

Body fields

NameTypeRequiredDescription
descriptionstringnolen ≤ 3000
websitestringnolen ≤ 2000

Example request

curl -X POST "https://hiboty.com/api/v1/bots/draft" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"An online store selling handmade ceramics in Istanbul.","website":"https://ornek.com"}'

Example response (200)

JSON
{
  "data": {
    "persona": "string",
    "welcome_message": "string",
    "faqs": [
      {
        "question": "string",
        "answer": "string"
      }
    ],
    "website_error": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Creates a new draft bot from a bot file

POST/api/v1/bots/import

The file is validated from scratch, no channel is connected and tools start disabled. Tool signing secrets are returned only in this response. The plan's bot limit applies. Scope: bots:write.

Scope
bots:write
SDK method
importBot · import_bot
MCP tool
importBot

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
fileobject | stringyesThe file returned by exportBot (object or JSON text), up to 512 KB

Example request

curl -X POST "https://hiboty.com/api/v1/bots/import" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"file":{"tur":"hiboty.bot","surum":1}}'

Example response (201)

JSON
{
  "data": {
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "knowledge_count": 1,
    "tools": [
      {
        "name": "Hiboty",
        "signing_secret": "string"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Validates a bot file without saving

POST/api/v1/bots/import/preview

Returns what would be created, the addresses in the file and fields with invisible characters. Scope: bots:write.

Scope
bots:write
SDK method
previewBotImport · preview_bot_import
MCP tool
previewBotImport

Body fields

NameTypeRequiredDescription
fileobject | stringyesThe file returned by exportBot (object or JSON text), up to 512 KB

Example request

curl -X POST "https://hiboty.com/api/v1/bots/import/preview" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":{"tur":"hiboty.bot","surum":1}}'

Example response (200)

JSON
{
  "data": {
    "name": "Hiboty",
    "channel": "telegram",
    "knowledge_count": 1,
    "tool_count": 1,
    "addresses": [
      {
        "type": "tool",
        "name": "Hiboty",
        "url": "https://example.com/hook",
        "has_query": true
      }
    ],
    "invisible_character_fields": [
      "string"
    ],
    "oversized_sources": [
      "string"
    ],
    "bot_count": 1,
    "bot_limit": 1,
    "bot": {
      "persona": "string",
      "welcome_message": "string",
      "handoff_keyword": "string",
      "ai_enabled": true,
      "ai_tools": true,
      "voice_transcription": true,
      "image_understanding": true
    },
    "knowledge": [
      {
        "type": "text",
        "title": "Example",
        "url": "https://example.com/hook",
        "content": "string"
      }
    ],
    "tools": [
      {
        "name": "Hiboty",
        "description": "string",
        "url": "https://example.com/hook",
        "fields": [
          {
            "name": "Hiboty",
            "type": "string",
            "required": false,
            "description": "string",
            "options": []
          }
        ]
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Bot details

GET/api/v1/bots/{id}

Tokens and secrets are never returned; only the connected flag is. Scope: bots:read.

Scope
bots:read
SDK method
getBot · get_bot
MCP tool
getBotread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates bot and AI settings

PATCH/api/v1/bots/{id}

Only the fields you send change; the previous state is kept as a version (listBotVersions). Scope: bots:write.

Scope
bots:write
SDK method
updateBot · update_bot
MCP tool
updateBot

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Body fields

NameTypeRequiredDescription
namestringnolen 2–80
personastringnolen ≤ 6000
welcome_messagestringnolen ≤ 1000
handoff_keywordstringnolen 2–40
ai_enabledbooleanno
voice_transcriptionbooleanno
image_understandingbooleanno
ai_toolsbooleanno
voice_replyenumnoVoice reply (TTS) setting; not included in the version history.kapali | sesliye_sesli | her_zaman
reply_languageenumnoFixed reply language; null means automatic. Not included in the version history.tr | en | de | fr | es | it | pt | nl | ru | ar | az | null
appointment_toolbooleannoAppointment request tool; not included in the version history.
cancel_request_toolbooleannoOrder cancellation request tool; not included in the version history.
show_source_linksbooleannoShow the source link to customers; not included in the version history.

Example request

curl -X PATCH "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"persona":"You are a sales assistant who gives short, clear answers.","ai_enabled":true}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a bot

DELETE/api/v1/bots/{id}

Irreversible; its contacts and conversations are deleted too. As in the dashboard, it needs owner permission (403 forbidden_role). Scope: bots:write.

Scope
bots:write
SDK method
deleteBot · delete_bot
MCP tool
deleteBotexternal effectirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.forbidden_role
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Connects a bot to its channel

POST/api/v1/bots/{id}/connect

Telegram: token. WhatsApp Cloud API: phone_number_id, business_account_id, access_token and (if none is stored) app_secret; you can set your own webhook_verify_token for Meta's webhook check, and it's never returned. Details get the same validation as the dashboard, are stored encrypted, and the Telegram webhook is set up. Responses and errors contain no secret values. warning: whatsapp_subscription_failed means the connection was saved but the app couldn't subscribe to the WABA. Scope: bots:write.

Scope
bots:write
SDK method
connectBot · connect_bot
MCP tool
connectBotexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
tokenstringnoToken from BotFather
phone_number_idstringno
business_account_idstringno
access_tokenstringnolen ≥ 20
app_secretstringno
webhook_verify_tokenstringnoThe value you choose for Meta's webhook check; never returned in a responselen 16–128
business_idstringnoOptional Meta business portfolio ID; written to the WhatsApp account (WABA) record

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/connect" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"token":"123456789:AAExampleExampleExampleExampleExample"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "warning": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Removes the channel connection

POST/api/v1/bots/{id}/disconnect

The Telegram webhook and the tokens are deleted and the bot returns to draft; contacts and conversations are kept. Returns 409 not_connected if it isn't connected. Scope: bots:write.

Scope
bots:write
SDK method
disconnectBot · disconnect_bot
MCP tool
disconnectBotexternal effectirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/disconnect" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Pauses a bot

POST/api/v1/bots/{id}/pause

Scope: bots:write.

Scope
bots:write
SDK method
pauseBot · pause_bot
MCP tool
pauseBotexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/pause" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Resumes a bot

POST/api/v1/bots/{id}/resume

Returns 409 not_connected if the channel isn't connected. Scope: bots:write.

Scope
bots:write
SDK method
resumeBot · resume_bot
MCP tool
resumeBotexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/resume" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "channel": "telegram",
    "status": "draft",
    "connected": true,
    "persona": "string",
    "welcome_message": "string",
    "handoff_keyword": "string",
    "ai_enabled": true,
    "voice_transcription": true,
    "image_understanding": true,
    "ai_tools": true,
    "voice_reply": "kapali",
    "reply_language": "tr",
    "appointment_tool": true,
    "cancel_request_tool": true,
    "show_source_links": true,
    "telegram_username": "string",
    "whatsapp_phone": "string",
    "whatsapp_phone_number_id": "string",
    "whatsapp_business_account_id": "string",
    "whatsapp_embedded": true,
    "whatsapp_app_secret_set": true,
    "webhook_url": "https://example.com/a.png",
    "webhook_verified_at": "2026-11-06T09:00:00.000Z",
    "last_webhook_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "whatsapp_quality": "GREEN",
    "whatsapp_messaging_limit": "string",
    "whatsapp_quality_at": "2026-11-06T09:00:00.000Z",
    "delivery_score": 0,
    "delivery_score_reasons": [
      "veri_az"
    ],
    "delivery_score_at": "2026-11-06T09:00:00.000Z",
    "whatsapp_account_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Go-live readiness check

GET/api/v1/bots/{id}/readiness

Scope: bots:read.

Scope
bots:read
SDK method
getBotReadiness · get_bot_readiness
MCP tool
getBotReadinessread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/readiness" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "ready": true,
    "items": [
      {
        "key": "sehir",
        "status": "tamam",
        "group": "kanal",
        "count": [
          1
        ]
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Exports the bot file

GET/api/v1/bots/{id}/export

Configuration, knowledge sources and tool definitions; channel details and secrets are left out. Needs admin permission. Scope: bots:read.

Scope
bots:read
SDK method
exportBot · export_bot
MCP tool
exportBotread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/export" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "file_name": "string",
    "file": {},
    "knowledge_count": 1,
    "tool_count": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Tries an AI reply

POST/api/v1/bots/{id}/ai-test

Nothing is sent to contacts and no conversation opens; the reply counts against the AI quota as a test. The last 20 messages are used. Scope: bots:write.

Scope
bots:write
SDK method
testBotReply · test_bot_reply
MCP tool
testBotReply

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Body fields

NameTypeRequiredDescription
messagesobject[]yesitems 1–50
messages[].roleenumyesuser | assistant
messages[].contentstringyeslen 1–4000

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/ai-test" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"When will my order arrive?"}]}'

Example response (200)

JSON
{
  "data": {
    "reply": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Lists knowledge sources

GET/api/v1/bots/{id}/knowledge

Returns length instead of content. Scope: bots:read.

Scope
bots:read
SDK method
listKnowledgeSources · list_knowledge_sources
MCP tool
listKnowledgeSourcesread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "text",
      "title": "Example",
      "length": 1,
      "url": "https://example.com/hook",
      "status": "string",
      "freshness": "taze",
      "last_error": "string",
      "fetched_at": "2026-11-06T09:00:00.000Z",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Adds a knowledge source

POST/api/v1/bots/{id}/knowledge

type: text (content), faq (question, answer), url (public page; private network addresses are rejected, 400 source_fetch_failed) or file (file_name and file_base64; UTF-8 text files only, up to 256 KB). Scope: bots:write.

Scope
bots:write
SDK method
createKnowledgeSource · create_knowledge_source
MCP tool
createKnowledgeSourceexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
typeenumyestext | faq | url | file
titlestringyeslen 2–160
contentstringnotype=textlen 10–60000
questionstringnotype=faqlen ≤ 500
answerstringnotype=faqlen ≤ 5000
urlurinotype=url; a public http/https pagelen ≤ 2000
file_namestringnotype=file; txt, md, csv, tsv, json, htmllen ≤ 200
file_base64stringnotype=file; base64 content of a UTF-8 text file, up to 256 KB

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -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."}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "text",
    "title": "Example",
    "length": 1,
    "url": "https://example.com/hook",
    "status": "string",
    "freshness": "taze",
    "last_error": "string",
    "fetched_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "content": "string",
    "question": "string",
    "answer": "string",
    "changed": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).source_fetch_failed
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

A knowledge source's content

GET/api/v1/bots/{id}/knowledge/{source_id}

Scope: bots:read.

Scope
bots:read
SDK method
getKnowledgeSource · get_knowledge_source
MCP tool
getKnowledgeSourceread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
source_idpathuuidyesSource ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "text",
    "title": "Example",
    "length": 1,
    "url": "https://example.com/hook",
    "status": "string",
    "freshness": "taze",
    "last_error": "string",
    "fetched_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "content": "string",
    "question": "string",
    "answer": "string",
    "changed": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates a knowledge source

PATCH/api/v1/bots/{id}/knowledge/{source_id}

Only the title changes on a URL source. An FAQ source needs question and answer. Scope: bots:write.

Scope
bots:write
SDK method
updateKnowledgeSource · update_knowledge_source
MCP tool
updateKnowledgeSource

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
source_idpathuuidyesSource ID

Body fields

NameTypeRequiredDescription
titlestringyeslen 2–160
contentstringnolen ≤ 60000
questionstringnolen ≤ 500
answerstringnolen ≤ 5000

Example request

curl -X PATCH "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Return policy","content":"You can return items within 14 days of delivery."}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "text",
    "title": "Example",
    "length": 1,
    "url": "https://example.com/hook",
    "status": "string",
    "freshness": "taze",
    "last_error": "string",
    "fetched_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "content": "string",
    "question": "string",
    "answer": "string",
    "changed": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a knowledge source

DELETE/api/v1/bots/{id}/knowledge/{source_id}

Scope: bots:write.

Scope
bots:write
SDK method
deleteKnowledgeSource · delete_knowledge_source
MCP tool
deleteKnowledgeSourceirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
source_idpathuuidyesSource ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Fetches a URL source again

POST/api/v1/bots/{id}/knowledge/{source_id}/refresh

Up to 20 per hour per organization. Scope: bots:write.

Scope
bots:write
SDK method
refreshKnowledgeSource · refresh_knowledge_source
MCP tool
refreshKnowledgeSourceexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
source_idpathuuidyesURL source ID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/knowledge/3fa85f64-5717-4562-b3fc-2c963f66afa6/refresh" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "type": "text",
    "title": "Example",
    "length": 1,
    "url": "https://example.com/hook",
    "status": "string",
    "freshness": "taze",
    "last_error": "string",
    "fetched_at": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "content": "string",
    "question": "string",
    "answer": "string",
    "changed": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists custom AI tools

GET/api/v1/bots/{id}/tools

The secret header value and signing secret are never returned. Scope: bots:read.

Scope
bots:read
SDK method
listBotTools · list_bot_tools
MCP tool
listBotToolsread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/tools?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "description": "string",
      "fields": [
        {
          "name": "Hiboty",
          "type": "string",
          "required": false,
          "description": "string",
          "options": [
            "string"
          ]
        }
      ],
      "url": "https://example.com/hook",
      "host": "string",
      "secret_header_name": "string",
      "enabled": true,
      "last_called_at": "2026-11-06T09:00:00.000Z",
      "last_status": 1,
      "signing_secret": "string"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Adds a custom AI tool

POST/api/v1/bots/{id}/tools

The address must be https; private network addresses are rejected. Up to 10 tools per bot. The signing secret (signing_secret) is returned only in this response. Scope: bots:write.

Scope
bots:write
SDK method
createBotTool · create_bot_tool
MCP tool
createBotToolexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
namestringyes
descriptionstringyeslen 10–1000
fieldsobject[]noitems ≤ 12
fields[].namestringyes
fields[].typeenumyesstring | number | boolean | enum
fields[].requiredbooleannodefault false
fields[].descriptionstringnolen ≤ 300
fields[].optionsstring[]noitems ≤ 20
urluriyesPublic https address
secret_header_namestringnolen ≤ 60
secret_header_valuestringnolen ≤ 2000
enabledbooleannodefault true

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/tools" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"stok_sorgula","description":"Checks product stock.","url":"https://ornek.com/stok","fields":[{"name":"urun_kodu","type":"string","required":true,"description":"Product code"}]}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "description": "string",
    "fields": [
      {
        "name": "Hiboty",
        "type": "string",
        "required": false,
        "description": "string",
        "options": [
          "string"
        ]
      }
    ],
    "url": "https://example.com/hook",
    "host": "string",
    "secret_header_name": "string",
    "enabled": true,
    "last_called_at": "2026-11-06T09:00:00.000Z",
    "last_status": 1,
    "signing_secret": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates a custom AI tool

PATCH/api/v1/bots/{id}/tools/{tool_id}

Only the fields you send change; the signing secret doesn't change, and the stored value is kept if secret_header_value is omitted. Scope: bots:write.

Scope
bots:write
SDK method
updateBotTool · update_bot_tool
MCP tool
updateBotToolexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
tool_idpathuuidyesTool ID

Body fields

NameTypeRequiredDescription
namestringno
descriptionstringno
fieldsobject[]noitems ≤ 12
fields[].namestringyes
fields[].typeenumyesstring | number | boolean | enum
fields[].requiredbooleannodefault false
fields[].descriptionstringnolen ≤ 300
fields[].optionsstring[]noitems ≤ 20
urlurino
secret_header_namestringno
secret_header_valuestringno
remove_secret_headerbooleanno
enabledbooleanno

Example request

curl -X PATCH "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/tools/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "description": "string",
    "fields": [
      {
        "name": "Hiboty",
        "type": "string",
        "required": false,
        "description": "string",
        "options": [
          "string"
        ]
      }
    ],
    "url": "https://example.com/hook",
    "host": "string",
    "secret_header_name": "string",
    "enabled": true,
    "last_called_at": "2026-11-06T09:00:00.000Z",
    "last_status": 1,
    "signing_secret": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a custom AI tool

DELETE/api/v1/bots/{id}/tools/{tool_id}

Scope: bots:write.

Scope
bots:write
SDK method
deleteBotTool · delete_bot_tool
MCP tool
deleteBotToolirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
tool_idpathuuidyesTool ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/tools/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Calls a custom tool with sample input

POST/api/v1/bots/{id}/tools/{tool_id}/test

A real request goes to your address (with the X-Hiboty-Test header); no contact or conversation ID is sent. Scope: bots:write.

Scope
bots:write
SDK method
testBotTool · test_bot_tool
MCP tool
testBotToolexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
tool_idpathuuidyesTool ID

Body fields

NameTypeRequiredDescription
inputobjectyes

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/tools/3fa85f64-5717-4562-b3fc-2c963f66afa6/test" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input":{"urun_kodu":"A-100"}}'

Example response (200)

JSON
{
  "data": {
    "success": true,
    "uncertain": true,
    "status": 1,
    "duration_ms": 1,
    "body": "string",
    "truncated": true,
    "model_text": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists configuration versions

GET/api/v1/bots/{id}/versions

The last 50 versions are kept per bot. Scope: bots:read.

Scope
bots:read
SDK method
listBotVersions · list_bot_versions
MCP tool
listBotVersionsread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "version": 1,
      "created_at": "2026-11-06T09:00:00.000Z",
      "source": "panel",
      "restored_from_version": 1,
      "readable": true,
      "changes": [
        {
          "field": "string",
          "before": "string",
          "after": "string"
        }
      ],
      "truncated": true,
      "tools_changed": true,
      "sources_changed": true,
      "tool_changes": [
        {
          "name": "Hiboty",
          "change": "eklendi"
        }
      ],
      "source_changes": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "title": "Example",
          "change": "eklendi"
        }
      ]
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Version diff and restore preview

GET/api/v1/bots/{id}/versions/{version_id}

restore_token represents the previewed state; pass it unchanged to restoreBotVersion. restore is null for non-admins. Scope: bots:read.

Scope
bots:read
SDK method
getBotVersion · get_bot_version
MCP tool
getBotVersionread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
version_idpathuuidyesVersion ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "version": 1,
    "changes": [
      {
        "field": "string",
        "before": "string",
        "after": "string"
      }
    ],
    "restore": {
      "available": true,
      "changes": [
        {
          "field": "string",
          "before": "string",
          "after": "string"
        }
      ],
      "skipped_fields": [
        "string"
      ],
      "restore_token": "string",
      "reason": "string",
      "tool_changes": [
        {
          "name": "Hiboty",
          "change": "eklendi"
        }
      ],
      "changed_sources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "title": "Example",
          "change": "eklendi"
        }
      ],
      "tools_need_secret": [
        "string"
      ]
    },
    "tool_changes": [
      {
        "name": "Hiboty",
        "change": "eklendi"
      }
    ],
    "source_changes": [
      {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "title": "Example",
        "change": "eklendi"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Restores a version

POST/api/v1/bots/{id}/versions/{version_id}/restore

Writes a new version and keeps history; channel connection and status don't change. Returns 409 stale_version if settings changed after the preview. Scope: bots:write.

Scope
bots:write
SDK method
restoreBotVersion · restore_bot_version
MCP tool
restoreBotVersionirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
version_idpathuuidyesVersion ID

Body fields

NameTypeRequiredDescription
restore_tokenstringyes

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/restore" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"restore_token":"f3a1c9…"}'

Example response (200)

JSON
{
  "data": {
    "new_version": 1,
    "restored_version": 1,
    "pending_approval": true,
    "tools_need_secret": [
      "string"
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.stale_version
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Channel profile texts

GET/api/v1/bots/{id}/profile

The Telegram bot name and descriptions or the WhatsApp business profile, read live from the channel. Needs admin permission. Scope: bots:read.

Scope
bots:read
SDK method
getBotProfile · get_bot_profile
MCP tool
getBotProfileread-onlyexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "channel": "telegram",
    "tr": {
      "name": "Hiboty",
      "short_description": "string",
      "description": "string"
    },
    "en": {
      "name": "Hiboty",
      "short_description": "string",
      "description": "string"
    },
    "about": "string",
    "description": "string",
    "vertical": "string",
    "website": "https://example.com"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Writes profile texts to the channel

PUT/api/v1/bots/{id}/profile

tr and en on a Telegram bot; about, vertical (and optional description, website) on a WhatsApp bot. The customer-facing channel profile changes. Scope: bots:write.

Scope
bots:write
SDK method
updateBotProfile · update_bot_profile
MCP tool
updateBotProfileexternal effectirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Body fields

NameTypeRequiredDescription
trobjectno
tr.namestringyeslen ≤ 64
tr.short_descriptionstringyeslen ≤ 120
tr.descriptionstringyeslen ≤ 512
enobjectno
en.namestringyeslen ≤ 64
en.short_descriptionstringyeslen ≤ 120
en.descriptionstringyeslen ≤ 512
aboutstringnolen ≤ 139
descriptionstringnolen ≤ 512
verticalstringno
websitestringnolen ≤ 256

Example request

curl -X PUT "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tr":{"name":"Store Assistant","short_description":"Order and shipping questions","description":"Answers your order, shipping and return questions."},"en":{"name":"Store Assistant","short_description":"Orders and shipping","description":"Answers your order, shipping and return questions."}}'

Example response (200)

JSON
{
  "data": {
    "changed": 1
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Generates a profile suggestion with AI

POST/api/v1/bots/{id}/profile/suggest

Doesn't write to the channel; counts against the AI quota. Scope: bots:write.

Scope
bots:write
SDK method
suggestBotProfile · suggest_bot_profile
MCP tool
suggestBotProfile

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/profile/suggest" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "channel": "telegram",
    "tr": {
      "name": "Hiboty",
      "short_description": "string",
      "description": "string"
    },
    "en": {
      "name": "Hiboty",
      "short_description": "string",
      "description": "string"
    },
    "about": "string",
    "description": "string",
    "vertical": "string",
    "website": "https://example.com"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Lists AI evaluation cases

GET/api/v1/bots/{id}/eval-cases

Scope: bots:read.

Scope
bots:read
SDK method
listBotEvalCases · list_bot_eval_cases
MCP tool
listBotEvalCasesread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-cases?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "question": "string",
      "must_include": [
        "string"
      ],
      "must_not_include": [
        "string"
      ],
      "expect_handoff": true
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Adds an evaluation case

POST/api/v1/bots/{id}/eval-cases

Scope: bots:write.

Scope
bots:write
SDK method
createBotEvalCase · create_bot_eval_case
MCP tool
createBotEvalCase

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
questionstringyeslen 2–1000
must_includestring[]noitems ≤ 10
must_not_includestring[]noitems ≤ 10
expect_handoffbooleannodefault false

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-cases" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"question":"What is your return period?","must_include":["14 days"],"must_not_include":[],"expect_handoff":false}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "question": "string",
    "must_include": [
      "string"
    ],
    "must_not_include": [
      "string"
    ],
    "expect_handoff": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Updates an evaluation case

PATCH/api/v1/bots/{id}/eval-cases/{case_id}

Send the whole case. Scope: bots:write.

Scope
bots:write
SDK method
updateBotEvalCase · update_bot_eval_case
MCP tool
updateBotEvalCase

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
case_idpathuuidyesCase ID

Body fields

NameTypeRequiredDescription
questionstringyeslen 2–1000
must_includestring[]noitems ≤ 10
must_not_includestring[]noitems ≤ 10
expect_handoffbooleannodefault false

Example request

curl -X PATCH "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-cases/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"question":"What is your return period?","must_include":["14 days"],"must_not_include":["30 days"],"expect_handoff":false}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "question": "string",
    "must_include": [
      "string"
    ],
    "must_not_include": [
      "string"
    ],
    "expect_handoff": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes an evaluation case

DELETE/api/v1/bots/{id}/eval-cases/{case_id}

Scope: bots:write.

Scope
bots:write
SDK method
deleteBotEvalCase · delete_bot_eval_case
MCP tool
deleteBotEvalCaseirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
case_idpathuuidyesCase ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-cases/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists evaluation runs

GET/api/v1/bots/{id}/eval-runs

Scope: bots:read.

Scope
bots:read
SDK method
listBotEvalRuns · list_bot_eval_runs
MCP tool
listBotEvalRunsread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-runs?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "kind": "cases",
      "status": "string",
      "started_at": "string",
      "finished_at": "string",
      "model": "string",
      "summary": {
        "total": 1,
        "passed": 1,
        "failed": 1,
        "errored": 1,
        "not_run": 1
      }
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Runs an evaluation

POST/api/v1/bots/{id}/eval-runs

kind: cases (case set) or security (built-in attack list). Each reply counts against the AI quota; nothing is sent to customers and tools aren't called. Scope: bots:write.

Scope
bots:write
SDK method
runBotEval · run_bot_eval
MCP tool
runBotEval

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
kindenumyescases | security

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-runs" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"kind":"cases"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "summary": {
      "total": 1,
      "passed": 1,
      "failed": 1,
      "errored": 1,
      "not_run": 1
    }
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Run results

GET/api/v1/bots/{id}/eval-runs/{run_id}

Scope: bots:read.

Scope
bots:read
SDK method
getBotEvalRun · get_bot_eval_run
MCP tool
getBotEvalRunread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
run_idpathuuidyesRun ID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/eval-runs/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "kind": "cases",
    "status": "string",
    "started_at": "string",
    "finished_at": "string",
    "model": "string",
    "summary": {
      "total": 1,
      "passed": 1,
      "failed": 1,
      "errored": 1,
      "not_run": 1
    },
    "comparison": {
      "improved": 1,
      "worsened": 1,
      "added": 1,
      "removed": 1
    },
    "results": [
      {
        "key": "sehir",
        "question": "string",
        "status": "string",
        "reply": "string",
        "handed_off": true,
        "refused": true,
        "reasons": [
          {}
        ],
        "error": "string",
        "change": "string"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

All WhatsApp templates

GET/api/v1/bots/{id}/whatsapp-templates

Includes pending and rejected ones; use listTemplates for approved only. Scope: bots:read.

Scope
bots:read
SDK method
listWhatsAppTemplates · list_whats_app_templates
MCP tool
listWhatsAppTemplatesread-onlyexternal effect

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/whatsapp-templates?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "string",
      "name": "Hiboty",
      "language": "tr",
      "category": "string",
      "status": "string",
      "body": "string",
      "rejected_reason": "string"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Creates a WhatsApp template

POST/api/v1/bots/{id}/whatsapp-templates

The template goes to Meta for review. Scope: bots:write.

Scope
bots:write
SDK method
createWhatsAppTemplate · create_whats_app_template
MCP tool
createWhatsAppTemplateexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Valid for 24 hours per organization, endpoint and key: the same key with the same body returns the first response unchanged (Idempotency-Replayed: true) and the action isn't repeated. A different body returns 409 idempotency_conflict; while the first request is running you get 409 idempotency_in_progress with Retry-After. 5xx and 429 responses aren't stored, so you can retry with the same key.len 1–255

Body fields

NameTypeRequiredDescription
namestringyeslen ≤ 512
categoryenumyesMARKETING | UTILITY
languagestringyes
headerstringnolen ≤ 60
bodystringyes{{1}}, {{2}} variables in orderlen 1–1024
examplesstring[]noA sample for each variableitems ≤ 20
footerstringnolen ≤ 60
buttonsobject[]noitems ≤ 3
buttons[].typeenumnoquick_reply | url
buttons[].textstringnolen ≤ 25
buttons[].urlstringnoAn https:// address for type=url

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/whatsapp-templates" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"siparis_kargoda","category":"UTILITY","language":"tr","body":"Hello {{1}}, your order has shipped.","examples":["Jane"]}'

Example response (201)

JSON
{
  "data": {
    "id": "string",
    "name": "Hiboty",
    "status": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Deletes a WhatsApp template

DELETE/api/v1/bots/{id}/whatsapp-templates/{name}

The template is deleted from Meta in all its languages. Scope: bots:write.

Scope
bots:write
SDK method
deleteWhatsAppTemplate · delete_whats_app_template
MCP tool
deleteWhatsAppTemplateexternal effectirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
namepathstringyesTemplate name

Example request

curl -X DELETE "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/whatsapp-templates/Hiboty" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "name": "Hiboty",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Lists disliked AI replies

GET/api/v1/bots/{id}/ai-feedback

Unresolved replies, with the contact's question. Scope: bots:read.

Scope
bots:read
SDK method
listAiFeedback · list_ai_feedback
MCP tool
listAiFeedbackread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque; older date-time cursors are also accepted)

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/ai-feedback?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "question": "string",
      "reply": "string",
      "note": "string",
      "created_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Resolves a disliked reply

POST/api/v1/bots/{id}/ai-feedback/{message_id}

add_faq: creates an FAQ source from question and answer; dismiss: only hides it from the list. Scope: bots:write.

Scope
bots:write
SDK method
resolveAiFeedback · resolve_ai_feedback
MCP tool
resolveAiFeedback

Parameters

NameTypeRequiredDescription
idpathuuidyesBot ID
message_idpathuuidyesMessage ID

Body fields

NameTypeRequiredDescription
actionenumyesadd_faq | dismiss
questionstringnolen ≤ 500
answerstringnolen ≤ 5000

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/ai-feedback/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"add_faq","question":"What is your return period?","answer":"14 days from delivery."}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resolved": true,
    "knowledge_source_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

A WhatsApp bot's approved templates

GET/api/v1/templates

Scope
read
SDK method
listTemplates · list_templates
MCP tool
listTemplatesread-only

Parameters

NameTypeRequiredDescription
bot_idqueryuuidyesWhatsApp bot

Example request

curl -X GET "https://hiboty.com/api/v1/templates?bot_id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "name": "Hiboty",
      "language": "tr",
      "category": "string",
      "parameter_count": 1,
      "body": "string",
      "header_parameter": true
    }
  ]
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Sets up the Telegram webhook again

POST/api/v1/bots/{id}/refresh-webhook

Use it when the bot isn't receiving group or channel events; a request goes to Telegram. Returns 409 not_connected if no Telegram bot is connected, 409 https_required if the server address isn't HTTPS, and 502 channel_error if Telegram refuses. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
refreshBotWebhook · refresh_bot_webhook
MCP tool
refreshBotWebhookexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/refresh-webhook" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "webhook_refreshed": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connectedhttps_required
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).channel_error

Sets up the Telegram command menu

POST/api/v1/bots/{id}/commands

Sets the Telegram bot's command menu with setMyCommands. With an empty body the default menu is set: /start, /help and the handoff keyword (only if it uses lowercase English letters, digits and underscores); Turkish descriptions go to the default scope and English ones to the "en" language scope. If commands is given, the same list is written to both scopes (up to 100 commands; command 1-32 characters, description 1-256). The menu is set automatically on connection; if the connect response has warning telegram_commands_failed, retry with this endpoint. 409 not_connected if the bot isn't connected. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
setBotCommands · set_bot_commands
MCP tool
setBotCommandsexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
commandsobject[]noitems ≤ 100
commands[].commandstringyeslen ≤ 33
commands[].descriptionstringyeslen ≤ 256

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/commands" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"commands":[{"command":"start","description":"Start"},{"command":"menu","description":"Menu"}]}'

Example response (200)

JSON
{
  "data": {
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "commands": [
      {
        "command": "string",
        "description": "string"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).

Gets the card payment setting

GET/api/v1/bots/{id}/payments

Telegram Payments (card payment) status. The provider token is never returned; only provider_token_set and test_mode. Telegram Stars payments don't depend on this setting. Scope: bots:read.

Scope
bots:read
SDK method
getBotPaymentSettings · get_bot_payment_settings
MCP tool
getBotPaymentSettingsread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/payments" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "card_payments_enabled": true,
    "provider_token_set": true,
    "test_mode": true,
    "refund_note": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Saves the card payment provider token

PUT/api/v1/bots/{id}/payments

Stores the provider token from BotFather › Payments (123:TEST:… or 123:LIVE:…) encrypted; provider_token null deletes the token and turns card payments off. Only the format is checked; Telegram validates the token on the first invoice. The bot must be connected to Telegram to save one (409 not_connected). Card payment refunds are made in the provider's dashboard. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
updateBotPaymentSettings · update_bot_payment_settings
MCP tool
updateBotPaymentSettings

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
provider_tokenstring | nullyesProvider token; null deletes the tokenlen ≤ 300

Example request

curl -X PUT "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/payments" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider_token":"284685063:TEST:…"}'

Example response (200)

JSON
{
  "data": {
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "card_payments_enabled": true,
    "provider_token_set": true,
    "test_mode": true,
    "refund_note": "string"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.not_connected
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists changes awaiting approval

GET/api/v1/publish-approvals

Bot configuration, tool and knowledge source changes and Mini App publishes awaiting approval while publish approval is on, newest first. Returns an empty list for non-admins. Scope: bots:read.

Scope
bots:read
SDK method
listPublishApprovals · list_publish_approvals
MCP tool
listPublishApprovalsread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidnoOnly this bot's changes
miniapp_idqueryuuidnoOnly this Mini App's publishes
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/publish-approvals?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "type": "bot",
      "target_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "target_name": "string",
      "version": 1,
      "action": "yapilandirma",
      "summary": [
        "string"
      ],
      "requested_by": "string",
      "requested_at": "2026-11-06T09:00:00.000Z",
      "own_request": true,
      "api_key_request": true
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Approves a pending bot change

POST/api/v1/bots/{id}/versions/{version_id}/approve

The change is applied with the approver's permissions. If the organization sets an evaluation threshold and the latest run's pass rate is below it, 409 threshold is returned. Needs admin permission. With four-eyes on, the person who made the change can't approve it (403 four_eyes); approval isn't possible with an API key. Scope: bots:write.

Scope
bots:write
SDK method
approveBotVersion · approve_bot_version
MCP tool
approveBotVersion

Parameters

NameTypeRequiredDescription
idpathuuidyesID
version_idpathuuidyesversion_id

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/approve" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "status": "approved",
    "signing_secret": "string",
    "tools_need_secret": [
      "string"
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.four_eyes
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.threshold
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Rejects a pending bot change

POST/api/v1/bots/{id}/versions/{version_id}/reject

The change isn't applied; an admin or the person who made the change (withdrawing it) can reject it. Scope: bots:write.

Scope
bots:write
SDK method
rejectBotVersion · reject_bot_version
MCP tool
rejectBotVersion

Parameters

NameTypeRequiredDescription
idpathuuidyesID
version_idpathuuidyesversion_id

Example request

curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/versions/3fa85f64-5717-4562-b3fc-2c963f66afa6/reject" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "status": "approved",
    "signing_secret": "string",
    "tools_need_secret": [
      "string"
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Bulk action on several bots

POST/api/v1/bots/bulk

Pauses (pause), resumes (resume) or changes the settings of the selected bots together (update: ai_enabled, handoff_keyword, voice_transcription). Up to 100 bots. Each bot is handled separately and the response returns a result per bot (partial success): a bot you can't access is skipped with not_found, a bot outside the plan limit with plan_limit and an unconnected bot with not_connected. A settings change creates a version record for each bot; with publish approval on, a pending change is opened for each bot (pending_approval). Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
bulkBotAction · bulk_bot_action
MCP tool
bulkBotActionexternal effect

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
actionenumyespause | resume | update
bot_idsstring[]yesitems 1–100
settingsobjectno
settings.ai_enabledbooleanno
settings.handoff_keywordstringnolen 2–40
settings.voice_transcriptionbooleanno

Example request

curl -X POST "https://hiboty.com/api/v1/bots/bulk" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"action":"update","bot_ids":["6f1c2a4e-1b7d-4c1a-9a51-3f2b8d7e9c10"],"settings":{"ai_enabled":true}}'

Example response (200)

JSON
{
  "data": {
    "action": "pause",
    "summary": {
      "total": 1,
      "succeeded": 1,
      "unchanged": 1,
      "pending_approval": 1,
      "skipped": 1
    },
    "results": [
      {
        "bot_id": "string",
        "name": "Hiboty",
        "status": "succeeded",
        "reason": "not_found",
        "version": 1
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Runs the evaluation set on all bots

POST/api/v1/bots/evaluations/run-all

Bots that have cases and are within the plan limit are queued and run one after another in the background; each case produces one AI reply that counts toward the monthly AI quota, and no message is sent to customers. First get the estimate with dry_run: true (responses_needed); to run, max_responses must be at least that number, otherwise 409 budget_not_confirmed. If the quota isn't enough it returns 429 ai_quota_exceeded; if the organization already has a queued or running evaluation, 409 run_in_progress. Without bot_ids, every bot you can access. Follow the results with GET /api/v1/bots/evaluations and the bot's eval-runs endpoint. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
runAllBotEvaluations · run_all_bot_evaluations
MCP tool
runAllBotEvaluations

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
bot_idsuuid[]noitems 1–100
dry_runbooleanno
max_responsesintegernoMaximum number of AI replies you approve (budget confirmation)val ≥ 0

Example request

curl -X POST "https://hiboty.com/api/v1/bots/evaluations/run-all" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"dry_run":true}'

Example response (200)

JSON
{
  "data": {
    "dry_run": true,
    "responses_needed": 1,
    "quota_left": 1,
    "quota_enough": true,
    "key_set": true,
    "in_progress": true,
    "queued": 1,
    "run_ids": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "bots": [
      {
        "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "cases": 1,
        "skipped_reason": "no_cases"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 409The action isn't possible in this state; the code gives the reason.budget_not_confirmedrun_in_progress
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.ai_quota_exceeded

Fleet evaluation summary

GET/api/v1/bots/evaluations

For every bot you can access, the pass rate of the latest evaluation-set run and the change from the previous completed run (percentage points); overall average and the number of bots that improved or worsened. Scope: bots:read.

Scope
bots:read
SDK method
getFleetEvaluation · get_fleet_evaluation
MCP tool
getFleetEvaluationread-only

Example request

curl -X GET "https://hiboty.com/api/v1/bots/evaluations" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "in_progress": true,
    "queued": 1,
    "overview": {
      "bots": 1,
      "evaluated": 1,
      "average_pass_rate": 1,
      "improved": 1,
      "worsened": 1
    },
    "bots": [
      {
        "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "name": "Hiboty",
        "channel": "string",
        "cases": 1,
        "status": "queued",
        "last_run": {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "finished_at": "string",
          "summary": {
            "total": 1,
            "passed": 1,
            "failed": 1,
            "errored": 1,
            "not_run": 1
          },
          "pass_rate": 1
        },
        "previous_pass_rate": 1,
        "change": 1
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists the organization's bot templates

GET/api/v1/bot-templates

Templates saved by the organization (newest first, at most 50). For the starter gallery use GET /api/v1/bots/templates. Other organizations' templates are never visible. Needs admin permission. Scope: bots:read.

Scope
bots:read
SDK method
listOrgBotTemplates · list_org_bot_templates
MCP tool
listOrgBotTemplatesread-only

Example request

curl -X GET "https://hiboty.com/api/v1/bot-templates" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "description": "string",
      "channel": "telegram",
      "knowledge_count": 1,
      "tool_count": 1,
      "created_by": "string",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z"
    }
  ]
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Saves a bot as a template

POST/api/v1/bot-templates

The bot's persona, welcome message, handoff keyword, AI settings, knowledge sources and AI tool definitions are written to the template (same allow list as export). Templates never contain channel tokens, App Secrets, webhook or signing secrets, secret headers, contacts or conversations. Tools and sources with an address are listed in the response. The name is unique within the organization (409). Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
createOrgBotTemplate · create_org_bot_template
MCP tool
createOrgBotTemplate

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
bot_iduuidyes
namestringyeslen 2–80
descriptionstringnolen ≤ 300

Example request

curl -X POST "https://hiboty.com/api/v1/bot-templates" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"6f1c2a4e-1b7d-4c1a-9a51-3f2b8d7e9c10","name":"Salon bot","description":"Booking and price questions"}'

Example response (201)

JSON
{
  "data": {
    "template": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "description": "string",
      "channel": "telegram",
      "knowledge_count": 1,
      "tool_count": 1,
      "created_by": "string",
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z"
    },
    "urls": [
      {
        "kind": "tool",
        "name": "Hiboty",
        "url": "https://example.com/hook",
        "has_query": true
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Gets an organization template

GET/api/v1/bot-templates/{id}

The template summary and its bot file. Templates never contain channel tokens, App Secrets, webhook or signing secrets, secret headers, contacts or conversations. Needs admin permission. Scope: bots:read.

Scope
bots:read
SDK method
getOrgBotTemplate · get_org_bot_template
MCP tool
getOrgBotTemplateread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/bot-templates/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "description": "string",
    "channel": "telegram",
    "knowledge_count": 1,
    "tool_count": 1,
    "created_by": "string",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z",
    "file": {}
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Renames a template or changes its description

PATCH/api/v1/bot-templates/{id}

Only the name and description change; to refresh the content, save the bot as a template again. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
updateOrgBotTemplate · update_org_bot_template
MCP tool
updateOrgBotTemplate

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Body fields

NameTypeRequiredDescription
namestringyeslen 2–80
descriptionstringnolen ≤ 300

Example request

curl -X PATCH "https://hiboty.com/api/v1/bot-templates/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Salon bot 2026","description":"Booking, price and cancellation questions"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "description": "string",
    "channel": "telegram",
    "knowledge_count": 1,
    "tool_count": 1,
    "created_by": "string",
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Deletes a template

DELETE/api/v1/bot-templates/{id}

Bots created from the template aren't affected. Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
deleteOrgBotTemplate · delete_org_bot_template
MCP tool
deleteOrgBotTemplateirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X DELETE "https://hiboty.com/api/v1/bot-templates/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "deleted": true
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Creates a bot from a template

POST/api/v1/bot-templates/{id}/bots

Always creates a new draft bot: no channel is connected, AI tools come disabled, and signing secrets are regenerated and returned only in this response. Without name and channel the template's values are used. The plan's bot limit applies (403 plan_limit). Needs admin permission. Scope: bots:write.

Scope
bots:write
SDK method
createBotFromOrgTemplate · create_bot_from_org_template
MCP tool
createBotFromOrgTemplate

Supports Idempotency-Key

Parameters

NameTypeRequiredDescription
idpathuuidyesID
Idempotency-KeyheaderstringnoOptional, 1-255 visible ASCII characters. Within 24 hours the same key and body return the first response unchanged; a different body returns 409 idempotency_conflict.len 1–255

Body fields

NameTypeRequiredDescription
namestringnolen 2–80
channelenumnotelegram | whatsapp

Example request

curl -X POST "https://hiboty.com/api/v1/bot-templates/3fa85f64-5717-4562-b3fc-2c963f66afa6/bots" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"name":"Salon Ayse","channel":"whatsapp"}'

Example response (201)

JSON
{
  "data": {
    "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Hiboty",
    "knowledge_count": 1,
    "tools": [
      {
        "name": "Hiboty",
        "signing_secret": "string"
      }
    ]
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.plan_limit
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists WhatsApp accounts

GET/api/v1/whatsapp-accounts

The business portfolio › WhatsApp Business Account (WABA) › phone number hierarchy. Numbers in the same WABA appear under one account; templates and Meta billing are account-level. The access token and App Secret are never returned; only access_token_set and app_secret_set. A member with restricted bot access only sees the numbers they can access and those numbers' accounts. Scope: bots:read.

Scope
bots:read
SDK method
listWhatsAppAccounts · list_whats_app_accounts
MCP tool
listWhatsAppAccountsread-only

Paginated

Parameters

NameTypeRequiredDescription
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/whatsapp-accounts?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "waba_id": "string",
      "business_id": "string",
      "name": "Hiboty",
      "display_name": "string",
      "currency": "USD",
      "timezone_id": "string",
      "embedded": true,
      "status": "bagli",
      "access_token_set": true,
      "app_secret_set": true,
      "last_synced_at": "2026-11-06T09:00:00.000Z",
      "last_error": "string",
      "phone_numbers": [
        {
          "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "bot_name": "string",
          "bot_status": "string",
          "display_phone": "string",
          "phone_number_id": "string",
          "quality": "GREEN",
          "messaging_limit": "string",
          "delivery_score": 1,
          "last_webhook_at": "2026-11-06T09:00:00.000Z",
          "last_error": "string"
        }
      ],
      "created_at": "2026-11-06T09:00:00.000Z",
      "updated_at": "2026-11-06T09:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Gets a WhatsApp account

GET/api/v1/whatsapp-accounts/{id}

The account and its numbers (quality, messaging limit, delivery score). The access token and App Secret are never returned; only access_token_set and app_secret_set. A member with restricted bot access only sees the numbers they can access and those numbers' accounts. Scope: bots:read.

Scope
bots:read
SDK method
getWhatsAppAccount · get_whats_app_account
MCP tool
getWhatsAppAccountread-only

Parameters

NameTypeRequiredDescription
idpathuuidyesID

Example request

curl -X GET "https://hiboty.com/api/v1/whatsapp-accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "waba_id": "string",
    "business_id": "string",
    "name": "Hiboty",
    "display_name": "string",
    "currency": "USD",
    "timezone_id": "string",
    "embedded": true,
    "status": "bagli",
    "access_token_set": true,
    "app_secret_set": true,
    "last_synced_at": "2026-11-06T09:00:00.000Z",
    "last_error": "string",
    "phone_numbers": [
      {
        "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "bot_name": "string",
        "bot_status": "string",
        "display_phone": "string",
        "phone_number_id": "string",
        "quality": "GREEN",
        "messaging_limit": "string",
        "delivery_score": 1,
        "last_webhook_at": "2026-11-06T09:00:00.000Z",
        "last_error": "string"
      }
    ],
    "created_at": "2026-11-06T09:00:00.000Z",
    "updated_at": "2026-11-06T09:00:00.000Z"
  }
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.

Lists a WhatsApp account's templates

GET/api/v1/whatsapp-accounts/{id}/templates

All templates in Meta (with status and rejection reason) at the account (WABA) level; every number in the account uses the same templates. 409 channel_not_configured if the account isn't connected, 502 on a Meta error. Scope: bots:read.

Scope
bots:read
SDK method
listWhatsAppAccountTemplates · list_whats_app_account_templates
MCP tool
listWhatsAppAccountTemplatesread-only

Paginated

Parameters

NameTypeRequiredDescription
idpathuuidyesID
limitqueryintegernoPage size (1–200, default 50); 400 if it isn't an integerval 1–200, default 50
cursorquerystringnonext_cursor from the previous response (opaque)

Example request

curl -X GET "https://hiboty.com/api/v1/whatsapp-accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6/templates?limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "string",
      "name": "Hiboty",
      "language": "tr",
      "category": "string",
      "status": "string",
      "body": "string",
      "rejected_reason": "string"
    }
  ],
  "next_cursor": "string"
}

Possible errors

  • 400Invalid request: a missing or wrong field, or an unknown field name (validation_error).
  • 401The API key is missing, invalid or revoked (unauthorized).
  • 403Missing scope (scope), the plan doesn't allow it (plan_limit), the role isn't enough (forbidden_role), the email isn't verified (email_not_verified) or the organization is suspended.
  • 404The record doesn't exist or this key can't access it (not_found).
  • 409The action isn't possible in this state; the code gives the reason.channel_not_configured
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
  • 502A channel or external service failed (channel_error).