Capture Bulk Messaging traffic into conversations

(new)

Beta

Twilio Bulk Messaging API is currently available as a public beta product and the information contained in this document is subject to change. This means that some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by a SLA.

When you use the Bulk Messaging API to send outbound messages, Conversation Orchestrator can automatically create conversations for those messages and their replies. You do this by setting capture rules on a conversation configuration that match your Bulk Messaging phone number.

Limitations

Conversation Orchestrator captures only text messages from Bulk Messaging. It doesn't capture messages that contain media or rich content.

Prerequisites

Create a conversation configuration for Bulk Messaging

Create a conversation configuration with capture rules that match your Bulk Messaging phone number. When you send messages through the Bulk Messaging API, Conversation Orchestrator captures them into conversations. Replies are added to the same conversation, so you can manage the entire interaction in one place.

The following example configuration:

Includes capture rules (captureRules) that match any message sent from or to your Bulk Messaging phone number.
Groups conversations by profile (conversationGroupingType: GROUP_BY_PROFILE), so the same customer across different devices or channels maps to one conversation.
Sets an inactivity timeout of 30 minutes and a closed timeout of 24 hours for SMS. Learn more about conversation lifecycle.

Twilio ConsoleAPI

In the Twilio Console, go to Products & services > Conversation Orchestrator > Conversation configurations.
Click Create a Conversation configuration.
On the Name Configuration step, enter a name and description, select Conversation grouping as Group by profile, and then click Next.
On the Messaging and chat traffic step, from the SMS/MMS phone numbers list, select your Twilio phone number that you use for Bulk Messaging. Then click Next.
On the Voice traffic step, click Skip this Step.
On the Configure lifecycle step, select Include inactive state, set Inactive timeout to 30 minutes and Closed timeout to 24 hours, and then click Next.
On the Enable Conversation Memory step, create a new memory store or select an existing memory store to use for this conversation configuration. Then click Next.
Deselect the Turn on observations and summaries checkbox, then click Next.
On the Summary step, review your settings and click Create Conversation configuration.

Retrieve conversations created from Bulk Messaging

Make a GET request to the Conversations resource. Use channelId to filter by resource identifier, such as a message ID.

Retrieve conversations created from Bulk Messaging

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function listConversationByAccount() {
14  const conversations = await client.conversations.v2.conversations.list({
15    channelId: "YOUR_MESSAGE_ID",
16    limit: 20,
17  });
18
19  conversations.forEach((c) => console.log(c.id));
20}
21
22listConversationByAccount();

You can also inspect participants or inspect communications in a conversation to see the messages captured from Bulk Messaging.

Limitations

Conversation Orchestrator captures only text messages from Bulk Messaging. It doesn't capture messages that contain media or rich content.

Next steps

Core concepts: Learn about configurations, capture rules, and conversation grouping types.
Ingestion modes: Learn about passive capture rules, active API creation, and how to combine them.
Conversation lifecycle: Understand conversation states and configure timeout behavior.
Bulk Messaging API: Send high-volume messages to up to 10,000 recipients in a single request.