Trigger Conversations API

The Trigger Conversations API starts outbound conversations through an existing VIVI channel. Use it to send appointment reminders, operational alerts, status updates, or other event-driven messages from your backend systems. The endpoint supports Twilio Phone, SIP Trunk, Twilio SMS, and Microsoft Teams & Copilot channels.

Endpoint

POST https://api.vivi.bot/channelsApi/{channelId}/conversations/trigger

API reference

View the complete request and response schema in ReDoc.

Before you start

You need:

A configured Twilio Phone, SIP Trunk, Twilio SMS, or Microsoft Teams & Copilot channel.
The channel ID, available from the channel details page in VIVI.
An active account or workspace API credential and its clientId, clientSecret, audience, and tokenUrl.

See API Credentials for instructions on creating credentials and exchanging them for an access token.

The endpoint accepts only machine-to-machine access tokens. An interactive user token or an API channel’s vivi-api-key will not work.

Request an access token

Exchange your API credentials for an access token. Cache and reuse the token until it is close to expiring.

cURL

curl --request POST "YOUR_TOKEN_URL" \
  --header "Content-Type: application/json" \
  --data '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE",
    "grant_type": "client_credentials"
  }'

Send the returned token on trigger requests as Authorization: Bearer YOUR_ACCESS_TOKEN.

Request body

string

required

The message or voice prompt to send. Maximum 4,000 characters. Use {variable} placeholders to personalize the message for each recipient.

array

required

One or more recipients. The default maximum is 100 recipients per request. Every recipient contains a channel-specific target and optional metadata values.

string

required

The destination. Its accepted format depends on the channel type. Maximum 256 characters.

object

String values used to replace placeholders in messageTemplate. Every recipient must provide every variable used by the template. Maximum encoded size: 4 KB per recipient.

object

Optional string metadata for your own request context. Maximum encoded size: 8 KB.

The API validates the complete batch before dispatching anything. Duplicate targets, invalid targets, or missing template variables reject the entire request.

Channel examples

Replace YOUR_CHANNEL_ID and YOUR_ACCESS_TOKEN in the examples below. The channel ID must belong to the same account as the API credential.

Twilio Phone
SIP Trunk
Twilio SMS
Microsoft Teams

Use an E.164 phone number, including + and the country code. VIVI starts a voice call from the first phone number configured on the channel.

curl --request POST \
  --url "https://api.vivi.bot/channelsApi/YOUR_CHANNEL_ID/conversations/trigger" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 2ccaca2e-08d9-42ec-bfd5-eaa92f43ed22" \
  --data '{
    "messageTemplate": "Hello {firstName}. Your appointment is {appointmentTime}.",
    "recipients": [
      {
        "target": "+14155550123",
        "metadata": {
          "firstName": "Avery",
          "appointmentTime": "Tuesday at 10:30 AM"
        }
      }
    ],
    "metadata": {"source": "scheduling-system"}
  }'

import requests

channel_id = "YOUR_CHANNEL_ID"
access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    f"https://api.vivi.bot/channelsApi/{channel_id}/conversations/trigger",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "2ccaca2e-08d9-42ec-bfd5-eaa92f43ed22",
    },
    json={
        "messageTemplate": "Hello {firstName}. Your appointment is {appointmentTime}.",
        "recipients": [
            {
                "target": "+14155550123",
                "metadata": {
                    "firstName": "Avery",
                    "appointmentTime": "Tuesday at 10:30 AM",
                },
            }
        ],
        "metadata": {"source": "scheduling-system"},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const channelId = "YOUR_CHANNEL_ID";
const accessToken = "YOUR_ACCESS_TOKEN";

const response = await fetch(
  `https://api.vivi.bot/channelsApi/${channelId}/conversations/trigger`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "2ccaca2e-08d9-42ec-bfd5-eaa92f43ed22",
    },
    body: JSON.stringify({
      messageTemplate: "Hello {firstName}. Your appointment is {appointmentTime}.",
      recipients: [
        {
          target: "+14155550123",
          metadata: {
            firstName: "Avery",
            appointmentTime: "Tuesday at 10:30 AM",
          },
        },
      ],
      metadata: { source: "scheduling-system" },
    }),
  },
);

if (!response.ok) throw new Error(`Trigger failed: ${response.status}`);
console.log(await response.json());

Use an E.164 phone number, a PBX extension such as 6000, or a SIP user part containing letters, digits, periods, underscores, or hyphens. VIVI starts a voice call through the configured trunk.

curl --request POST \
  --url "https://api.vivi.bot/channelsApi/YOUR_CHANNEL_ID/conversations/trigger" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: ed700603-2cb2-4118-883e-3f56619b000f" \
  --data '{
    "messageTemplate": "Hello {firstName}. Your appointment is {appointmentTime}.",
    "recipients": [
      {
        "target": "6000",
        "metadata": {
          "firstName": "Avery",
          "appointmentTime": "Tuesday at 10:30 AM"
        }
      }
    ],
    "metadata": {"source": "scheduling-system"}
  }'

import requests

channel_id = "YOUR_CHANNEL_ID"
access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    f"https://api.vivi.bot/channelsApi/{channel_id}/conversations/trigger",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "ed700603-2cb2-4118-883e-3f56619b000f",
    },
    json={
        "messageTemplate": "Hello {firstName}. Your appointment is {appointmentTime}.",
        "recipients": [
            {
                "target": "6000",
                "metadata": {
                    "firstName": "Avery",
                    "appointmentTime": "Tuesday at 10:30 AM",
                },
            }
        ],
        "metadata": {"source": "scheduling-system"},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const channelId = "YOUR_CHANNEL_ID";
const accessToken = "YOUR_ACCESS_TOKEN";

const response = await fetch(
  `https://api.vivi.bot/channelsApi/${channelId}/conversations/trigger`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "ed700603-2cb2-4118-883e-3f56619b000f",
    },
    body: JSON.stringify({
      messageTemplate: "Hello {firstName}. Your appointment is {appointmentTime}.",
      recipients: [
        {
          target: "6000",
          metadata: {
            firstName: "Avery",
            appointmentTime: "Tuesday at 10:30 AM",
          },
        },
      ],
      metadata: { source: "scheduling-system" },
    }),
  },
);

if (!response.ok) throw new Error(`Trigger failed: ${response.status}`);
console.log(await response.json());

Use an E.164 phone number, including + and the country code. VIVI sends the message from the number configured on the channel. Consent, opt-out, and A2P rules still apply.

curl --request POST \
  --url "https://api.vivi.bot/channelsApi/YOUR_CHANNEL_ID/conversations/trigger" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: b8ee9526-8769-418b-b2e1-c1171b95d2d1" \
  --data '{
    "messageTemplate": "Hi {firstName}, order {orderNumber} is ready for pickup.",
    "recipients": [
      {
        "target": "+14155550123",
        "metadata": {
          "firstName": "Avery",
          "orderNumber": "VIVI-1042"
        }
      }
    ],
    "metadata": {"source": "order-management"}
  }'

import requests

channel_id = "YOUR_CHANNEL_ID"
access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    f"https://api.vivi.bot/channelsApi/{channel_id}/conversations/trigger",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "b8ee9526-8769-418b-b2e1-c1171b95d2d1",
    },
    json={
        "messageTemplate": "Hi {firstName}, order {orderNumber} is ready for pickup.",
        "recipients": [
            {
                "target": "+14155550123",
                "metadata": {
                    "firstName": "Avery",
                    "orderNumber": "VIVI-1042",
                },
            }
        ],
        "metadata": {"source": "order-management"},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const channelId = "YOUR_CHANNEL_ID";
const accessToken = "YOUR_ACCESS_TOKEN";

const response = await fetch(
  `https://api.vivi.bot/channelsApi/${channelId}/conversations/trigger`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "b8ee9526-8769-418b-b2e1-c1171b95d2d1",
    },
    body: JSON.stringify({
      messageTemplate: "Hi {firstName}, order {orderNumber} is ready for pickup.",
      recipients: [
        {
          target: "+14155550123",
          metadata: {
            firstName: "Avery",
            orderNumber: "VIVI-1042",
          },
        },
      ],
      metadata: { source: "order-management" },
    }),
  },
);

if (!response.ok) throw new Error(`Trigger failed: ${response.status}`);
console.log(await response.json());

Use the canonical lowercase UUID of a registered Teams message target. Find target IDs in the Proactive Teams messages section of the channel. A user principal name or Microsoft Entra object ID is not accepted.The VIVI app must already be part of the destination conversation. See Microsoft Teams & Copilot for target registration instructions.

curl --request POST \
  --url "https://api.vivi.bot/channelsApi/YOUR_CHANNEL_ID/conversations/trigger" \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 9cb879a8-b52a-42ca-be83-f35c7b7bfeb5" \
  --data '{
    "messageTemplate": "Hi {firstName}, support case {caseNumber} was updated.",
    "recipients": [
      {
        "target": "8f4c8f7d-8f40-4ea4-a4f0-891adb8619fd",
        "metadata": {
          "firstName": "Avery",
          "caseNumber": "CS-4815"
        }
      }
    ],
    "metadata": {"source": "support-system"}
  }'

import requests

channel_id = "YOUR_CHANNEL_ID"
access_token = "YOUR_ACCESS_TOKEN"

response = requests.post(
    f"https://api.vivi.bot/channelsApi/{channel_id}/conversations/trigger",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Idempotency-Key": "9cb879a8-b52a-42ca-be83-f35c7b7bfeb5",
    },
    json={
        "messageTemplate": "Hi {firstName}, support case {caseNumber} was updated.",
        "recipients": [
            {
                "target": "8f4c8f7d-8f40-4ea4-a4f0-891adb8619fd",
                "metadata": {
                    "firstName": "Avery",
                    "caseNumber": "CS-4815",
                },
            }
        ],
        "metadata": {"source": "support-system"},
    },
    timeout=30,
)
response.raise_for_status()
print(response.json())

const channelId = "YOUR_CHANNEL_ID";
const accessToken = "YOUR_ACCESS_TOKEN";

const response = await fetch(
  `https://api.vivi.bot/channelsApi/${channelId}/conversations/trigger`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "Content-Type": "application/json",
      "Idempotency-Key": "9cb879a8-b52a-42ca-be83-f35c7b7bfeb5",
    },
    body: JSON.stringify({
      messageTemplate: "Hi {firstName}, support case {caseNumber} was updated.",
      recipients: [
        {
          target: "8f4c8f7d-8f40-4ea4-a4f0-891adb8619fd",
          metadata: {
            firstName: "Avery",
            caseNumber: "CS-4815",
          },
        },
      ],
      metadata: { source: "support-system" },
    }),
  },
);

if (!response.ok) throw new Error(`Trigger failed: ${response.status}`);
console.log(await response.json());

Response

The endpoint returns 201 Created after processing the batch. A successful HTTP response can contain both successful and failed recipients, so inspect every item in results. Results remain in the same order as the request.

{
  "results": [
    {
      "index": 0,
      "threadId": "a2ed4f17-c880-4c56-bf1b-1547d8b129b7",
      "recipient": "+14155550123",
      "channelType": "twilio_sms",
      "status": "initiating",
      "agentResponse": null,
      "error": null
    }
  ]
}

Field	Description
`index`	The recipient’s zero-based position in the request.
`threadId`	The VIVI conversation thread ID, or `null` if a thread could not be created.
`recipient`	The original target.
`channelType`	The channel type used for the recipient.
`status`	`initiating`, `completed`, or `failed`.
`agentResponse`	Agent response text for a synchronous completion, otherwise `null`.
`error`	A code, message, and `retriable` flag when the recipient failed.

Voice and SMS dispatches normally return initiating. Microsoft Teams returns completed after provider confirmation. Recipient-specific failures return failed with an error object.

Retries, idempotency, and rate limits

Partial failures

A 201 response means that the batch was processed, not that every recipient succeeded. Retry only results where error.retriable is true, and send a new request containing only those recipients. Generate a new Idempotency-Key for the retry request.

Idempotency-Key

The optional Idempotency-Key header prevents a concurrent duplicate from dispatching twice while the first request is processing. The reservation is released after processing completes, so reusing the key later executes the request again and can create a duplicate.

Rate limit

Each workspace accepts 60 trigger requests per rolling 60-second window. A 429 response includes a Retry-After header with the number of seconds to wait.

Request errors

Status	Meaning
`400`	The channel type, target, template variables, or recipient list failed semantic validation.
`401`	The Bearer token is missing, invalid, or is not a machine-to-machine token.
`403`	The service client is inactive or does not own the channel’s account.
`404`	The channel was not found in the service client’s account.
`409`	The idempotency key is in progress or was reused concurrently with a different payload.
`422`	The JSON body is missing required fields or violates field types or size limits.
`429`	The workspace exceeded the trigger rate limit. Honor the `Retry-After` header.

Error responses include a stable code, a human-readable message, a retriable flag, and a request_id for support and log correlation.

Getting Started

Core Concepts

Accounts & Billing

Features

Resources

Trigger Conversations API

Endpoint

API reference

Before you start

Request an access token

Request body

Channel examples

Response

Retries, idempotency, and rate limits

Request errors

Endpoint

API reference

​Before you start

​Request an access token

​Request body

​Channel examples

​Response

​Retries, idempotency, and rate limits

​Request errors

Before you start

Request an access token

Request body

Channel examples

Response

Retries, idempotency, and rate limits

Request errors