Send a human reply

POST

/api/conversations/{id}/reply

• Production

Sends a reply to a conversation on behalf of a human agent. This bypasses the AI pipeline entirely — the message is delivered directly to the customer via the conversation’s channel (email, WhatsApp, etc.). The conversation must be in ‘human_managed’ status (use the take-over endpoint first). The reply is delivered via a Temporal workflow signal, so delivery is guaranteed even under transient failures.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

The unique identifier of the conversation to reply to.

Request Body

object

content

required

The reply message text to send to the customer.

string

>= 1 characters

Example

Hi Alex, your order #4521 is currently in transit and should arrive by March 27. Here is your tracking link: https://tracking.example.com/TRK-10123456784

Responses

200

The reply was accepted and will be delivered to the customer.

Simple success acknowledgment returned by action endpoints (reply, resolve, take-over, etc.).

object

ok

required

Always true on success.

boolean

Example

true

400

The request body is invalid (e.g., empty content).

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]

404

No conversation exists with the given ID in the authenticated tenant. An API key restricted to a brand or workspace receives the same answer for a conversation in a workspace outside its restriction.

Standard error response returned by all endpoints on failure.

object

error

required

A human-readable error message describing what went wrong.

string

Example

Conversation not found

code

A machine-readable reason on some refusals, for example ‘key_lock’ when an API key’s brand or workspace restriction does not cover the action.

string

Example

key_lock

missing_scopes

On a 403 for an API key without a scope the endpoint requires: the scopes the key lacks.

Array<string>

Example

[
  "mcp:write"
]

entryId

On a 409 with code duplicate_question or duplicate_rule_text: the knowledge base entry or policy that already holds the question or rule text.

string format: uuid

Example

11223344-5566-4788-99aa-bbccddeeff00

connectionId

On a 422 about one MCP connection a request names, from an assignment or an agent create or update (a connection that does not exist, one listed twice, or one that does not declare a tool named): the connection, as the request named it.

string

undeclaredTools

On the same 422: the tool names the connection does not declare.

Array<string>

Example

[
  "get_orders"
]

declaredTools

On the same 422: the tools the connection declares.

Array<string>

Example

[
  "get_order",
  "search_orders"
]