API reference

Conversations

12 endpoints in this group.

Lists conversations by latest message

GET/api/v1/conversations

Scope
read
SDK method
listConversations · list_conversations
MCP tool
listConversationsread-only

Paginated

Parameters

NameTypeRequiredDescription
bot_idqueryuuidno
statusqueryenumnoopen | handoff | closed
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/conversations?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",
      "status": "open",
      "unread_count": 1,
      "last_message_preview": "string",
      "last_message_at": "2026-11-06T09:00:00.000Z",
      "contact": {
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "external_id": "123456789",
        "name": "Hiboty",
        "channel": "telegram",
        "consent": "opted_in"
      }
    }
  ],
  "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.

Changes the conversation status

POST/api/v1/conversations/{id}/status

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.

Scope
write
SDK method
updateConversationStatus · update_conversation_status
MCP tool
updateConversationStatusexternal effect

Parameters

NameTypeRequiredDescription
idpathuuidyesConversation ID

Body fields

NameTypeRequiredDescription
statusenumyesopen | handoff | closed

Example request

curl -X POST "https://hiboty.com/api/v1/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/status" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"handoff"}'

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "previous_status": "open",
    "assigned_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "closed_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.

Conversation details

GET/api/v1/conversations/{id}

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

NameTypeRequiredDescription
idpathuuidyesID

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "unread_count": 1,
    "last_message_preview": "string",
    "last_message_at": "2026-11-06T09:00:00.000Z",
    "handoff_at": "2026-11-06T09:00:00.000Z",
    "closed_at": "2026-11-06T09:00:00.000Z",
    "snoozed_until": "2026-11-06T09:00:00.000Z",
    "flood_until": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "string"
    },
    "contact": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "channel": "string",
      "consent": "string"
    },
    "assigned_user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty"
    }
  }
}

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.

Assigns a conversation to a team member

POST/api/v1/conversations/{id}/assign

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.

Scope
conversations:write
SDK method
assignConversation · assign_conversation
MCP tool
assignConversationexternal 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

Body fields

NameTypeRequiredDescription
user_iduuid | nullyes

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "unread_count": 1,
    "last_message_preview": "string",
    "last_message_at": "2026-11-06T09:00:00.000Z",
    "handoff_at": "2026-11-06T09:00:00.000Z",
    "closed_at": "2026-11-06T09:00:00.000Z",
    "snoozed_until": "2026-11-06T09:00:00.000Z",
    "flood_until": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "string"
    },
    "contact": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "channel": "string",
      "consent": "string"
    },
    "assigned_user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty"
    }
  }
}

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_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.

Marks a conversation as read

POST/api/v1/conversations/{id}/read

Resets the unread counter. Scope: conversations:write.

Scope
conversations:write
SDK method
markConversationRead · mark_conversation_read
MCP tool
markConversationRead

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/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/read" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "unread_count": 1,
    "last_message_preview": "string",
    "last_message_at": "2026-11-06T09:00:00.000Z",
    "handoff_at": "2026-11-06T09:00:00.000Z",
    "closed_at": "2026-11-06T09:00:00.000Z",
    "snoozed_until": "2026-11-06T09:00:00.000Z",
    "flood_until": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "string"
    },
    "contact": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "channel": "string",
      "consent": "string"
    },
    "assigned_user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty"
    }
  }
}

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.

Snoozes a conversation

POST/api/v1/conversations/{id}/snooze

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.

Scope
conversations:write
SDK method
snoozeConversation · snooze_conversation
MCP tool
snoozeConversation

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
optionenumyes1s | 3s | yarin | pazartesi | custom | null
untilstringnoOnly when option is customlen ≤ 40

Example request

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

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "unread_count": 1,
    "last_message_preview": "string",
    "last_message_at": "2026-11-06T09:00:00.000Z",
    "handoff_at": "2026-11-06T09:00:00.000Z",
    "closed_at": "2026-11-06T09:00:00.000Z",
    "snoozed_until": "2026-11-06T09:00:00.000Z",
    "flood_until": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "string"
    },
    "contact": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "channel": "string",
      "consent": "string"
    },
    "assigned_user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty"
    }
  }
}

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.

Clears the message flood pause

POST/api/v1/conversations/{id}/clear-flood

The AI reply paused by a message flood turns back on immediately; nothing changes if there is no pause. Scope: conversations:write.

Scope
conversations:write
SDK method
clearConversationFlood · clear_conversation_flood
MCP tool
clearConversationFlood

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/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/clear-flood" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482"

Example response (200)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "open",
    "unread_count": 1,
    "last_message_preview": "string",
    "last_message_at": "2026-11-06T09:00:00.000Z",
    "handoff_at": "2026-11-06T09:00:00.000Z",
    "closed_at": "2026-11-06T09:00:00.000Z",
    "snoozed_until": "2026-11-06T09:00:00.000Z",
    "flood_until": "2026-11-06T09:00:00.000Z",
    "created_at": "2026-11-06T09:00:00.000Z",
    "bot": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty",
      "channel": "string"
    },
    "contact": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "external_id": "123456789",
      "name": "Hiboty",
      "username": "ayse",
      "channel": "string",
      "consent": "string"
    },
    "assigned_user": {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Hiboty"
    }
  }
}

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.

Sends an agent reply

POST/api/v1/conversations/{id}/reply

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.

Scope
messages:send
SDK method
replyToConversation · reply_to_conversation
MCP tool
replyToConversationexternal 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

Body fields

NameTypeRequiredDescription
bodystringyeslen ≤ 4000
image_urlstringnolen ≤ 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."}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "status": "sent"
  }
}

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_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

Lists internal notes

GET/api/v1/conversations/{id}/notes

Notes only the team can see, newest first. Scope: conversations:read.

Scope
conversations:read
SDK method
listConversationNotes · list_conversation_notes
MCP tool
listConversationNotesread-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/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/notes?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",
      "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "author_name": "string",
      "body": "string",
      "mentions": [
        "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      ],
      "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 an internal note

POST/api/v1/conversations/{id}/notes

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.

Scope
conversations:write
SDK method
createConversationNote · create_conversation_note
MCP tool
createConversationNote

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
bodystringyeslen 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?"}'

Example response (201)

JSON
{
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "conversation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "author_name": "string",
    "body": "string",
    "mentions": [
      "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    ],
    "created_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 an internal note

DELETE/api/v1/conversations/{id}/notes/{note_id}

The note's author or an admin can delete it. An API key has no user, so it needs admin permission (403 forbidden_role). Scope: conversations:write.

Scope
conversations:write
SDK method
deleteConversationNote · delete_conversation_note
MCP tool
deleteConversationNoteirreversible

Parameters

NameTypeRequiredDescription
idpathuuidyesID
note_idpathuuidyesNote ID

Example request

curl -X DELETE "https://hiboty.com/api/v1/conversations/3fa85f64-5717-4562-b3fc-2c963f66afa6/notes/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.

Runs a bulk action on conversations

POST/api/v1/conversations/bulk

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.

Scope
conversations:write
SDK method
bulkConversations · bulk_conversations
MCP tool
bulkConversationsexternal 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
operationenumyesclose | assign | read
idsuuid[]yesitems 1–100
user_iduuid | nullno

Example request

curl -X POST "https://hiboty.com/api/v1/conversations/bulk" \
  -H "Authorization: Bearer $HIBOTY_API_KEY" \
  -H "Idempotency-Key: order-10482" \
  -H "Content-Type: application/json" \
  -d '{"operation":"read","ids":["3fa85f64-5717-4562-b3fc-2c963f66afa6"]}'

Example response (200)

JSON
{
  "data": {
    "operation": "close",
    "requested": 1,
    "affected": 1,
    "skipped": 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.
  • 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.