Twilio
Add robust messaging capabilities to your care flow.
Add robust messaging capabilities to your care flow.
Category: Communication. Adds 5 actions to a care flow.
What to configure
Set these once, on the extension in Awell Studio. An action fails at run time if a required setting is missing.
| Setting | Required | Notes |
|---|---|---|
| Account SID | Yes | Find your Account SID at twilio.com/console. Stored as a secret. |
| Add opt-out language | No | On by default, set to "Off" if you don't want to add opt-out language to your text messages. |
| Auth token | Yes | Find your Auth Token at twilio.com/console. Stored as a secret. |
| Client ID | No | Find your Client ID at twilio.com/console. Stored as a secret. |
| "From" number | No | A Twilio phone number that you own in E.164 format which will be used to send text messages. If you are using a Messaging Service you can leave this field empty. |
| Language | No | The language you are sending text messages in. Possible options: fr, en (default), nl. |
| Messaging Service SID | No | The SID of the Messaging Service you want to associate with the Message. If you are not using a Messaging Service but a "from" number, then you can leave this field empty. |
| Opt-out language | No | The sentence that is appended at the end of your text messages that informs recipients of how they can opt out. If not specified, standard opt-out language is appended to your messages. |
| Region | No | Possible options: IE1, AU1, US1 - Default is IE1. |
Actions
Twilio adds these 5 actions to a care flow. Add one to a step, then fill in its inputs.
Start a new execution of a pre-existing flow
Send a text message from a given telephone number to a recipient of your choice.
This action can be previewed in Studio before you publish.
| Input | Type | Required | Description |
|---|---|---|---|
| "From" number | string | No | The phone number that will send the text messages, it must be a Twilio phone number that you own. When left blank, the "From" number from the extension settings will be used. |
| "To" phone number | string | Yes | The phone number you would like to send the text message to. |
| Flow ID | string | Yes | Flow ID (FWXXXXX...) |
| Parameters | json | Yes | Context to be passed into the flow (as an flat object) |
Returns:
| Data point | Type |
|---|---|
executionId | string |
Get messages
Get a list of text messages matching the given criteria. You can also filter the Messages by providing one of the allowed filters.
This action can be previewed in Studio before you publish.
| Input | Type | Required | Description |
|---|---|---|---|
| "From" number | string | No | Search for text messages sent from a specific phone number |
| "To" number | string | No | Search for text messages sent to a specific phone number |
| Page Size | numeric | No | The number of results per page. Minimum is 1 and maximum is 1000. |
| Sent date after than | date | No | Search for messages sent after a given date |
| Sent date before than | date | No | Search for messages sent before a given date |
| Sent date | date | No | Search for messages sent on a given date |
Returns:
| Data point | Type |
|---|---|
allMessages | strings_array |
latestMessage | string |
numberOfMessages | number |
Get a list of text messages matching the given criteria. Only the last 50 messages are returned.
Send SMS (with from number)
Send a text message from a given telephone number to a recipient of your choice.
This action can be previewed in Studio before you publish.
| Input | Type | Required | Description |
|---|---|---|---|
| "From" number | string | No | The phone number that will send the text messages, it must be a Twilio phone number that you own. When left blank, the "From" number from the extension settings will be used. |
| "To" phone number | string | Yes | The phone number you would like to send the text message to. |
| Message | text | Yes | The message you would like to send. |
Returns:
| Data point | Type |
|---|---|
messageSid | string |
Send an SMS with Twilio to a recipient of your liking.
Send SMS during business hours
Send a text message during business hours from a given telephone number to a recipient of your choice.
This action can be previewed in Studio before you publish.
| Input | Type | Required | Description |
|---|---|---|---|
| Messaging Service SID | string | No | The SID of the Messaging Service you want to associate with the Message. If left blank, the SID specified in the settings will be used. |
| "To" phone number | string | Yes | The phone number you would like to send the text message to. |
| Message | text | Yes | The message you would like to send. |
| Timezone | text | No | Specify the IANA time zone to determine if the current time (in UTC) falls within business hours in your timezone. The default time zone used for this check is UTC. |
Returns:
| Data point | Type |
|---|---|
messageSid | string |
scheduled | boolean |
sendAt | date |
Send SMS (with Messaging Service)
Send a text message from a Messaging Service to a recipient of your choice.
This action can be previewed in Studio before you publish.
| Input | Type | Required | Description |
|---|---|---|---|
| Messaging Service SID | string | No | The SID of the Messaging Service you want to associate with the Message. If left blank, the SID specified in the settings will be used. |
| "To" phone number | string | Yes | The phone number you would like to send the text message to. |
| Message | text | Yes | The message you would like to send. |
Returns:
| Data point | Type |
|---|---|
messageSid | string |
Setup and notes
Twilio is a customer engagement platform used by hundreds of thousands of businesses and more than ten million developers worldwide to build unique, personalized experiences for their customers.
They are known for democratizing channels like voice, text, chat, video, and email through APIs, making it easy for every organization to build meaningful interactions with customers on the channels they prefer.
Extension settings
In order to set up this extension, you will need:
- A Twilio API key or auth token which can be found in the Twilio console.
- Your account SID which can be found in the Twilio console.
- A phone number to send the message from. This must be a Twilio phone number that you own.
User consent
The extension has some built-in mechanisms to enforce compliance with Twilio's messaging policy.
Opt-out
By default, every text message will be appended with standard opt-out language ("Reply STOP to unsubscribe."). You can specify custom opt-out language within the settings of the extension but make sure the opt-out keywords used are supported. STOP, UNSTOP, UNSUBSCRIBE or CANCEL are the default opt-out keywords supported but Twilio also supports defining custom stop keywords.
If you don't want to append opt-out language to your text messages, set the "Add opt-out language" setting to "Off".
For more information, please visit the Twilio docs.
Sending text messages to recipients that opted out
If you attempt to send a text message to a recipient who has opted out, the message will fail to be delivered and the action will be marked as failed. This is the default behavior of Twilio's API, which prevents sending texts to anyone who has chosen to opt out.
Send SMS during working hours
This action allows for the scheduling of SMS messages to be sent within the "daily operational hours" of 9 AM to 5 PM. It ensures that text messages are dispatched at appropriate times during the day, avoiding early morning or late-night disturbances to recipients.
Here's how it works:
- If the action is activate during business hours (9 AM to 5 PM), the SMS is sent immediately.
- If activated before 9 AM, the SMS is scheduled to be sent at 9 AM on the same day.
- If activated after 5 PM, the SMS is scheduled to be sent at 9 AM the following day.
This setup ensures that all messages reach your respondents during reasonable daytime hours, enhancing the likelihood of a timely and considerate communication. It's important to mention that messages will still be dispatched over the weekend, but they will adhere to the "business hours" schedule of 9 AM to 5 PM.
Note that scheduling messages with Twilio is only possible if you send text messages using a MessagingServiceSid.
Changelog
v2 2024-02-22
- Add capability to search for messages using all the allowed filters provided by Twilio API. Check here: https://www.twilio.com/docs/messaging/api/message-resource#read-multiple-message-resources
v2 2023-06-23
Full description: https://github.com/awell-health/awell-extensions/issues/157
- "Send SMS" action
- Change label from "Send SMS" to "Send SMS (with from number)"
- Throw error when "From" number in both settings and in fields is not provided
- Add new action "Send SMS (with Messaging Service)"
v2
Compared to v1 (pre-beta release), the extension only has one custom action "Send SMS" instead of two. The Custom Action allows for:
- Sending a text message to a recipient (phone number) stored in a data point, including patient profile data points.
- Sending a text message to a fixed recipient (phone number).
Where this page comes from
The settings, actions, inputs, outputs and webhooks above are generated from the
extension's own code, at @awell-health/awell-extensions v2.1.159. They match what the
platform actually does rather than a description of it.
Field-level detail also appears in Awell Studio when you configure the action. Something wrong or missing? Email support@awellhealth.com.