***
title: Launch Chat Agents
slug: launch-chat-agents
description: Learn how to launch chat agents with Synthflow via API, chat widget, WhatsApp, or SMS.
---------------------
For a complete page index, fetch https://docs.synthflow.ai/llms.txt. For full documentation content, fetch https://docs.synthflow.ai/llms-full.txt.
Synthflow offers multiple ways to launch a chat agent: API integration, an embeddable chat widget, WhatsApp, and SMS.
Choose the channel based on where the conversation should happen:
* **API** for custom applications and backend-controlled chat sessions.
* **Widget** for a fast website or app embed managed by Synthflow.
* **WhatsApp** for Twilio-backed messaging on supported US-region workspaces.
* **SMS** for text conversations through your own Twilio number.
**Region availability:** WhatsApp and SMS channels are currently available for **US-region workspaces only**. EU support is not yet available because Twilio does not currently offer EU data residency for the WhatsApp and SMS Conversations APIs, which is required to meet GDPR data processing and storage requirements. EU support will be added once a compliant provider option is available. API and widget-based chat agents are available in all regions.
## 1. API Integration
After deploying your chat agent, you can start a new chat conversation programmatically using the API:
```bash
curl -X POST 'https://api.synthflow.ai/v2/chat/{chat_id}' \
--header 'Content-Type: application/json' \
--data '{
"model_id": "{model_id}",
"metadata": {}
}'
```
* Replace `{chat_id}` with a unique UUID for the conversation.
* Replace `{model_id}` with the ID of your chat agent.
You can use this endpoint to send and receive messages, manage sessions, and integrate chat into any custom application.
## 2. Embeddable Chat Widget
Synthflow provides an out-of-the-box chat widget you can embed on your website or in your app:
1. Create a chat agent in the Synthflow dashboard.
2. Go to the chat agent's **Settings** and **Deployment** tab.
3. Copy the provided embed code.
4. Paste the embed code into your website or application where you want the chat widget to appear.
The widget is fully managed by Synthflow, making it easy to add conversational AI to your site with minimal setup.
***
## 3. WhatsApp
Chat agents can send and receive messages over WhatsApp. This requires a connected Twilio account with a WhatsApp-enabled sender.
**Connect your Twilio account**
Navigate to **Integrations > Twilio** in the Synthflow dashboard and provide your Twilio SID and Auth credentials. See the [Twilio integration guide](/integrate-twilio) for full setup instructions.
**Enable a WhatsApp sender in Twilio**
You need a WhatsApp-enabled sender in your Twilio account. If you don't have one, follow [Twilio's WhatsApp documentation](https://www.twilio.com/docs/whatsapp) to register a sender.
**Configure the sender webhooks**
In the Twilio console, navigate to your WhatsApp sender and set the following webhook URLs:
| Field | URL |
| ----------------------------------------- | --------------------------------------------------- |
| **Callback URL** (inbound messages) | `https://chat.synthflow.ai/webhooks/twilio/inbound` |
| **Status Callback URL** (delivery status) | `https://chat.synthflow.ai/webhooks/twilio/status` |
If your sender is associated with a Twilio Messaging Service, the Messaging Service webhook URLs take priority and override the sender-level URLs. Either remove the sender from the Messaging Service, or set the same webhook URLs on the Messaging Service instead.
**Deploy your chat agent**
Assign the WhatsApp-enabled number to your chat agent from the **Deployment** tab. Incoming WhatsApp messages will route to the agent and responses are sent back over the same channel.
***
## 4. SMS
Chat agents can also communicate over SMS. Like WhatsApp, this requires your own Twilio account.
**Connect your Twilio account**
If you haven't already, connect Twilio in **Integrations > Twilio**. See the [Twilio integration guide](/integrate-twilio).
**Assign an SMS-capable number**
Use a Twilio phone number that supports SMS. You can [buy a number](/buy-a-phone-number) through Synthflow or [import your own](/custom-phonenumbers).
**Configure the phone number webhooks**
In the Twilio console, navigate to your phone number's configuration and set the following:
| Field | URL |
| ------------------------------------ | --------------------------------------------------- |
| **A message comes in** (webhook URL) | `https://chat.synthflow.ai/webhooks/twilio/inbound` |
| **Status callback URL** | `https://chat.synthflow.ai/webhooks/twilio/status` |
If the phone number is part of a Twilio Messaging Service, the Messaging Service webhook URLs take priority over the phone number's own URLs. Either remove the number from the Messaging Service, or set the same webhook URLs on the Messaging Service instead.
**Deploy your chat agent**
Attach the SMS-capable number to your chat agent from the **Deployment** tab. The agent will handle inbound SMS messages and reply over SMS.
Both WhatsApp and SMS channels require you to [connect your own Twilio account](/integrate-twilio) and use your own Twilio credentials. Synthflow supports the integration, but Twilio messaging usage is billed through your Twilio account.
Twilio charges for WhatsApp and SMS usage at their own rates. These costs are billed directly by Twilio and are separate from Synthflow's standard platform fee, which still applies.
***
## Conversation Lifecycle
Messaging channels share the same basic lifecycle controls: reminder timing, idle timeout, and outbound conversation setup. These settings matter most when you expect asynchronous user replies instead of real-time chat.
WhatsApp and SMS conversations support automatic idle reminders and timeouts. These settings are configured on the agent and apply per-conversation.
| Setting | Description |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Idle timeout** (`allowed_idle_time_seconds`) | Seconds of user inactivity before the conversation is automatically ended. |
| **Reminder delay** (`reminder_after_idle_seconds`) | Seconds of user inactivity before a reminder message is sent. Must be less than the idle timeout. |
| **Reminder message** (`reminder_message`) | The text sent to the user when the reminder fires. |
| **Enable reminders** (`send_user_idle_reminder`) | Set to `true` to enable idle reminders. |
When a user stops responding, the lifecycle works as follows:
1. After `reminder_after_idle_seconds` of inactivity, the agent sends the configured `reminder_message` over the same channel.
2. If the user still does not respond within `allowed_idle_time_seconds` (measured from the last user message), the conversation is automatically ended with an `end_reason` of `inactivity_timeout`.
3. If the user replies at any point, the idle timer resets.
Minimum values are 60 seconds for both the reminder delay and the idle timeout. Values below 60 seconds are overridden to defaults (1 hour for reminders, 24 hours for timeout).
***
## Starting an Outbound Conversation
You can initiate outbound WhatsApp and SMS conversations via the API. The endpoint creates a new conversation and sends the first message to the recipient.
```bash
curl -X POST https://api.synthflow.ai/v2/chat/outbound \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"agent_id": "your-agent-id",
"channel": "whatsapp",
"to_number": "+15559876543",
"from_number": "+15551234567",
"initial_message": "Hi! How can I help you today?"
}'
```
### Request Fields
| Field | Type | Required | Description |
| ------------------ | ------ | -------- | ---------------------------------------------------------------------------- |
| `agent_id` | string | Yes | The ID of your chat agent. |
| `channel` | string | Yes | `sms` or `whatsapp`. |
| `to_number` | string | Yes | Recipient phone number in E.164 format (e.g. `+15559876543`). |
| `from_number` | string | Yes | Your Twilio sender number in E.164 format. |
| `initial_message` | string | No | A freeform text message to send as the opening message. |
| `template` | object | No | A Twilio Content Template to use as the opening message (see below). |
| `custom_variables` | object | No | Key-value pairs for prompt variable substitution in the agent configuration. |
### Response
```json
{
"status": "ok",
"response": {
"conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
}
```
### WhatsApp 24-Hour Session Window
WhatsApp enforces a **24-hour conversation window**. If the recipient has messaged your sender within the last 24 hours, you can send a freeform `initial_message`. If the recipient has **not** messaged in the last 24 hours, you must use an approved Twilio Content Template — WhatsApp will reject freeform messages outside the session window.
Use `initial_message` for freeform messages within the window:
```json
{
"agent_id": "your-agent-id",
"channel": "whatsapp",
"to_number": "+15559876543",
"from_number": "+15551234567",
"initial_message": "Hi! Following up on your earlier question."
}
```
Use `template` for messages outside the 24-hour window (also works within it):
```json
{
"agent_id": "your-agent-id",
"channel": "whatsapp",
"to_number": "+15559876543",
"from_number": "+15551234567",
"template": {
"content_sid": "HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"variables": {
"1": "Thursday at 9am"
}
}
}
```
### Template Object
| Field | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------- |
| `content_sid` | string | Yes | The SID of an approved [Twilio Content Template](https://www.twilio.com/docs/content). Starts with `HX`. |
| `variables` | object | No | Key-value pairs for template parameter substitution (e.g. `{"1": "value"}`). |
Twilio Content Templates must be submitted for approval before use. Templates in `pending` or `rejected` status will cause the outbound message to fail. You can manage templates in the [Twilio Content Editor](https://www.twilio.com/console/content).
SMS does not have a session window restriction — you can use `initial_message` for SMS outbound at any time.
***
## Post-Conversation Webhook
When a chat conversation ends, Synthflow can send a webhook to a URL you configure on your agent. The payload includes the full transcript, individual turns, and routing metadata.
### Payload Fields
| Field | Type | Description |
| -------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `event_type` | string | The event that triggered the webhook (e.g. `conversation_completed`). |
| `chat_id` | string | Unique identifier for the conversation. |
| `agent_id` | string | The ID of the chat agent that handled the conversation. |
| `workspace_id` | string | Your Synthflow workspace ID. |
| `entry_mode` | string | How the conversation was initiated — `omnichannel` for WhatsApp/SMS, `api` for API or widget chats. |
| `channel` | string | The messaging channel used (`sms`, `whatsapp`, or `api`). |
| `chat_status` | string | Final status of the conversation (e.g. `ended`). |
| `end_reason` | string | Why the conversation ended (e.g. `completed`, `inactivity_timeout`). |
| `started_at` | string | ISO 8601 timestamp when the conversation started. |
| `ended_at` | string | ISO 8601 timestamp when the conversation ended. |
| `transcript` | string | Plain-text transcript. Each line is prefixed with `User:` for user messages or the agent ID for agent messages. |
| `turns` | array | Ordered list of individual message turns (see below). |
| `metadata` | object | Custom metadata attached to the conversation, if any. |
| `route` | object | Routing metadata for omnichannel conversations (see below). |
### Turn Object
Each entry in the `turns` array represents a single message:
| Field | Type | Description |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
| `message_id` | string | Unique identifier for the message. |
| `turn_number` | integer | Position in the conversation (1-indexed). |
| `agent_id` | string | The agent ID for agent messages, or `"user"` for user messages. |
| `message` | string | The message content. |
| `direction` | string | `inbound` (user → agent) or `outbound` (agent → user). |
| `current_state` | string | The flow designer state active when this message was sent. Present on all turns except the first inbound message. |
| `provider_message_sid` | string | Twilio message SID. Present on outbound omnichannel turns only. |
| `timestamp` | string | ISO 8601 timestamp. |
### Route Object
Present on WhatsApp and SMS conversations. Contains the provider and addressing details:
| Field | Type | Description |
| ---------------------- | ------ | --------------------------------------------------------- |
| `provider` | string | The messaging provider (e.g. `twilio`). |
| `channel` | string | `sms` or `whatsapp`. |
| `provider_account_sid` | string | Your Twilio Account SID. |
| `agent_address` | string | The phone number used by the agent (e.g. `+15551234567`). |
| `user_address` | string | The end-user's phone number. |
### Example Payload
```json
{
"event_type": "conversation_completed",
"chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
"workspace_id": "your-workspace-id",
"entry_mode": "omnichannel",
"channel": "sms",
"chat_status": "ended",
"end_reason": "completed",
"started_at": "2026-01-15T10:30:00.000000Z",
"ended_at": "2026-01-15T10:32:45.000000Z",
"transcript": "User: Hi, I'd like to book an appointment\nf0e1d2c3-b4a5-6789-0abc-def123456789: Sure! I can help with that. What day works best for you?\nUser: Thursday morning\nf0e1d2c3-b4a5-6789-0abc-def123456789: Great, I have 9am or 11am available on Thursday. Which do you prefer?\nUser: 9am please\nf0e1d2c3-b4a5-6789-0abc-def123456789: Done! You're booked for Thursday at 9am. See you then!",
"turns": [
{
"message_id": "11111111-1111-1111-1111-111111111111",
"turn_number": 1,
"agent_id": "user",
"message": "Hi, I'd like to book an appointment",
"direction": "inbound",
"timestamp": "2026-01-15T10:30:02.000000Z"
},
{
"message_id": "22222222-2222-2222-2222-222222222222",
"turn_number": 2,
"agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
"message": "Sure! I can help with that. What day works best for you?",
"direction": "outbound",
"current_state": "main_state",
"provider_message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"timestamp": "2026-01-15T10:30:03.000000Z"
},
{
"message_id": "33333333-3333-3333-3333-333333333333",
"turn_number": 3,
"agent_id": "user",
"message": "Thursday morning",
"direction": "inbound",
"current_state": "main_state",
"timestamp": "2026-01-15T10:31:15.000000Z"
},
{
"message_id": "44444444-4444-4444-4444-444444444444",
"turn_number": 4,
"agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
"message": "Great, I have 9am or 11am available on Thursday. Which do you prefer?",
"direction": "outbound",
"current_state": "main_state",
"provider_message_sid": "SMyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
"timestamp": "2026-01-15T10:31:16.000000Z"
},
{
"message_id": "55555555-5555-5555-5555-555555555555",
"turn_number": 5,
"agent_id": "user",
"message": "9am please",
"direction": "inbound",
"current_state": "main_state",
"timestamp": "2026-01-15T10:32:30.000000Z"
},
{
"message_id": "66666666-6666-6666-6666-666666666666",
"turn_number": 6,
"agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
"message": "Done! You're booked for Thursday at 9am. See you then!",
"direction": "outbound",
"current_state": "booking_state",
"provider_message_sid": "SMzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
"timestamp": "2026-01-15T10:32:45.000000Z"
}
],
"route": {
"provider": "twilio",
"channel": "sms",
"provider_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agent_address": "+15551234567",
"user_address": "+15559876543"
}
}
```
## Frequently asked questions
Every 5 messages sent by Synthflow counts as 1 billable minute, charged at your plan's per-minute rate. This is a platform-level fee. If you use SMS or WhatsApp through Twilio, standard Twilio messaging fees apply on top.
Yes! You can use either a single prompt or a flow designer configuration for your chat agent.
Chat will be shortly integrated into the analytics platform.