Conversations

Operations tagged Conversations in the public API.

About Conversations

A conversation is one thread between a visitor and a chatbot, from any surface: POST /chat, the website widget, the hosted agent page, the dashboard Test Chat or a messaging channel. Each turn in it — the visitor's message and the reply — is a message.

Lifecycle. The first turn creates the conversation and emits conversation.started; each stored turn emits conversation.message.created; conversation.handoff.requested fires once, when the conversation first asks for a human. Lists show a conversation once it has a message. It stays readable until you delete it with DELETE /conversations/{id}, which emits conversation.ended.

IDs you will meet.

id — the conversation id, an integer, in every /conversations/{id} path. A message carries it as conversation_id.
session_id — a string whose prefix names the surface that started the thread (api_, ws_, widget-, sess_, ch-). Send an api_ one back to POST /chat to continue the thread; look any of them up with GET /conversations/by_session/{sessionId}.
Message id — an integer, for GET /messages/{id} and POST /messages/{id}/feedback. POST /chat returns it as id, POST /chat/stream as query_id.

IDs on this page

Chatbot id<CHATBOT_ID>: Integer.
Get it from
GET /v1/chatbots returns it as data[].id
POST /v1/chatbots returns it as id
GET /v1/chatbots/by_handle/{handle} returns it as id
Webhook chatbot.created carries it as data.object.id
In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
Review status id<REVIEW_STATUS_ID>: Integer.
Get it from
GET /v1/conversations returns it as data[].review_status.id
GET /v1/conversations/{id} returns it as review_status.id
The account's review-status catalogue is managed in the dashboard; /v1 has no operation that lists it.
Session id<SESSION_ID>: String. Its prefix names the surface that started the conversation: api_ (POST /chat, POST /chat/stream), ws_ (website widget and hosted agent page), widget- (a widget or agent-page turn sent without a minted session), sess_ (dashboard Test Chat) or ch-{platform}-{integrationId}-{externalChatId} (messaging channels). Older conversations can carry another shape.
Get it from
POST /v1/chat returns it as session_id
GET /v1/conversations returns it as data[].session_id
GET /v1/conversations/{id} returns it as session_id
POST /chat/stream sends it as session_id in its metadata event (and in the JSON replay of an idempotent retry).
Conversation id<CONVERSATION_ID>: Integer.
Get it from
POST /v1/chat returns it as conversation_id
GET /v1/conversations returns it as data[].id
GET /v1/conversations/by_session/{sessionId} returns it as id
GET /v1/messages/{id} returns it as conversation_id
GET /v1/customers/{id}/timeline returns it as data[].chat_session_id
Webhook conversation.started carries it as data.object.id
Webhook conversation.handoff.requested carries it as data.object.id
POST /chat/stream returns no conversation id: read session_id from its metadata event, then look the conversation up with GET /conversations/by_session/{sessionId}.
Message id<MESSAGE_ID>: Integer.
Get it from
POST /v1/chat returns it as id
GET /v1/conversations/{id}/messages returns it as data[].id
Webhook conversation.message.created carries it as data.object.id
POST /chat/stream sends it as query_id in its metadata event (and in the JSON replay of an idempotent retry).

/v1/conversations

List conversations

Returns the account's conversations from every surface — the API, the website widget, the hosted agent page, the dashboard Test Chat and messaging channels — newest first, cursor-paginated. A conversation appears once it has at least one message. Pass chatbot_id for one chatbot's conversations; the other filters combine with it. A chatbot_id of another account is 404 NOT_FOUND. There is no channel filter: read channel on each conversation.

Required scope: conversations:read
Idempotency: Read-only
Rate limits

Before you call

chatbot_id(query)Chatbot id
Integer.
Placeholder in the samples: <CHATBOT_ID>
Get it from
- GET /v1/chatbots returns it as data[].id
- POST /v1/chatbots returns it as id
- GET /v1/chatbots/by_handle/{handle} returns it as id
- Webhook chatbot.created carries it as data.object.id
- In the dashboard, it is the number in a chatbot's address: /dashboard/chatbots/{id}.
review_status_id(query)Review status id
Integer.
Placeholder in the samples: <REVIEW_STATUS_ID>
Get it from
- GET /v1/conversations returns it as data[].review_status.id
- GET /v1/conversations/{id} returns it as review_status.id
- The account's review-status catalogue is managed in the dashboard; /v1 has no operation that lists it.

Query parameters

chatbot_idintegernullableOptional
Restrict to one chatbot. Omit to list every conversation in the account.
Minimum: 1
statusstringnullableOptional
Answer status: answered (at least one answered turn), not_answered (unanswered or partial turns and no answered one) or partial_answer. Any other value is 422 VALIDATION_FAILED.
Possible valuesanswerednot_answeredpartial_answernull
date_fromstringnullableOptional
Only conversations started on or after this UTC calendar day (YYYY-MM-DD).
Format: date
date_tostringnullableOptional
Only conversations started on or before this UTC calendar day (YYYY-MM-DD, inclusive); must not precede date_from.
Format: date
searchstringnullableOptional
Conversations with a visitor message containing every word of the term, in any order (Arabic spelling variants such as ه/ة, ي/ى and أ/إ/ا match each other; at most 100 characters are matched).
Max length: 255
review_status_idintegernullableOptional
Only conversations whose effective review status is this id from the account catalogue. A custom status matches explicit assignments; a system status also matches legacy rows whose is_reviewed resolves to it. An id outside the catalogue is 422 VALIDATION_FAILED.
Minimum: 1
limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of ConversationResourceRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
Always/v1/conversations
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/conversations' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "conversation",
      "id": 1,
      "session_id": "api_Q7mK2xVb9RtL4nWc8ZpH3sYd6JfA1gEu5oTi0vNq",
      "chatbot_id": 1,
      "status": "active",
      "channel": "api",
      "is_reviewed": false,
      "review_status": {
        "id": 1,
        "name": "Needs review",
        "color": "neutral",
        "counts_as_reviewed": false
      },
      "handoff_requested": false,
      "handoff_reason": null,
      "external_user_id": null,
      "external_user_name": null,
      "started_at": "2026-01-01T00:00:00+00:00",
      "created_at": "2026-01-01T00:00:00+00:00",
      "updated_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/conversations"
}

/v1/conversations/by_session/{sessionId}

Retrieve a conversation by session id

Looks a conversation up by its session_id instead of its integer id. Use it after POST /chat/stream, whose metadata event carries session_id but no conversation id, or when your own records keep the session id. A session id from any surface is accepted (api_, ws_, widget-, sess_, ch-); only POST /chat is limited to api_ sessions. A session id of another account is 404 NOT_FOUND.

Required scope: conversations:read
Idempotency: Read-only
Rate limits

Before you call

sessionId(path)Session id
String. Its prefix names the surface that started the conversation: api_ (POST /chat, POST /chat/stream), ws_ (website widget and hosted agent page), widget- (a widget or agent-page turn sent without a minted session), sess_ (dashboard Test Chat) or ch-{platform}-{integrationId}-{externalChatId} (messaging channels). Older conversations can carry another shape.
Placeholder in the samples: <SESSION_ID>
Get it from
- POST /v1/chat returns it as session_id
- GET /v1/conversations returns it as data[].session_id
- GET /v1/conversations/{id} returns it as session_id
- POST /chat/stream sends it as session_id in its metadata event (and in the JSON replay of an idempotent retry).

Path parameters

sessionIdstringRequired
The conversation's session_id, exactly as an earlier response returned it.

Responses

200
ConversationResource
objectstringRequired
Alwaysconversation
idintegerRequired
The conversation id, used in every /conversations/{id} path. Messages carry it as conversation_id.
session_idstringRequired
The session id the surface minted; its prefix names that surface (api_, ws_, widget-, sess_, ch-). Send an api_ one back to POST /chat to continue the conversation.
chatbot_idintegerRequired
The chatbot the conversation is with.
statusstringRequired
Lifecycle state. Conversations are created active; completed and abandoned are reserved values no current surface sets.
Possible valuesactivecompletedabandoned
channelstringRequired
The surface the conversation arrived through: api, widget, direct_link (hosted agent page), dashboard (Test Chat), a messaging platform, or unknown for an older conversation whose origin was never recorded.
Possible valueswidgetdirect_linkdashboardapitelegramwhatsappfacebookinstagramslackdiscordlineviberwechatsmsunknown
is_reviewedbooleanRequired
Whether the effective review status counts as reviewed (review_status.counts_as_reviewed).
review_statusobjectRequired
The conversation's effective status in the account's review catalogue. POST /conversations/{id}/review sets it.
handoff_requestedbooleanRequired
Whether the conversation asked for a human. conversation.handoff.requested fires once, when this turns true.
handoff_reasonstringnullableRequired
Why the handoff was requested, when a reason was recorded.
external_user_idstringnullableRequired
The visitor id the embedding page passed to the widget or hosted agent page, or the platform chat id on a messaging channel; null when none. Claimed by the host page, never verified: display data only.
external_user_namestringnullableRequired
The visitor display name the embedding page or messaging channel supplied; null when none. Display data only, never verified.
started_atstringnullableRequired
When the conversation started (ISO 8601, UTC).
created_atstringnullableRequired
When the conversation was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the conversation last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/conversations/by_session/<SESSION_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "conversation",
  "id": 1,
  "session_id": "api_Q7mK2xVb9RtL4nWc8ZpH3sYd6JfA1gEu5oTi0vNq",
  "chatbot_id": 1,
  "status": "active",
  "channel": "api",
  "is_reviewed": false,
  "review_status": {
    "id": 1,
    "name": "Needs review",
    "color": "neutral",
    "counts_as_reviewed": false
  },
  "handoff_requested": false,
  "handoff_reason": null,
  "external_user_id": null,
  "external_user_name": null,
  "started_at": "2026-01-01T00:00:00+00:00",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/conversations/{id}

Retrieve a conversation

Returns one conversation: the surface it came from (channel), its review state and its handoff flag. Its messages are listed by GET /conversations/{id}/messages. A deleted conversation, or one of another account, is 404 NOT_FOUND.

Required scope: conversations:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Conversation id
Integer.
Placeholder in the samples: <CONVERSATION_ID>
Get it from
- POST /v1/chat returns it as conversation_id
- GET /v1/conversations returns it as data[].id
- GET /v1/conversations/by_session/{sessionId} returns it as id
- GET /v1/messages/{id} returns it as conversation_id
- GET /v1/customers/{id}/timeline returns it as data[].chat_session_id
- Webhook conversation.started carries it as data.object.id
- Webhook conversation.handoff.requested carries it as data.object.id
- POST /chat/stream returns no conversation id: read session_id from its metadata event, then look the conversation up with GET /conversations/by_session/{sessionId}.

Path parameters

idintegerRequired
The conversation id.

Responses

200
ConversationResource
objectstringRequired
Alwaysconversation
idintegerRequired
The conversation id, used in every /conversations/{id} path. Messages carry it as conversation_id.
session_idstringRequired
The session id the surface minted; its prefix names that surface (api_, ws_, widget-, sess_, ch-). Send an api_ one back to POST /chat to continue the conversation.
chatbot_idintegerRequired
The chatbot the conversation is with.
statusstringRequired
Lifecycle state. Conversations are created active; completed and abandoned are reserved values no current surface sets.
Possible valuesactivecompletedabandoned
channelstringRequired
The surface the conversation arrived through: api, widget, direct_link (hosted agent page), dashboard (Test Chat), a messaging platform, or unknown for an older conversation whose origin was never recorded.
Possible valueswidgetdirect_linkdashboardapitelegramwhatsappfacebookinstagramslackdiscordlineviberwechatsmsunknown
is_reviewedbooleanRequired
Whether the effective review status counts as reviewed (review_status.counts_as_reviewed).
review_statusobjectRequired
The conversation's effective status in the account's review catalogue. POST /conversations/{id}/review sets it.
handoff_requestedbooleanRequired
Whether the conversation asked for a human. conversation.handoff.requested fires once, when this turns true.
handoff_reasonstringnullableRequired
Why the handoff was requested, when a reason was recorded.
external_user_idstringnullableRequired
The visitor id the embedding page passed to the widget or hosted agent page, or the platform chat id on a messaging channel; null when none. Claimed by the host page, never verified: display data only.
external_user_namestringnullableRequired
The visitor display name the embedding page or messaging channel supplied; null when none. Display data only, never verified.
started_atstringnullableRequired
When the conversation started (ISO 8601, UTC).
created_atstringnullableRequired
When the conversation was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the conversation last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/conversations/<CONVERSATION_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "conversation",
  "id": 1,
  "session_id": "api_Q7mK2xVb9RtL4nWc8ZpH3sYd6JfA1gEu5oTi0vNq",
  "chatbot_id": 1,
  "status": "active",
  "channel": "api",
  "is_reviewed": false,
  "review_status": {
    "id": 1,
    "name": "Needs review",
    "color": "neutral",
    "counts_as_reviewed": false
  },
  "handoff_requested": false,
  "handoff_reason": null,
  "external_user_id": null,
  "external_user_name": null,
  "started_at": "2026-01-01T00:00:00+00:00",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/conversations/{id}

Delete a conversation

Permanently deletes the conversation with its messages and the Call Action run logs captured in it. There is no undo. Use it for data-subject requests or to clear test traffic. Emits conversation.ended (there is no separate deletion event): a receiver that needs to tell a deletion apart should follow up with GET /conversations/{id}, which is 404 once the conversation is deleted.

Required scope: conversations:write
Idempotency: Accepts Idempotency-Key
Webhook events: conversation.ended
Rate limits

Before you call

id(path)Conversation id
Integer.
Placeholder in the samples: <CONVERSATION_ID>
Get it from
- POST /v1/chat returns it as conversation_id
- GET /v1/conversations returns it as data[].id
- GET /v1/conversations/by_session/{sessionId} returns it as id
- GET /v1/messages/{id} returns it as conversation_id
- GET /v1/customers/{id}/timeline returns it as data[].chat_session_id
- Webhook conversation.started carries it as data.object.id
- Webhook conversation.handoff.requested carries it as data.object.id
- POST /chat/stream returns no conversation id: read session_id from its metadata event, then look the conversation up with GET /conversations/by_session/{sessionId}.

Path parameters

idintegerRequired
The conversation id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Responses

200
Success.
objectstringRequired
Alwaysconversation
idintegerRequired
deletedbooleanRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X DELETE 'https://api.agentency.com/v1/conversations/<CONVERSATION_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "conversation",
  "id": 1,
  "deleted": true
}

/v1/conversations/{id}/messages

List a conversation's messages

Returns the conversation's turns, newest first and cursor-paginated (send order=asc to read the thread from its first turn). Each Message carries the visitor's text (query), the reply (response), its verdict and confidence, the citations it drew on and the turn's token cost.

Required scope: conversations:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Conversation id
Integer.
Placeholder in the samples: <CONVERSATION_ID>
Get it from
- POST /v1/chat returns it as conversation_id
- GET /v1/conversations returns it as data[].id
- GET /v1/conversations/by_session/{sessionId} returns it as id
- GET /v1/messages/{id} returns it as conversation_id
- GET /v1/customers/{id}/timeline returns it as data[].chat_session_id
- Webhook conversation.started carries it as data.object.id
- Webhook conversation.handoff.requested carries it as data.object.id
- POST /chat/stream returns no conversation id: read session_id from its metadata event, then look the conversation up with GET /conversations/by_session/{sessionId}.

Path parameters

idintegerRequired
The conversation id.

Query parameters

limitintegerOptional
Page size, clamped to 1–100.
Default: 20Minimum: 1Maximum: 100
starting_afterstringOptional
Cursor from a previous page's next_cursor: returns the page after it. A cursor minted for another list, sort or order is 422 INVALID_CURSOR.
ending_beforestringOptional
Cursor from a previous page's previous_cursor: returns the page before it. Wins when both cursors are sent.
created[gte]stringOptional
Only rows created on or after this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.
created[lte]stringOptional
Only rows created on or before this instant: YYYY-MM-DD (whole UTC day) or an RFC 3339 timestamp with a zone. Anything else is 422 INVALID_PARAMETER.

Responses

200
Success.
objectstringRequired
Alwayslist
dataarray of MessageRequired
has_morebooleanRequired
next_cursorstringnullableRequired
previous_cursorstringnullableRequired
urlstringRequired
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
422
Validation failed. See error.details.
Error codesINVALID_CURSOR INVALID_PARAMETER
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/conversations/<CONVERSATION_ID>/messages' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "id": 1,
      "conversation_id": 1,
      "chatbot_id": 1,
      "query": "How do refunds work?",
      "response": "Refunds are issued to the original payment method within 5 business days.",
      "status": "answered",
      "confidence_score": 96.3,
      "verdict": "full",
      "retrieval_confidence": 91.31,
      "media": [],
      "feedback": null,
      "sources": [],
      "input_tokens": 33,
      "output_tokens": 157,
      "cost_usd": "0.000000",
      "currency": "USD",
      "created_at": "2026-01-01T00:00:00+00:00"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "previous_cursor": null,
  "url": "/v1/conversations/1/messages"
}

/v1/messages/{id}

Retrieve a message

Returns one message — one turn: the visitor's text and the reply — with its verdict, confidence, citations and cost. conversation_id names the conversation it belongs to. A message of another account is 404 NOT_FOUND.

Required scope: conversations:read
Idempotency: Read-only
Rate limits

Before you call

id(path)Message id
Integer.
Placeholder in the samples: <MESSAGE_ID>
Get it from
- POST /v1/chat returns it as id
- GET /v1/conversations/{id}/messages returns it as data[].id
- Webhook conversation.message.created carries it as data.object.id
- POST /chat/stream sends it as query_id in its metadata event (and in the JSON replay of an idempotent retry).

Path parameters

idintegerRequired
The message id.

Responses

200
MessageResource
One chat turn: the visitor's message and the assistant's reply.
objectstringRequired
Alwaysmessage
idintegerRequired
The message id, for GET /messages/{id} and POST /messages/{id}/feedback.
conversation_idintegerRequired
The conversation the message belongs to (GET /conversations/{id}).
chatbot_idintegerRequired
The chatbot that replied.
querystringnullableRequired
The visitor's message.
responsestringnullableRequired
The assistant's reply.
statusstringRequired
Outcome, derived from verdict when there is one: answered, partial_answer or no_answer.
confidence_scorenumberRequired
Answer confidence, 0–100, derived from verdict: error → 0; none → retrieval_confidence ÷ 10 (≤ 10); clarify / contact / meta / small_talk keep retrieval_confidence (usually 0 — these turns run no retrieval); full / partial → the evidence strength (retrieval_confidence: the rank-weighted relevance of the knowledge chunks) fused with the answer grounding (how much of each sentence of the reply one of its sources supports) in log-odds space, a partial answer carrying a lower prior — so a reply that restates strong sources reads high and one that wanders off them reads lower than its evidence. Under the calibrated rollback model it is instead the verdict band (partial 40–70, full 70–100) when the answer verdict is enabled (CHAT_VERDICT_ENABLED) and equals retrieval_confidence otherwise; messages stored before the verdict contract carry that retrieval number here and null in retrieval_confidence. Show this number as "confidence in the answer"; use retrieval_confidence for "how well the knowledge base matched".
Minimum: 0Maximum: 100
verdictstringnullableRequired
What the reply is: full / partial answer from the knowledge base, none (refusal — no information), clarify (asked a clarifying question), contact (handoff / contact details), meta (about the assistant itself), small_talk, error (the fallback reply), or general (a general knowledge-mode chatbot answered from general knowledge because its knowledge base did not cover the question). confidence_score is derived from it. null on messages stored before the verdict contract.
Possible valuesfullpartialnoneclarifycontactmetasmall_talkerrorgeneralnull
retrieval_confidencenumbernullableRequired
Knowledge match (evidence strength), 0–100: the rank-weighted relevance score of the knowledge chunks retrieved for the turn — the best passages carry the number (the plain mean under the calibrated rollback model). Says how well the knowledge base matched the question, not whether the reply answered it — a refusal over well-matched sources can score high here while confidence_score stays ≤ 10. null on messages stored before the verdict contract.
Minimum: 0Maximum: 100
mediaarray of ChatMediaItemRequired
Media cards the answer offered; [] when none.
feedbackstringnullableRequired
The rating recorded on the reply (POST /messages/{id}/feedback), or null when it has none.
Possible valuespositivenegativenull
sourcesarray of objectRequired
Citations the answer drew on.
input_tokensintegerRequired
Prompt tokens the turn used.
output_tokensintegerRequired
Completion tokens the turn used.
cost_usdstringRequired
Provider cost of the turn in USD, as a decimal string.
currencystringRequired
AlwaysUSD
created_atstringnullableRequired
When the turn was stored (ISO 8601, UTC).
Format: date-time
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X GET 'https://api.agentency.com/v1/messages/<MESSAGE_ID>' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"

Response

Example 200 response

json

{
  "object": "message",
  "id": 1,
  "conversation_id": 1,
  "chatbot_id": 1,
  "query": "How do refunds work?",
  "response": "Refunds are issued to the original payment method within 5 business days.",
  "status": "answered",
  "confidence_score": 96.3,
  "verdict": "full",
  "retrieval_confidence": 91.31,
  "media": [],
  "feedback": null,
  "sources": [],
  "input_tokens": 33,
  "output_tokens": 157,
  "cost_usd": "0.000000",
  "currency": "USD",
  "created_at": "2026-01-01T00:00:00+00:00"
}

/v1/conversations/{id}/review

Set a conversation's review state

Marks the conversation reviewed or back to needing review, and returns it updated. reviewed: true (the default when the body omits it) moves it to the account catalogue's system "Reviewed" status; reviewed: false moves it to "Needs review". Either replaces a custom status set in the dashboard. The call sets a state rather than toggling one, so a retry never flips it back. It emits no webhook event.

Required scope: conversations:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Conversation id
Integer.
Placeholder in the samples: <CONVERSATION_ID>
Get it from
- POST /v1/chat returns it as conversation_id
- GET /v1/conversations returns it as data[].id
- GET /v1/conversations/by_session/{sessionId} returns it as id
- GET /v1/messages/{id} returns it as conversation_id
- GET /v1/customers/{id}/timeline returns it as data[].chat_session_id
- Webhook conversation.started carries it as data.object.id
- Webhook conversation.handoff.requested carries it as data.object.id
- POST /chat/stream returns no conversation id: read session_id from its metadata event, then look the conversation up with GET /conversations/by_session/{sessionId}.

Path parameters

idintegerRequired
The conversation id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

reviewedbooleanOptional
The review state to set: true marks the conversation reviewed, false marks it as needing review. Defaults to true when omitted.

Responses

200
ConversationResource
objectstringRequired
Alwaysconversation
idintegerRequired
The conversation id, used in every /conversations/{id} path. Messages carry it as conversation_id.
session_idstringRequired
The session id the surface minted; its prefix names that surface (api_, ws_, widget-, sess_, ch-). Send an api_ one back to POST /chat to continue the conversation.
chatbot_idintegerRequired
The chatbot the conversation is with.
statusstringRequired
Lifecycle state. Conversations are created active; completed and abandoned are reserved values no current surface sets.
Possible valuesactivecompletedabandoned
channelstringRequired
The surface the conversation arrived through: api, widget, direct_link (hosted agent page), dashboard (Test Chat), a messaging platform, or unknown for an older conversation whose origin was never recorded.
Possible valueswidgetdirect_linkdashboardapitelegramwhatsappfacebookinstagramslackdiscordlineviberwechatsmsunknown
is_reviewedbooleanRequired
Whether the effective review status counts as reviewed (review_status.counts_as_reviewed).
review_statusobjectRequired
The conversation's effective status in the account's review catalogue. POST /conversations/{id}/review sets it.
handoff_requestedbooleanRequired
Whether the conversation asked for a human. conversation.handoff.requested fires once, when this turns true.
handoff_reasonstringnullableRequired
Why the handoff was requested, when a reason was recorded.
external_user_idstringnullableRequired
The visitor id the embedding page passed to the widget or hosted agent page, or the platform chat id on a messaging channel; null when none. Claimed by the host page, never verified: display data only.
external_user_namestringnullableRequired
The visitor display name the embedding page or messaging channel supplied; null when none. Display data only, never verified.
started_atstringnullableRequired
When the conversation started (ISO 8601, UTC).
created_atstringnullableRequired
When the conversation was created (ISO 8601, UTC).
updated_atstringnullableRequired
When the conversation last changed (ISO 8601, UTC).
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/conversations/<CONVERSATION_ID>/review' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "reviewed": true
}'

Response

Example 200 response

json

{
  "object": "conversation",
  "id": 1,
  "session_id": "api_Q7mK2xVb9RtL4nWc8ZpH3sYd6JfA1gEu5oTi0vNq",
  "chatbot_id": 1,
  "status": "active",
  "channel": "api",
  "is_reviewed": true,
  "review_status": {
    "id": 1,
    "name": "Reviewed",
    "color": "success",
    "counts_as_reviewed": true
  },
  "handoff_requested": false,
  "handoff_reason": null,
  "external_user_id": null,
  "external_user_name": null,
  "started_at": "2026-01-01T00:00:00+00:00",
  "created_at": "2026-01-01T00:00:00+00:00",
  "updated_at": "2026-01-01T00:00:00+00:00"
}

/v1/messages/{id}/feedback

Rate a message's reply

Records a thumbs up (positive) or thumbs down (negative) on the reply and returns the message with feedback set. A later call overwrites the earlier rating; the API cannot clear it. It emits no webhook event.

Required scope: conversations:write
Idempotency: Accepts Idempotency-Key
Webhook events: None
Rate limits

Before you call

id(path)Message id
Integer.
Placeholder in the samples: <MESSAGE_ID>
Get it from
- POST /v1/chat returns it as id
- GET /v1/conversations/{id}/messages returns it as data[].id
- Webhook conversation.message.created carries it as data.object.id
- POST /chat/stream sends it as query_id in its metadata event (and in the JSON replay of an idempotent retry).

Path parameters

idintegerRequired
The message id.

Header parameters

Idempotency-KeystringOptional
Makes a retry safe. The first 2xx answer is stored for 24 h and replayed for the same key with Idempotency-Replayed: true; a retry while the first request runs is 409 IDEMPOTENCY_IN_FLIGHT; the same key with a different payload is 422 IDEMPOTENCY_KEY_REUSED; a malformed key is 400 INVALID_IDEMPOTENCY_KEY.
Min length: 16Max length: 128Pattern: ^[A-Za-z0-9_-]+$

Request body

feedbackstringRequired
The rating of the reply: positive (thumbs up) or negative (thumbs down). It replaces any earlier rating of the same message.
Possible valuespositivenegative

Responses

200
MessageResource
One chat turn: the visitor's message and the assistant's reply.
objectstringRequired
Alwaysmessage
idintegerRequired
The message id, for GET /messages/{id} and POST /messages/{id}/feedback.
conversation_idintegerRequired
The conversation the message belongs to (GET /conversations/{id}).
chatbot_idintegerRequired
The chatbot that replied.
querystringnullableRequired
The visitor's message.
responsestringnullableRequired
The assistant's reply.
statusstringRequired
Outcome, derived from verdict when there is one: answered, partial_answer or no_answer.
confidence_scorenumberRequired
Answer confidence, 0–100, derived from verdict: error → 0; none → retrieval_confidence ÷ 10 (≤ 10); clarify / contact / meta / small_talk keep retrieval_confidence (usually 0 — these turns run no retrieval); full / partial → the evidence strength (retrieval_confidence: the rank-weighted relevance of the knowledge chunks) fused with the answer grounding (how much of each sentence of the reply one of its sources supports) in log-odds space, a partial answer carrying a lower prior — so a reply that restates strong sources reads high and one that wanders off them reads lower than its evidence. Under the calibrated rollback model it is instead the verdict band (partial 40–70, full 70–100) when the answer verdict is enabled (CHAT_VERDICT_ENABLED) and equals retrieval_confidence otherwise; messages stored before the verdict contract carry that retrieval number here and null in retrieval_confidence. Show this number as "confidence in the answer"; use retrieval_confidence for "how well the knowledge base matched".
Minimum: 0Maximum: 100
verdictstringnullableRequired
What the reply is: full / partial answer from the knowledge base, none (refusal — no information), clarify (asked a clarifying question), contact (handoff / contact details), meta (about the assistant itself), small_talk, error (the fallback reply), or general (a general knowledge-mode chatbot answered from general knowledge because its knowledge base did not cover the question). confidence_score is derived from it. null on messages stored before the verdict contract.
Possible valuesfullpartialnoneclarifycontactmetasmall_talkerrorgeneralnull
retrieval_confidencenumbernullableRequired
Knowledge match (evidence strength), 0–100: the rank-weighted relevance score of the knowledge chunks retrieved for the turn — the best passages carry the number (the plain mean under the calibrated rollback model). Says how well the knowledge base matched the question, not whether the reply answered it — a refusal over well-matched sources can score high here while confidence_score stays ≤ 10. null on messages stored before the verdict contract.
Minimum: 0Maximum: 100
mediaarray of ChatMediaItemRequired
Media cards the answer offered; [] when none.
feedbackstringnullableRequired
The rating recorded on the reply (POST /messages/{id}/feedback), or null when it has none.
Possible valuespositivenegativenull
sourcesarray of objectRequired
Citations the answer drew on.
input_tokensintegerRequired
Prompt tokens the turn used.
output_tokensintegerRequired
Completion tokens the turn used.
cost_usdstringRequired
Provider cost of the turn in USD, as a decimal string.
currencystringRequired
AlwaysUSD
created_atstringnullableRequired
When the turn was stored (ISO 8601, UTC).
Format: date-time
400
A tenant selector header named a tenant other than the API key's own (ACCOUNT_SELECTOR_NOT_SUPPORTED): an all-digit X-Account-Id other than the key owner's id or, while workspaces.context_enabled is on, an X-Workspace-Id other than the key's workspace (ws_ prefix optional, case-insensitive). A header naming the key's own tenant, or a non-numeric X-Account-Id, is ignored; a key cannot switch tenants, so send neither. A mutation that honours Idempotency-Key also returns INVALID_IDEMPOTENCY_KEY when that header is not 16–128 [A-Za-z0-9_-] characters.
Error codesACCOUNT_SELECTOR_NOT_SUPPORTED INVALID_IDEMPOTENCY_KEY
401
Missing or invalid API key.
Error codesUNAUTHENTICATED
403
The API key is missing a required scope.
Error codesACCOUNT_SUSPENDED INSUFFICIENT_SCOPE
404
The resource does not exist on this account.
Error codesNOT_FOUND
409
The request conflicts with the current resource state.
Error codesIDEMPOTENCY_IN_FLIGHT
422
Validation failed. See error.details.
Error codesIDEMPOTENCY_KEY_REUSED VALIDATION_FAILED
429
Rate limited. Honour the Retry-After header before retrying.
Error codesRATE_LIMITED
500
Unexpected server error. Retry with the same Idempotency-Key.
Error codesSERVER_ERROR

Request

curl

curl -X POST 'https://api.agentency.com/v1/messages/<MESSAGE_ID>/feedback' \
  -H "Authorization: Bearer <YOUR_KEY>" \
  -H "Content-Type: application/json"
  -d '{
  "feedback": "feedback"
}'

Response

Example 200 response

json

{
  "object": "message",
  "id": 1,
  "conversation_id": 1,
  "chatbot_id": 1,
  "query": "How do refunds work?",
  "response": "Refunds are issued to the original payment method within 5 business days.",
  "status": "answered",
  "confidence_score": 96.3,
  "verdict": "full",
  "retrieval_confidence": 91.31,
  "media": [],
  "feedback": "positive",
  "sources": [],
  "input_tokens": 33,
  "output_tokens": 157,
  "cost_usd": "0.000000",
  "currency": "USD",
  "created_at": "2026-01-01T00:00:00+00:00"
}

About Conversations

IDs on this page

/v1/conversations

Query parameters

Responses

See also

Request

Response

/v1/conversations/by_session/{sessionId}

Path parameters

Responses

See also

Request

Response

/v1/conversations/{id}

Path parameters

Responses

See also

Request

Response

/v1/conversations/{id}

Path parameters

Header parameters

Responses

See also

Request

Response

/v1/conversations/{id}/messages

Path parameters

Query parameters

Responses

See also

Request

Response

/v1/messages/{id}

Path parameters

Responses

See also

Request

Response

/v1/conversations/{id}/review

Path parameters

Header parameters

Request body

Responses

See also

Request

Response

/v1/messages/{id}/feedback

Path parameters

Header parameters

Request body

Responses

See also

Request

Response