Setting up an interactive Twilio text respondent source

Interactive text surveys run surveys over text message in a back-and-forth between the respondent and the platform:

Use Twilio Text to upload phone contacts and send survey questions over SMS.

Before you start

• Advanced respondent sources must be enabled in your account.
• You need a Twilio Account SID, Auth Token, and either:
• a Twilio phone number, or
• a Twilio Messaging Service SID.

Your contact numbers must be in E.164 format (example: +15551234567). See E.164 phone number format for the formatting rules and common country prefixes.

Step 1: Create a new Twilio Text source

Go to Sources and create a source with type Twilio Text.

Fill these Twilio-specific fields together with the selected base fields:

Field (UX label)	What to enter	Required
Twilio account SID	Your Twilio Account SID used to send SMS	Yes
Twilio from number	SMS-enabled Twilio number in E.164	Exactly one of this or Messaging Service SID
Twilio messaging service SID	Twilio Messaging Service SID	Exactly one of this or From number
Twilio auth token	Twilio Auth Token	Required on create, optional on update
Stop confirmation message	Auto-reply sent after STOP/unsubscribe	Optional
Messages per second	Outbound SMS rate limit for this source	Yes (min 1)
Completion url	Redirect base URL after survey completion	Optional
Identity column	Contact file identity column name (default: Identifier)	Optional

Step 2: Configure Twilio webhooks and callback

The Twilio setup panel exposes two URLs. Configure both on the same sender you selected in Step 1:

If the number is attached to a Messaging Service, that service controls its inbound-message handling. On the number’s Configuration Details page, open Messaging and select Edit configuration details to confirm the associated service.

To configure the inbound webhook:

1. In the Twilio dialog, select Webhook, TwiML Bin, Function, Studio Flow, Proxy Service as the configuration method, then choose Use Webhooks as the primary method.
2. Copy the Inbound webhook URL from the MX8 Labs Twilio setup panel and paste it into What is your webhook URL?
3. Set Select a method to handle responses to HTTP POST, then save the configuration. This lets respondent replies reach the platform.

Finally, copy the SMS status callback URL from the Twilio setup panel and set it as the sender's delivery-status callback, also using POST. For a Twilio phone number, set it in the number's Messaging settings; for a Messaging Service, set it in the service's Integration settings. This lets MX8 Labs record whether each message was delivered or failed. Send a safe test before going live.

Step 3: Upload contacts

1. Use Upload file.
2. Supported file types: .csv, .csv.gz, .xlsx. For .xlsx, the platform reads the workbook's active sheet. You do not need to format the data as an Excel table.
3. Include the configured Identity column (default Identifier) and populate it with phone numbers in E.164 format (e.g. +15551234567). Numbers that are not in E.164 will be rejected. See E.164 phone number format for the formatting rules and common country prefixes.
4. The values in the identity column must be unique within the file. If any number appears more than once, the upload will be rejected. De-duplicate before uploading.

You can also include additional columns of first-party data alongside the identity column. Any column header that matches a question code, or that exactly matches the name of a stored variable in your survey, will be auto-matched. The value is pre-filled into the survey at runtime and is available in reporting. Matching to stored variables is exact and case-sensitive, so spell the column header identically to the stored variable.

Step 4: Send a safe test

1. Open a survey test link and choose this Twilio Text source if prompted.
2. Select Phone and enter your test number in E.164 format.
3. Confirm the test number is not already in this source's uploaded contacts.
4. Start the phone test. The platform sends the first survey question to your number and continues the test by SMS.

See Testing and Reviewing Your Survey for the complete market, source, mode, and test-data flow.

Step 5: Go live

1. Use the Status action Go Live.
2. Use Pause, Restart, or Complete as needed during fielding.

Monitor delivery and respondent outcomes

On the Summary tab, use the source's progress bar to track uploaded destinations through Planned, Scheduled, Starting, Delivered, or Failed. Delivered confirms the SMS delivery milestone, not that the recipient completed the survey.

Use the field report separately to review New, In Progress, Terminated, Poor Quality, and Complete respondent outcomes. If your account has export permission, select Dispatch CSV there to investigate destination-level provider statuses, timestamps, identifiers, and failure details. See Field reports for the column definitions.