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

w1a2b3c4-5678-9abc-def0-1234567890ab

channelId

required

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

string format: uuid

Example

ch1a2b3c-5678-9abc-def0-1234567890ab

contactId

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

string format: uuid

Example

ct1a2b3c-5678-9abc-def0-1234567890ab

contactEmail

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

string format: email

Example

jan.mueller@acme-customer.de

contactPhone

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

string

>= 1 characters

Example

+4915112345678

contactName

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

string

Example

Jan Mueller

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 Jan, 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

422

Validation error. For example, no contact identifier was provided, or the channel does not exist in the specified workspace.

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