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.
open: AI replies again; handoff: hands over to an agent, AI stays silent; closed: closes it (the satisfaction survey is sent if enabled). Scope: 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).
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.
Returns the contact summary, bot, assigned member, snooze and message flood state. The member role only sees conversations of bots it can access. Scope: conversations:read.
Scope
conversations:read
SDK method
getConversation · get_conversation
MCP tool
getConversationread-only
Parameters
Name
Type
Required
Description
idpath
uuid
yes
ID
Example request
curl -X GET "https://hiboty.com/api/v1/conversations/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.
When user_id is null the assignment is removed and the status doesn't change. With an assignee the conversation is handed off, the AI stops replying and the first transition publishes a conversation.handoff event. A target outside the team returns 409 not_team_member; one without access to the bot returns 409 bot_access_denied. Scope: conversations: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.not_team_memberbot_access_denied
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. 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.
option: 1s (1 hour), 3s (3 hours), yarin (tomorrow) and pazartesi (Monday), both 09:00 organization time, custom, or null (removes the snooze). custom needs until: an ISO instant with an offset, or a value without one (read in the organization's time zone); it must be in the future and at most 30 days ahead. Scope: conversations: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.
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.
A bot over the plan limit (403 bot_plan_restricted), the monthly message quota (429 message_quota_exceeded) and the contact's opt-out (403 opted_out) apply as in POST /messages. A real message goes to the customer (simulated in test mode); the conversation is handed off and the AI stops replying. image_url must be the /u/ address of an image uploaded by this organization, external addresses aren't accepted; with an image, body is the caption and can be empty. A channel failure returns 502 channel_error. Scope: messages:send.
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
body
string
yes
len ≤ 4000
image_url
string
no
len ≤ 200
Example request
curl -X POST "https://hiboty.com/api/v1/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/reply" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{"body":"Hello, your order shipped today."}'
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_restrictedopted_out
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.message_quota_exceeded
502A channel or external service failed (channel_error).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.
It doesn't go to the customer. Members mentioned as @Name who can access this bot get a notification; when written with an API key the author shows as API. Scope: conversations: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
body
string
yes
len 1–2000
Example request
curl -X POST "https://hiboty.com/api/v1/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/notes" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Idempotency-Key: order-10482" \
-H "Content-Type: application/json" \
-d '{"body":"@Zeynep can you check the return request?"}'
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.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.
operation: close (sends the satisfaction question to the customer if the survey is on), assign, read. Up to 100 ids. user_id applies to assign only and is required there; null removes the assignment. Inaccessible or missing conversations aren't processed; conversations whose bot the target can't access count as skipped. A target outside the team returns 409 not_team_member. Scope: conversations: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.
409The action isn't possible in this state; the code gives the reason.not_team_member
429A key, user or organization request limit (X-RateLimit-Scope) or the monthly message quota was exceeded; follow the Retry-After header.