Build a message flow

Messages

Each message can do up to four things, in this order:

1. Run operations - Call connectors to fetch or transform data. Results are stored in data and available to everything that follows via template variables.
2. Create transitions - Check conditions and route to a different message if a condition is met. If a transition matches, that message starts processing from step 1, without sending anything to the user. See Message Routing.
3. Render and send a template - Send the user a message using template variables like {{ data.order.status }} or {{ params.firstName }}.
4. Await input - Wait for the user to respond, then use that response in the next message. See Assigning Inputs.

Not every message needs all four. A greeting might only render a template. A data-fetching message might run operations and then render and send a dynamic message.

📘

Messages are referred to as States in the API. See the States API reference for more details.

Flows

A flow is a chain of messages linked together. A simple flow might be three messages: greet the user, show them something, confirm an action. Each message does its job—fetches data, sends content, presents choices—and the user's interaction determines which message comes next.

As you add more messages and connect them, the flow grows into a full conversation. A welcome message leads to a menu, the menu leads to an order confirmation, and a failed order loops back to the menu. Each message is self-contained, but together they form the experience.

For details on all the ways messages can route to each other, see Message Routing.

Example flows

Linear flow with button navigation

A simple flow with three Messages. Each message sends content with a button, and the user taps to move forward.

welcome

• Template: "Hi! Ready to order?" with a [View Menu] button
• User taps "View Menu" → agent sends show-menu

show-menu

• Operations:
  • Fetch menu from restaurant API → data.menu
• Template: Menu carousel with [Order] buttons
• User taps "Order" → agent sends confirm-order

confirm-order

• Operations:
  • Create order via API → data.order
• Template: "Your order is confirmed! {{ data.order.id }}"

Each step is driven by the user tapping a button.

Branching flow with conditional transitions

The happy path renders normally. Transitions handle the exceptions before the template is sent.

show-menu

• Operations:
  • Fetch menu → data.menu
• Template: Menu with [Order] buttons
• User taps "Order" → agent sends confirm-order

confirm-order

• Operations:
  • Check inventory → data.availability
  • Create order → data.order
• Transitions:
  • If out of stock → routes to item-unavailable
  • Else → Template: "Your order is confirmed! {{ data.order.id }}"

item-unavailable

• Template: "Sorry, that item is out of stock." with a [Back to Menu] button
• User taps "Back to Menu" → agent sends show-menu

If the item is in stock, the user sees the confirmation. If not, the transition fires before the template is sent, and the user sees the unavailable message instead.

Chained operations with multiple data sources

A single message can run multiple operations in sequence. Each result is available to the next operation and to the template.

show-order-summary

• Operations:
  • Fetch order from API → data.order
  • Format delivery date with Date connector → data.formattedDate
  • Get weather for delivery zip with API → data.weather
• Template: "Order #1234 arrives April 2. Weather: Sunny."

This combines an API Connector (order lookup, weather) with a Native Connector (date formatting) in one message.

Example: Restaurant ordering

This flow combines buttons, transitions, and chained operations:

welcome

• Operations:
  • Fetch customer profile from CRM → data.customer
• Template: "Welcome back, {{ data.customer.name }}! Ready to order?" with a [View Menu] button
• User taps "View Menu" → agent sends show-menu

show-menu

• Operations:
  • Fetch today's menu → data.menu
• Template: Rich card carousel with [Order] buttons
• User taps "Order" → agent sends confirm-order

confirm-order

• Operations:
  • Check inventory → data.availability
  • Create order → data.order
• Transitions:
  • If out of stock → routes to item-unavailable
  • Else → Template: "Your {{ data.order.item.name }} is on the way! Order #{{ data.order.id }}"

item-unavailable

• Template: "Sorry, that item is currently unavailable." with a [Back to Menu] button
• User taps "Back to Menu" → agent sends show-menu

This flow uses:

• Buttons to move from welcome → show-menu → confirm-order
• Transitions in confirm-order to route to item-unavailable when out of stock
• Operations at each step to fetch and transform data
• Template variables to render dynamic data
• A loop. item-unavailable sends show-menu via a button

What you can build

With just messages, connectors, and transitions, you can build sophisticated conversational experiences:

• Personalized interactions - Fetch customer data from your CRM and tailor every message to the individual.
• Transactional flows - Order status, appointment booking, and payment confirmations are connected to your live systems.
• Dynamic content - Pull product catalogs, inventory, pricing, or weather data and render it as rich cards and carousels.
• Intelligent routing - Branch conversations based on API responses, user input, or any data in the flow.
• Multi-step workflows - Chain together as many messages as you need. Each one builds on the data from the ones before it.

Every piece is composable. A connector you build for one flow works in any other. A message that checks inventory can be reused across different ordering flows.

Next steps

Connect to your data Set up API Connectors to call your APIs and use Native Connectors to transform the results.

Make your messages dynamic Use Template Variables and Liquid Filters to personalize every message with live data.

Build conversation logic Add Message Routing to route users through different paths based on conditions.

Trigger messages from your backend Use the Send Template Messages API to start conversations programmatically.