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.
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.
Optional, 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
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.
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.
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
Name
Type
Required
Description
description
string
no
len ≤ 3000
website
string
no
len ≤ 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"}'
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).
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.
Optional, 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
Name
Type
Required
Description
file
object | string
yes
The file returned by exportBot (object or JSON text), up to 512 KB
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.
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.
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.
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.
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.
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.
Optional, 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
Name
Type
Required
Description
token
string
no
Token from BotFather
phone_number_id
string
no
business_account_id
string
no
access_token
string
no
len ≥ 20
app_secret
string
no
webhook_verify_token
string
no
The value you choose for Meta's webhook check; never returned in a responselen 16–128
business_id
string
no
Optional Meta business portfolio ID; written to the WhatsApp account (WABA) record
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).
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
Name
Type
Required
Description
idpath
uuid
yes
Bot ID
Example request
curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/disconnect" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
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.
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.
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.
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.
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.
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
Name
Type
Required
Description
idpath
uuid
yes
Bot ID
Body fields
Name
Type
Required
Description
messages
object[]
yes
items 1–50
messages[].role
enum
yes
user | assistant
messages[].content
string
yes
len 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).
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.
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.
Optional, 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
Name
Type
Required
Description
type
enum
yes
text | faq | url | file
title
string
yes
len 2–160
content
string
no
type=textlen 10–60000
question
string
no
type=faqlen ≤ 500
answer
string
no
type=faqlen ≤ 5000
url
uri
no
type=url; a public http/https pagelen ≤ 2000
file_name
string
no
type=file; txt, md, csv, tsv, json, htmllen ≤ 200
file_base64
string
no
type=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."}'
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.
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.
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.
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.
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.
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.
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.
Optional, 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
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.
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.
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.
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.
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.
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.
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.
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.
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).
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
Name
Type
Required
Description
idpath
uuid
yes
Bot ID
Body fields
Name
Type
Required
Description
tr
object
no
tr.name
string
yes
len ≤ 64
tr.short_description
string
yes
len ≤ 120
tr.description
string
yes
len ≤ 512
en
object
no
en.name
string
yes
len ≤ 64
en.short_description
string
yes
len ≤ 120
en.description
string
yes
len ≤ 512
about
string
no
len ≤ 139
description
string
no
len ≤ 512
vertical
string
no
website
string
no
len ≤ 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).
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).
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.
Optional, 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
Name
Type
Required
Description
question
string
yes
len 2–1000
must_include
string[]
no
items ≤ 10
must_not_include
string[]
no
items ≤ 10
expect_handoff
boolean
no
default 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}'
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.
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.
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.
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.
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.
Optional, 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
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.
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.
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.
Optional, 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
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.
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.
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).
Optional, 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
Name
Type
Required
Description
name
string
yes
len ≤ 512
category
enum
yes
MARKETING | UTILITY
language
string
yes
header
string
no
len ≤ 60
body
string
yes
{{1}}, {{2}} variables in orderlen 1–1024
examples
string[]
no
A sample for each variableitems ≤ 20
footer
string
no
len ≤ 60
buttons
object[]
no
items ≤ 3
buttons[].type
enum
no
quick_reply | url
buttons[].text
string
no
len ≤ 25
buttons[].url
string
no
An 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"]}'
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).
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).
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.
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
Name
Type
Required
Description
idpath
uuid
yes
Bot ID
message_idpath
uuid
yes
Message ID
Body fields
Name
Type
Required
Description
action
enum
yes
add_faq | dismiss
question
string
no
len ≤ 500
answer
string
no
len ≤ 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."}'
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.
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).
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
Name
Type
Required
Description
idpath
uuid
yes
ID
Example request
curl -X POST "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/refresh-webhook" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
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 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.
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).
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
Name
Type
Required
Description
idpath
uuid
yes
ID
Example request
curl -X GET "https://hiboty.com/api/v1/bots/3fa85f64-5717-4562-b3fc-2c963f66afa6/payments" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
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.
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.
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.
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.
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.
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
Name
Type
Required
Description
idpath
uuid
yes
ID
version_idpath
uuid
yes
version_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"
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.
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.
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.
Optional, 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
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.
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.
Optional, 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
Name
Type
Required
Description
bot_ids
uuid[]
no
items 1–100
dry_run
boolean
no
max_responses
integer
no
Maximum number of AI replies you approve (budget confirmation)val ≥ 0
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
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"
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.
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"
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.
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.
Optional, 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
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.
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
Name
Type
Required
Description
idpath
uuid
yes
ID
Example request
curl -X GET "https://hiboty.com/api/v1/bot-templates/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
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.
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.
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.
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.
Optional, 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
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.
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.
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.
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
Name
Type
Required
Description
idpath
uuid
yes
ID
Example request
curl -X GET "https://hiboty.com/api/v1/whatsapp-accounts/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "Authorization: Bearer $HIBOTY_API_KEY"
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 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.
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).