Skip to main content
POST
Start a conversation at a trigger step
A trigger step is an entry point in a published chat flow. Send its agent ID, trigger ID and channel identifier. 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 builder’s Sample Request & Testing panel provides the request for your 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