Skip to main content
POST
Start a conversation at a trigger step
The request body carries three identifiers: the agent ID, the trigger ID, and the end user’s channel identifier, such as a WhatsApp number. Each request starts a new conversation. Existing open conversations for the same end user, inbox and channel are abandoned first. The trigger starts the flow but sends nothing itself. A downstream channel step sends the first message. The Trigger gambit’s Start from your system section shows the endpoint and request body for that trigger. Keys that can start this trigger lists eligible keys.

Authorizations

Authorization
string
header
required

An API key (tars_sk_…) sent as Authorization: Bearer <key>. Each operation names the permission it needs. Create keys in Settings → Integrations → API keys.

Body

application/json

Start a conversation at a trigger step of a chat agent.

agentId
string
required

The chat agent id.

Maximum string length: 128
triggerId
integer
required

The trigger step's number in the agent's flow.

Required range: x >= 0
channelUserId
string
required

The user's identifier on the trigger step's channel. For WhatsApp, the phone number in international format.

data
object

Each top-level key becomes a {{trigger.}} variable in the flow.

Response

The conversation started.

The conversation that started.

conversationId
string
required
status
any
required