Text messages with Twilio

On the Team plan and above, survey invitations and reminders can go by text; how to send them is in Send survey links by text message. Twilio is set up once for the whole deployment by whoever runs wrkflow. Until it is, texts show as Not configured.

Set up

1. 1In Twilio, buy a number or register a sender for the countries you will text, and complete the registration those countries require, such as A2P 10DLC in the US.
2. 2Create a Messaging Service, add the sender to its pool and keep Advanced Opt-Out on: it answers STOP, START and HELP and blocks opted-out numbers.
3. 3In the service’s integration settings, send incoming messages to https://<your-domain>/api/sms/inbound by HTTP POST. wrkflow checks Twilio’s signature against exactly that URL, so it must match NEXT_PUBLIC_SITE_URL.
4. 4Set TWILIO_ACCOUNT_SID, TWILIO_MESSAGING_SERVICE_SID and TWILIO_AUTH_TOKEN, and redeploy. To send with an API key instead, also set TWILIO_API_KEY_SID and TWILIO_API_KEY_SECRET: the auth token is still needed to verify replies and delivery reports.
5. 5Text yourself from a survey, reply STOP, and check that your number appears under Contacts, Not emailed, as Replied STOP. Reply START to undo.

What leaves wrkflow

• The phone number and the text, with the person’s personal link.
• The delivery report address carries the send and participant ids only.
• Once Twilio is set up it is listed as a subprocessor on the security page.

If something goes wrong

• Texts show as Not configured: the Twilio settings above aren’t all set.
• STOP replies and delivery reports can’t be verified: set TWILIO_AUTH_TOKEN.
• Couldn’t text, Can’t get texts: the number isn’t a mobile number or doesn’t exist. Fix the contact’s number.
• Replied STOP: the person opted out and can reply START. Texts come from a number shared by every organization, so a STOP applies to all of them.

See Integrations for the statuses and how to ask support.