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

You can change the Twilio account SID, From number or Messaging Service SID until the campaign's first dispatch is queued. After that, the sender fields are locked so later attempts use the campaign's configured sender identity. You can still change unrelated source settings or rotate the auth token. Check the sender and its Twilio registration before launching.

Step 2: Configure Twilio webhooks and callback

Save the source as a draft first so its Twilio setup panel has the final source-specific URLs.

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.

Check inbound routing before launch or restart

Before launching or resuming the source, MX8 Labs checks that replies reach the exact inbound webhook URL using HTTP POST. A phone number's TwiML Application or Messaging Service can override the webhook shown on the number itself, so check the effective inbound configuration too.

If validation blocks launch or restart, follow the reported routing error, correct the URL and method in Twilio, save the configuration, and try again. This check protects the reply path; still complete a safe phone test to verify the respondent experience.

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, attempted sender identity, and failure details. Twilio error 30034 identifies an unregistered sender; check the failure reason for US A2P 10DLC or Messaging Service registration guidance. See Field reports for the export workflow.