Launch Chat Agents

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:

$ 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.

Synthflow provides an out-of-the-box chat widget you can embed on your website or in your app:

Create a chat agent in the Synthflow dashboard.
Go to the chat agent’s Settings and Deployment tab.
Copy the provided embed code.
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 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 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.

Assign an SMS-capable number

Use a Twilio phone number that supports SMS. You can buy a number through Synthflow or import your own.

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 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:

After reminder_after_idle_seconds of inactivity, the agent sends the configured reminder_message over the same channel.
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.
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.

$ 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

1 {
2   "status": "ok",
3   "response": {
4     "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
5   }
6 }

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:

1 {
2   "agent_id": "your-agent-id",
3   "channel": "whatsapp",
4   "to_number": "+15559876543",
5   "from_number": "+15551234567",
6   "initial_message": "Hi! Following up on your earlier question."
7 }

Use template for messages outside the 24-hour window (also works within it):

1 {
2   "agent_id": "your-agent-id",
3   "channel": "whatsapp",
4   "to_number": "+15559876543",
5   "from_number": "+15551234567",
6   "template": {
7     "content_sid": "HXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
8     "variables": {
9       "1": "Thursday at 9am"
10     }
11   }
12 }

Template Object

Field	Type	Required	Description
`content_sid`	string	Yes	The SID of an approved Twilio Content Template. 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.

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

1 {
2   "event_type": "conversation_completed",
3   "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
4   "agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
5   "workspace_id": "your-workspace-id",
6   "entry_mode": "omnichannel",
7   "channel": "sms",
8   "chat_status": "ended",
9   "end_reason": "completed",
10   "started_at": "2026-01-15T10:30:00.000000Z",
11   "ended_at": "2026-01-15T10:32:45.000000Z",
12   "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!",
13   "turns": [
14     {
15       "message_id": "11111111-1111-1111-1111-111111111111",
16       "turn_number": 1,
17       "agent_id": "user",
18       "message": "Hi, I'd like to book an appointment",
19       "direction": "inbound",
20       "timestamp": "2026-01-15T10:30:02.000000Z"
21     },
22     {
23       "message_id": "22222222-2222-2222-2222-222222222222",
24       "turn_number": 2,
25       "agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
26       "message": "Sure! I can help with that. What day works best for you?",
27       "direction": "outbound",
28       "current_state": "main_state",
29       "provider_message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
30       "timestamp": "2026-01-15T10:30:03.000000Z"
31     },
32     {
33       "message_id": "33333333-3333-3333-3333-333333333333",
34       "turn_number": 3,
35       "agent_id": "user",
36       "message": "Thursday morning",
37       "direction": "inbound",
38       "current_state": "main_state",
39       "timestamp": "2026-01-15T10:31:15.000000Z"
40     },
41     {
42       "message_id": "44444444-4444-4444-4444-444444444444",
43       "turn_number": 4,
44       "agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
45       "message": "Great, I have 9am or 11am available on Thursday. Which do you prefer?",
46       "direction": "outbound",
47       "current_state": "main_state",
48       "provider_message_sid": "SMyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
49       "timestamp": "2026-01-15T10:31:16.000000Z"
50     },
51     {
52       "message_id": "55555555-5555-5555-5555-555555555555",
53       "turn_number": 5,
54       "agent_id": "user",
55       "message": "9am please",
56       "direction": "inbound",
57       "current_state": "main_state",
58       "timestamp": "2026-01-15T10:32:30.000000Z"
59     },
60     {
61       "message_id": "66666666-6666-6666-6666-666666666666",
62       "turn_number": 6,
63       "agent_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
64       "message": "Done! You're booked for Thursday at 9am. See you then!",
65       "direction": "outbound",
66       "current_state": "booking_state",
67       "provider_message_sid": "SMzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",
68       "timestamp": "2026-01-15T10:32:45.000000Z"
69     }
70   ],
71   "route": {
72     "provider": "twilio",
73     "channel": "sms",
74     "provider_account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
75     "agent_address": "+15551234567",
76     "user_address": "+15559876543"
77   }
78 }

Frequently asked questions

What is pricing for chat?

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.

Does chat work for both prompt and flow designer agents?

Yes! You can use either a single prompt or a flow designer configuration for your chat agent.

How do I monitor chat agent performance?

Chat will be shortly integrated into the analytics platform.