Start a new outbound conversation

POST

/api/conversations/compose

• Production

Creates a new conversation initiated by a human agent (outbound). Specify the target contact by providing either a contactId (for existing contacts) or contactEmail/contactPhone (to create or find a contact). The message is sent via the specified channel. This starts an OutboundConversationWorkflow in Temporal.

Authorizations

• bearerAuth

Request Body

object

workspaceId

required

The workspace to create the conversation in.

string format: uuid

Example

a1b2c3d4-e5f6-7890-abcd-ef1234567890

channelId

required

The channel to send the message through (email, WhatsApp, etc.).

string format: uuid

Example

d4e5f6a7-b8c9-4123-8567-890abcdef012

contactId

The ID of an existing contact to message. Provide this OR contactEmail/contactPhone, not both.

string format: uuid

Example

f7e8d9c0-b1a2-4456-8890-abcdef123456

contactEmail

Email address of the recipient. Used when composing to a new or unresolved contact via email channel.

string format: email

Example

alex.doe@example.com

contactPhone

Phone number of the recipient in E.164 format. Used when composing via WhatsApp or SMS channel.

string

>= 1 characters

contactName

Display name for the recipient. Used when creating a new contact.

string

Example

Alex Doe

subject

Subject line for the conversation. Required for email channels, optional for others.

string

Example

Follow-up: Your recent order inquiry

content

required

The message text to send.

string

>= 1 characters

Example

Dear Alex, I wanted to follow up on your recent inquiry about order #4521...

Responses

200

The outbound conversation was created and the message is being delivered.

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

object

ok

required

Always true on success.

boolean

Example

true

404

The workspace is not one of your account’s, or is outside the API key’s brand or workspace restriction (Workspace not found), or the channel is not a channel of that workspace (Channel not found). Nothing is created or sent.

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"
]

422

Validation error, for example no contact identifier was provided.

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"
]