Console API

Conversations

15 endpoints.

GET/api/v1/admin/conversations

List conversations

Parameters

Name	In	Type	Description
`business_id`	query	`string (uuid) \| null`	Scope contact hydration to this business. When provided, each list item's `contact` field is the business_contact record for that business; without it, contact is picked from any business the consumer is known to (first match).
`status`	query	`string \| null`	OPEN \| CLOSED \| SNOOZED
`assigned_to`	query	`integer \| null`
`unread_only`	query	`boolean`	default false
`needs_attention`	query	`boolean \| null`	Filter to conversations whose business contact is flagged needs-attention. Requires `business_id` — contacts are per-business while consumers are global, so an unscoped filter would match contacts flagged in other businesses.
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ConversationListItem__

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationListItem[]

ConversationListItem[] fields

Field	Type	Description
`id`required	`string`
`consumer_id`	`string \| null`
`status`required	`string`
`assigned_to`	`integer \| null`
`ai_enabled`	`boolean`	default true
`ai_mode`	`string`	default "AUTONOMOUS"
`last_message_at`	`string (date-time) \| null`
`last_message_preview`	`string \| null`
`last_message_channel`	`string \| null`
`unread_count`	`integer`	default 0
`message_count`	`integer`	default 0
`snoozed_until`	`string (date-time) \| null`
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`reply_channel`	`ReplyChannelData \| null`	ReplyChannelData fields ReplyChannelData (not expanded)
`contact`	`ConversationContactSummary \| null`	ConversationContactSummary fields ConversationContactSummary (not expanded)
`businesses`	`ConversationBusinessSummary[]`	default [] ConversationBusinessSummary[] fields Nested object (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

Field	Type	Description
`total`	`integer \| null`
`total_count`	`integer \| null`
`page`	`integer \| null`
`per_page`	`integer \| null`

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations

Create or fetch conversation for a contact (idempotent)

Start a conversation with a contact from the console. Returns 200 with the existing conversation when one already exists for the contact's consumer (idempotent). Passing `initial_message` sends the first outbound atomically.

Console-created conversations default to `ai_enabled=True`, `ai_mode='AUTONOMOUS'` — the bot drives the thread out of the box. Operators opt out via PATCH /conversations/{id} or by flipping the contact-level `auto_contact_enabled` toggle (which cascades here).

Parameters

Name	In	Type	Description
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonConversationCreateBody

Field Type Description

business_idrequired string

contact_idrequired string

channel

string | null

IMESSAGE (only supported channel today)

initial_message

MessageSendBody | null

MessageSendBody fields

Field	Type	Description
`body`required	`string`	min length 1
`attachments`	`MessageAttachment[]`	MessageAttachment[] fields MessageAttachment (not expanded)
`content_type`	`string`	TEXT \| MEDIA default "TEXT"
`idempotency_key`	`string \| null`
`channel`	`string \| null`

idempotency_key string | null

Responses

200Successful Response

application/jsonSuccessResponse_ConversationCreateResult_

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationCreateResult

ConversationCreateResult fields

Field Type Description

conversationrequired

ConversationData

ConversationData fields

ConversationData, expanded above.

message

MessageData | null

MessageData fields

Field	Type	Description
`id`required	`string`
`conversation_id`required	`string`
`consumer_id`required	`string`
`direction`required	`string`
`sender_type`required	`string`
`sender_id`	`string \| null`
`sender_display_name`	`string \| null`
`channel`required	`string`
`content_type`required	`string`
`body`	`string \| null`
`attachments`	`(FormSubmissionAttachment \| MessageAttachment)[]`	(FormSubmissionAttachment \| MessageAttachment)[] fields Nested object (not expanded)
`external_id`	`string \| null`
`status`required	`string`
`error_code`	`string \| null`
`error_message`	`string \| null`
`ai_metadata`	`object`
`created_at`required	`string (date-time)`
`delivered_at`	`string (date-time) \| null`
`read_at`	`string (date-time) \| null`

createdrequired boolean

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/conversations/{conversation_id}

Get conversation

Parameters

Name	In	Type	Description
`conversation_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ConversationData_

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationData

ConversationData fields

Field Type Description

idrequired string

consumer_id string | null

statusrequired string

assigned_to integer | null

ai_enabled boolean default true

ai_mode string default "AUTONOMOUS"

last_message_at string (date-time) | null

last_message_preview string | null

last_message_channel string | null

unread_count integer default 0

message_count integer default 0

snoozed_until string (date-time) | null

created_atrequired string (date-time)

updated_atrequired string (date-time)

reply_channel

ReplyChannelData | null

ReplyChannelData fields

Field	Type	Description
`default`	`string \| null`
`available`	`string[]`	default [] string[] fields Nested object (not expanded)

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

PATCH/api/v1/admin/conversations/{conversation_id}

Update conversation

Parameters

Name	In	Type	Description
`conversation_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonConversationUpdateBody

Field	Type	Description
`status`	`string \| null`	OPEN \| CLOSED \| SNOOZED
`assigned_to`	`integer \| null`
`ai_enabled`	`boolean \| null`
`ai_mode`	`string \| null`	AUTONOMOUS \| ASSIST \| OFF
`snoozed_until`	`string (date-time) \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ConversationData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ConversationData`	ConversationData fields ConversationData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/conversations/{conversation_id}/messages

List messages in a conversation

Parameters

Name	In	Type	Description
`conversation_id`required	path	`string (uuid)`
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_MessageData__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`MessageData[]`	MessageData[] fields MessageData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations/{conversation_id}/messages

Send outbound message

Parameters

Name	In	Type	Description
`conversation_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonMessageSendBody

MessageSendBody, expanded above.

Responses

201Successful Response

application/jsonSuccessResponse_MessageData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`MessageData`	MessageData fields MessageData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

DELETE/api/v1/admin/conversations/{conversation_id}/messages/{message_id}

Delete a DRAFT message (ASSIST-mode reject)

Parameters

Name	In	Type
`conversation_id`required	path	`string (uuid)`
`message_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

204Successful Response

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations/{conversation_id}/messages/{message_id}/retry

Retry a FAILED or PENDING outbound message

Parameters

Name	In	Type
`conversation_id`required	path	`string (uuid)`
`message_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_MessageData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`MessageData`	MessageData fields MessageData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations/{conversation_id}/messages/{message_id}/send

Approve and send a DRAFT (e.g. AI-authored) message

Used by the ASSIST-mode approve flow: promotes a DRAFT outbound row to PENDING, stamps ai_metadata.review_status='approved' with the approver's user_id, and publishes to raven. Optional `edited_body` in the body allows inline edits before approval.

Parameters

Name	In	Type
`conversation_id`required	path	`string (uuid)`
`message_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Request body

application/jsonDraftSendBody | null

Field	Type	Description
`edited_body`	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_MessageData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`MessageData`	MessageData fields MessageData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations/{conversation_id}/read

Mark conversation as read (zero unread_count)

Parameters

Name	In	Type	Description
`conversation_id`required	path	`string (uuid)`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ConversationData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ConversationData`	ConversationData fields ConversationData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/conversations/configs

List all conversations config versions (newest first)

Parameters

Name	In	Type	Description
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ConversationsConfigData__

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationsConfigData[]

ConversationsConfigData[] fields

Field	Type	Description
`id`required	`string`
`version`required	`integer`
`is_active`required	`boolean`
`persona_system_prompt`required	`string`
`prompt_version`required	`string`
`classification_provider`required	`string`
`conversational_provider`required	`string`
`summarization_provider`required	`string`
`classification_enabled`required	`boolean`
`conversational_enabled`required	`boolean`
`conversational_multimodal_enabled`	`boolean`	default true
`min_autonomous_confidence`required	`number`
`forbidden_topics`	`string[]`	string[] fields Nested object (not expanded)
`escalation_keywords`	`string[]`	string[] fields Nested object (not expanded)
`max_auto_replies_per_hour_per_consumer`required	`integer`
`max_auto_replies_per_day_global`required	`integer`
`summary_trigger_message_count`required	`integer`
`verbatim_tail_size`required	`integer`
`summary_max_sentences`	`integer`	default 20
`created_at`required	`string (date-time)`
`updated_at`required	`string (date-time)`
`created_by`	`string (uuid) \| null`

metadata

ResponseMetadata | null

ResponseMetadata fields

ResponseMetadata, expanded above.

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

POST/api/v1/admin/conversations/configs

Create a new conversations config version

Inserts a new version that supersedes the current active row. Any field omitted in the body is inherited from the current active version, so callers can submit a small diff.

Parameters

Name	In	Type	Description
`authorization`	header	`string \| null`

Request bodyrequired

application/jsonConversationsConfigCreateBody

Field	Type	Description
`persona_system_prompt`	`string \| null`
`prompt_version`	`string \| null`
`classification_provider`	`string \| null`
`conversational_provider`	`string \| null`
`summarization_provider`	`string \| null`
`classification_enabled`	`boolean \| null`
`conversational_enabled`	`boolean \| null`
`conversational_multimodal_enabled`	`boolean \| null`
`min_autonomous_confidence`	`number \| null`
`forbidden_topics`	`string[] \| null`	string[] \| null fields
`escalation_keywords`	`string[] \| null`	string[] \| null fields
`max_auto_replies_per_hour_per_consumer`	`integer \| null`
`max_auto_replies_per_day_global`	`integer \| null`
`summary_trigger_message_count`	`integer \| null`
`verbatim_tail_size`	`integer \| null`
`summary_max_sentences`	`integer \| null`

Responses

201Successful Response

application/jsonSuccessResponse_ConversationsConfigData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ConversationsConfigData`	ConversationsConfigData fields ConversationsConfigData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/conversations/configs/{version}

Get a conversations config by version

Parameters

Name	In	Type	Description
`version`required	path	`integer`
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ConversationsConfigData_

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ConversationsConfigData`	ConversationsConfigData fields ConversationsConfigData, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/conversations/configs/active

Get the active conversations config

Parameters

Name	In	Type	Description
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_ConversationsConfigData_

Field Type Description

request_idrequired string

success true default true

datarequired

ConversationsConfigData

ConversationsConfigData fields

ConversationsConfigData, expanded above.

metadata

ResponseMetadata | null

ResponseMetadata fields

Field Type Description

pagination

PaginationMetadata | null

PaginationMetadata fields

Field	Type	Description
`limit`required	`integer`
`next_cursor`	`string \| null`
`prev_cursor`	`string \| null`
`has_more`required	`boolean`
`has_prev`	`boolean`	default false
`total_count`	`integer \| null`

status_counts

object | null

object | null fields

Map of string to integer

lifecycle_counts

LifecycleCounts | null

LifecycleCounts fields

Field	Type	Description
`lead`	`integer`	default 0
`prospect`	`integer`	default 0
`customer`	`integer`	default 0
`former_customer`	`integer`	default 0

classification_counts

ClassificationCounts | null

ClassificationCounts fields

Field	Type	Description
`signal`	`object`	object fields Nested object (not expanded)
`touch`	`object`	object fields Nested object (not expanded)
`stage`	`object`	object fields Nested object (not expanded)

meta

ResponseMeta | null

ResponseMeta fields

ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.

GET/api/v1/admin/global-conversations

List conversations across all businesses (admin)

Admin cross-business inbox. Always unscoped. `needs_attention` matches conversations where any linked business_contact is flagged. Each row includes `businesses` (id + name) for UI badges and `contact.business_id` for actions.

Parameters

Name	In	Type	Description
`status`	query	`string \| null`	OPEN \| CLOSED \| SNOOZED
`assigned_to`	query	`integer \| null`
`unread_only`	query	`boolean`	default false
`needs_attention`	query	`boolean \| null`	Filter to conversations where any linked business_contact is flagged needs-attention (cross-business).
`cursor`	query	`string \| null`
`limit`	query	`integer`	default 50
`authorization`	header	`string \| null`

Responses

200Successful Response

application/jsonSuccessResponse_list_ConversationListItem__

Field	Type	Description
`request_id`required	`string`
`success`	`true`	default true
`data`required	`ConversationListItem[]`	ConversationListItem[] fields ConversationListItem, expanded above.
`metadata`	`ResponseMetadata \| null`	ResponseMetadata fields ResponseMetadata, expanded above.
`meta`	`ResponseMeta \| null`	ResponseMeta fields ResponseMeta, expanded above.

400Bad request
401Unauthorized
403Forbidden
404Not found
422Validation error
500Internal server error
503Service unavailable

Error bodies: ErrorResponse. See Errors.