List a conversation's messages
/v1/support/conversations/{conversation}/messages in the Support Inbox API.
The thread's messages oldest first, 50 per page. internal: true notes are withheld unless the token also carries support-conversation:update: reading a private remark about a member takes the same permission as writing one.
direction is inbound (from the member) or outbound (from your team). author_kind is contact, creator or system; author_user_id names the team member on an outbound reply and is null for inbound and system messages.
source is the surface the message came through: connector_chat for a member writing to the connector's installation, dashboard, api or mcp for a reply from your team, and connector_relay_dm or connector_relay_group for a reply your team typed on the platform itself (into the relay's ping, or inside the thread the relay opened in a group). Messages recorded before the connector SDK carry the same three meanings under the Telegram connector's older words, telegram_bot, telegram_relay_dm and telegram_relay_group.
delivery_status on an outbound message is pending → sent, or failed / unreachable. unreachable means the member has blocked the bot: the reply is stored but will never arrive, and retrying will not help. failure_reason carries the detail.
body is null for media sent without a caption. A captioned photo puts the caption in body and does not create a second message. A member editing an earlier message updates the stored message in place and stamps edited_at; no new message is created and no event fires. Inbound messages are rate-limited per member: excess messages are dropped silently rather than queued, so a flooding member produces no burst of events.
Each entry of attachments carries the file's kind, mime, file_name, size, width, height, duration and url.
File ids are never returned. A platform file id plus the bot token is enough to download the file straight from the platform, so it is treated as a credential.
urlis populated only after the file has been fetched at least once; it isnulluntil then.
Requires ability
The token must hold every one of these, or the call is refused with 403.
Authorization
bearerToken A personal access token minted on the dashboard under Settings, then Tokens, sent as Authorization: Bearer sbt_live_…. The token carries the abilities each endpoint lists under Requires ability and is frozen to one team.
In: header
Path Parameters
The thread, resolved by the route binder.
uuidQuery Parameters
The page to return, 1-indexed.
1Messages per page, 1 to 100.
50An alias of per_page, kept for older integrations.
Responses
200OKapplication/json
The page.
401UnauthorizedAUTHENTICATION_REQUIREDapplication/json
The request carries no bearer token, or one that is revoked, malformed, or minted for another environment (an sbt_test_ token on production).
403ForbiddenTOKEN_MISSING_ABILITYapplication/json
The token is valid but does not carry the ability this endpoint requires; error.context.required_ability names the one to grant. An endpoint that also checks who owns a row or which tier the account is on answers FORBIDDEN, TEAM_TIER_REQUIRED or CONNECTOR_TIER_REQUIRED with the same status, and says so in its own description.
404Not foundRESOURCE_NOT_FOUNDapplication/json
An id in the path names nothing the token can see. TENANT_MISMATCH: the project sits outside the token's scope:project: allow-list, or the token carries no team scope. Both answer 404 rather than 403 so that existence outside the token's scope cannot be inferred.
429Too many requestsRATE_LIMITEDapplication/json
The token has spent its 300 requests a minute or 10,000 an hour; Retry-After says when the next one is accepted.
How is this guide?
Last updated on