Start conversations API

curl -X POST \
  https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channelUserId": "+15551234567",
    "data": {
      "order_id": "A-1042",
      "amount": "49.00"
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channelUserId: "+15551234567",
      data: { order_id: "A-1042", amount: "49.00" }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channelUserId": "+15551234567",
        "data": {"order_id": "A-1042", "amount": "49.00"},
    },
)

data = response.json()

{
  "success": true,
  "conversationId": "CONVERSATION_ID",
  "messagesQueued": 0,
  "status": "started"
}

POST

api

triggers

{convId}

{gid}

curl -X POST \
  https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channelUserId": "+15551234567",
    "data": {
      "order_id": "A-1042",
      "amount": "49.00"
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channelUserId: "+15551234567",
      data: { order_id: "A-1042", amount: "49.00" }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channelUserId": "+15551234567",
        "data": {"order_id": "A-1042", "amount": "49.00"},
    },
)

data = response.json()

{
  "success": true,
  "conversationId": "CONVERSATION_ID",
  "messagesQueued": 0,
  "status": "started"
}

This reference covers the trigger endpoint. The trigger gambit’s editor generates a ready request under Sample Request & Testing, with the real URL for your region and a typed sample body. Copy it from there instead of assembling the URL by hand. The same panel holds a Test Trigger form. Paste an API key and a channelUserId value, then click Send Test. This fires a real trigger call and reports the result beside the button.

Request

string

required

The agent’s public ID. The same value the embed snippet uses as data-convid.

string

required

The numeric ID of the trigger gambit inside the published flow.

string

required

Bearer YOUR_API_KEY, a key with the Triggers permission.

string

required

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

object

Payload fields that become trigger variables in the flow.

curl -X POST \
  https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "channelUserId": "+15551234567",
    "data": {
      "order_id": "A-1042",
      "amount": "49.00"
    }
  }'

const response = await fetch(
  "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.TARS_API_KEY}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      channelUserId: "+15551234567",
      data: { order_id: "A-1042", amount: "49.00" }
    })
  }
);

const data = await response.json();

import os
import requests

response = requests.post(
    "https://us.api.hellotars.com/api/triggers/YOUR_AGENT_ID/YOUR_TRIGGER_ID",
    headers={
        "Authorization": f"Bearer {os.environ['TARS_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "channelUserId": "+15551234567",
        "data": {"order_id": "A-1042", "amount": "49.00"},
    },
)

data = response.json()

Trigger variables

Every field inside data becomes a trigger variable, available throughout the flow as {{trigger.field}}. The trigger gambit declares typed fields in the builder, and the generated sample body mirrors that schema. For example, data.order_id above is read in any gambit as {{trigger.order_id}}.

Behavior

A trigger call passing three gates for the key, the published flow, and the channel account, then abandoning any open conversation before the flow runs at the trigger gambit

The call starts a new conversation at the trigger gambit and runs the flow from there. Any conversation the same end user already has open on that deployment and channel is marked abandoned first. The trigger gambit must have a channel account selected, and the flow must be published.

Response

boolean

true on a successful trigger.

string

The ID of the conversation the trigger started.

number

Reserved. Always 0.

string

started when the flow began at the trigger gambit.

{
  "success": true,
  "conversationId": "CONVERSATION_ID",
  "messagesQueued": 0,
  "status": "started"
}

Errors

Error responses return { "success": false, "error": "…" } with one of these statuses.

Status	Cause
`400`	URL does not match `/api/triggers/{convId}/{gid}`, or the body is missing `channelUserId`
`400`	The flow is not published, the gambit is not a trigger, or the trigger has no channel account selected
`400`	The trigger’s channel account is not active, or it is not bound to an inbox
`401`	Missing `Authorization` header, or an invalid or revoked key
`403`	Key belongs to another organization or another agent, or lacks the Triggers permission
`404`	No agent matches the ID, or the trigger gambit is not in the published flow
`429`	Rate limit exceeded. Retry after the `Retry-After: 60` header elapses

Authorizations

Authorization

string

header

required

API key sent as Authorization: Bearer YOUR_API_KEY. Campaign endpoints use campaign-scoped keys; the rest use organization or agent keys with the matching permission.

Path Parameters

convId

string

required

The agent's public ID

gid

string

required

The numeric ID of the trigger gambit

Pattern: ^\d+$

Body

application/json

channelUserId

string

required

The end user's identifier on the trigger's channel

data

object

Payload fields that become trigger variables in the flow

Response

Conversation started

success

boolean

required

True when the trigger was accepted.

conversationId

string

The conversation the trigger started or advanced. Use it to correlate later activity.

messagesQueued

number

How many messages the flow queued for delivery in response.

status

string

Always started on a successful call.

Allowed value: "started"

Welcome

Core concepts

Guides

Developer

Start conversations API

Request

Trigger variables

Behavior

Response

Errors

Authorizations

Path Parameters

Body

Response

​Request

​Trigger variables

​Behavior

​Response

​Errors

​Related pages

Authorizations

Path Parameters

Body

Response

Request

Trigger variables

Behavior

Response

Errors

Related pages