API reference

Messages

4 endpoints in this group.

Sends a message to a contact

POST/api/v1/messages

The contact must have messaged the bot before. Send exactly one of message (free text) or template (WhatsApp only, an approved Meta template). Use Idempotency-Key to avoid duplicates on retries. Scope: messages:send.

Scope
messages:send
SDK method
sendMessage · send_message
MCP tool
sendMessageexternal effect

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
bot_iduuidyes
tostringyesTelegram chat ID or WhatsApp number (the contact must have messaged the bot before)len 3–64
messagestringnolen 1–4000
templateobjectno
template.namestringyes
template.languagestringyes
template.paramsstring[]no{{isim}} and {{custom_field}} variables are filled per contactitems ≤ 20

Example request

curl -X POST "https://hiboty.com/api/v1/messages" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Hello!"}'

Example response (201)

JSON
{
  "id": "string",
  "status": "sent",
  "bot_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "to": "string",
  "template": "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.bot_plan_restricted
  • 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 a conversation's messages from newest to oldest

GET/api/v1/messages/list

Scope
read
SDK method
listMessages · list_messages
MCP tool
listMessagesread-only

Paginated

Parameters

NameTypeRequiredDescription
conversation_idqueryuuidyes
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/messages/list?conversation_id=3fa85f64-5717-4562-b3fc-2c963f66afa6&limit=50" \
  -H "Authorization: Bearer $HIBOTY_API_KEY"

Example response (200)

JSON
{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "direction": "in",
      "sender": "string",
      "body": "string",
      "status": "string",
      "external_id": "123456789",
      "created_at": "2026-11-06T09:00:00.000Z",
      "ai_sources": [
        {
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "title": "Example",
          "chunk": 1,
          "url": "https://example.com/hook"
        }
      ]
    }
  ],
  "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.

Retries a failed message

POST/api/v1/messages/{id}/retry

Also needs the messages:send scope; a bot over the plan limit can't send (403 bot_plan_restricted) and the monthly message quota applies (429 message_quota_exceeded). Failed outgoing messages only, up to 5 times (otherwise 409 message_not_retryable). A real message goes to the customer. Automation messages aren't sent to contacts who withdrew consent (403 opted_out). An empty AI reply is regenerated and written as a new record. A channel failure returns 502 channel_error. Scope: conversations:write.

Scope
conversations:write
SDK method
retryMessage · retry_message
MCP tool
retryMessageexternal effect

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

Example request

curl -X POST "https://hiboty.com/api/v1/messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/retry" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "retried": 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.opted_outbot_plan_restricted
  • 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.message_not_retryable
  • 429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.message_quota_exceeded
  • 502A channel or external service failed (channel_error).channel_error

Rates an AI reply

POST/api/v1/messages/{id}/feedback

value: up, down or null (removes the rating). note is kept for down only. Only AI replies can be rated; any other message returns 404. Scope: conversations:write.

Scope
conversations:write
SDK method
rateAiReply · rate_ai_reply
MCP tool
rateAiReply

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
valueenumyesup | down | null
notestringnolen ≤ 500

Example request

curl -X POST "https://hiboty.com/api/v1/messages/3fa85f64-5717-4562-b3fc-2c963f66afa6/feedback" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"value":"down","note":"It gave the wrong shipping time"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "value": "up",
    "note": "string",
    "rated_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.