Twilio
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Overview
Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and performing other communication functions using its web service APIs.
This Universal Extension allows sending SMS/WhatsApp/Voice message to a list of recipients.
Version Information
Template Name | Extension Name | Extension Version |
---|---|---|
Twilio | ue-twilio | 1.0.0 |
Refer to Changelog for version history information.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Software Requirements for Universal Template and Universal Task
Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
Software Requirements for Universal Agent
Both Windows and Linux agents are supported:
- Universal Agent for Windows x64 Version 7.1.0.0 and later with python options installed.
- Universal Agent for Linux Version 7.1.0.0 and later with python options installed.
Software Requirements for Universal Controller
Universal Controller Version 7.1.0.0 and later.
Network and Connectivity Requirements
- Universal Agent where the extension is deployed should be able to reach the Twilio API.
- A Twilio Account should be created and the respective obtained Account SID and Auth Token can be found in Twilio console page.
Key Features
This Universal Extension provides the following key features:
- Actions
- Send SMS/WhatsApp/Voice message to a list of recipients.
- Input/Output
- Statistical Information as Extension Output
- Enhanced Logging when task is run in Debug mode providing trace of the API calls.
- Other
- Capability to use HTTP or HTTPS proxy instead of direct communication to Twilio.
Known Issues
Task instance "Status Description" in case of cancellation of a task instance when task is run on Universal Agents of versions 7.1 or 7.2 is incorrect. Issue is resolved on Universal Agent with version 7.3 and onwards.
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
Before creating a new task you need to have a Twilio Account with the respective SID and Auth Token.
For a new Universal Task, create a new task, and enter the required input fields.
Input Fields
The input fields for this Universal Extension are described below.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | Send SMS Message | Choice | Αction performed upon the task execution. Available actions are listed below.
|
Twilio Credentials | Required | - | Credentials | The Credentials definition should be as follows.
|
Sender | Required | - | Text | Senders identifier (phone number) in E.164 format. |
Recipient List | Required | - | Large Text | A list of message Recipient identifiers (phone numbers) , separated by comma. E.164 format. Max characters: 4000 |
Message | Required | - | Large Text | Body of the message.
|
Answer Timeout | Optional | 30 | Integer | Max wait time until a call is answered in seconds.
On average 3-5 seconds are consumed until the phone starts ringing. So estimate respectively. Required when Action = "Send Voice Message". |
Call Max Duration | Optional | 60 | Integer | Maximum talk time per call in seconds.
Required when Action = "Send Voice Message". |
Proxy Type | Optional | -- None-- | Choice | Type of proxy connection to be used. Available options listed below.
|
Proxy | Optional | - | Text | Proxy server in the following format: http://proxyip:port or https://proxyip:port . Required when Proxy Type is not "-- None --". |
Proxy CA Bundle File | Optional | - | Text | The path to a custom certificate bundle to use when establishing SSL/TLS connections with proxy. The Bundle needs to include certificates for both proxy and Twilio sites. Used when Proxy Type is configured for "HTTPS" or "HTTPS With Credentials". |
Proxy Credentials | Optional | - | Credentials | The Credentials definition should be as follows.
|
Task Examples
Send SMS Message to one recipient
Send WhatsApp Message to a list of recipients with HTTPS Proxy
Send Voice Message with HTTPS With Credentials Proxy
Task Output
Exit Codes
The exit codes for this Universal Extension are described below.
Exit Code | Status Classification Code | Status Classification Description | Status Description |
---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Task executed successfully. |
1 | FAIL | Failed Execution | FAIL: < Error Description >. |
2 | AUTHENTICATION_ERROR | Bad credentials | AUTHENTICATION_ERROR: Account cannot be authenticated. < Error Details >. |
3 | AUTHORIZATION_ERROR | Insufficient Permissions | AUTHORIZATION_ERROR: Account is not authorized to perform the requested action. < Error Details >. |
10 | CONNECTION_ERROR | Bad connection data or connection timed out | CONNECTION_ERROR: < Error Description >. |
20 | DATA_VALIDATION_ERROR | Input fields validation error | DATA_VALIDATION_ERROR: < Error Description >. |
21 | FAIL | Not all messages were queued | FAIL: Some messages were not possible to be queued. Check STDERR for more information. |
Extension Output
In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.
Attribute changed
is populated as follows:
- true if at least 1 message was queued successfully to Twilio.
- false otherwise.
result
section includes the following attributes:
Attribute | Type | Description |
---|---|---|
stats | object | Object with the statistics of the queued messages to Twilio with "Success" or "Failure". |
msg_queued_count | number | Number of messages successfully queued to Twilio. Part of stats array. |
msg_failed_count | number | Number of messages failed to queue to Twilio Part of stats array. |
Extension Output on "Cancel" command execution, is supported for Universal Agent 7.3 and above.
Extension Output example for a successful execution of Send SMS Message to one recipient.
{
"exit_code": 0,
"status_description": "SUCCESS: Task executed successfully.",
"changed": true,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "sms_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999"
],
"message_body_text": "Hello World",
"call_max_duration": null,
"answer_timeout": null,
"proxy": null,
"proxy_type": null,
"proxy_ca_bundle_file": null,
"proxy_credentials_user": null,
"proxy_credentials_password": null
}
},
"result": {
"stats": {
"msg_queued_count": 1,
"msg_failed_count": 0,
}
}
}
Extension Output example for a failed execution of Send WhatsApp Message to a list of recipients with HTTPS Proxy, with 1 out of 3 messages queued to Twilio.
{
"exit_code": 21,
"status_description": "FAIL: Some messages were not possible to be queued. Check STDERR for more information.",
"changed": true,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "whatsapp_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999",
"+3069888888",
"+3069777777"
],
"message_body_text": "Hello World",
"call_max_duration": null,
"answer_timeout": null,
"proxy": "https://proxy_example.com:8080",
"proxy_type": "HTTPS",
"proxy_ca_bundle_file": "/path_to_bundle/proxy_and_end_point_certificates",
"proxy_credentials_user": null,
"proxy_credentials_password": null
}
},
"result": {
"stats": {
"msg_queued_count": 1,
"msg_failed_count": 2,
}
}
}
Extension Output example for a failed execution of Send Voice Message with HTTPS With Credentials Proxy.
{
"exit_code": 1,
"status_description": "FAIL: <Error Description>.",
"changed": false,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "voice_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999",
],
"message_body_text": "Hello World",
"call_max_duration": 60,
"answer_timeout": 30,
"proxy": "https://proxy_example.com:8080",
"proxy_type": "HTTPS",
"proxy_ca_bundle_file": "/path_to_bundle/proxy_and_end_point_certificates",
"proxy_credentials_user": "****",
"proxy_credentials_password": "****",
}
},
"result": {
"stats": {
"msg_queued_count": 0,
"msg_failed_count": 1,
}
}
}
STDOUT and STDERR
STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.
Extension Cancellation & Rerun
A task instance can be cancelled in any of the following statuses: Queued, Action Required, Started, Running.
Information will be printed on the STDERR regarding the cancelled task such queued, failed, not sent messages. Cancelling almost immediately cancels the queuing to Twilio.When you re-run a task instance, the Controller uses the same task instance. That is, the new task instance that has the same sys_id and input that will resend the same messages to the defined recipients.
Integration Modifications
Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.
- Python code modifications should not be done.
- Template Modifications
- General Section
- "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
- Universal Template Details Section
- "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
- Success and Failure Exit codes should not be changed.
- Success and Failure Output processing should not be changed.
- Fields Restriction Section
The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.- Success/Failure exit codes need to be respected.
- In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.
- General Section
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents.
Document Link | Description |
---|---|
Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
Credentials | User documentation for creating and working with credentials. |
Resolvable Credentials Permitted Property | User documentation for Resolvable Credentials Permitted Property. |
Changelog
ue-twilio-1.0.0 (2022-11-22)
Initial Version
Disclaimer
Your use of this download is governed by Stonebranch’s Terms of Use, which are available at https://www.stonebranch.com/integration-hub/Terms-and-Privacy/Terms-of-Use/
Overview
Twilio provides programmable communication tools for making and receiving phone calls, sending and receiving text messages, and performing other communication functions using its web service APIs.
This Universal Extension allows sending SMS/WhatsApp/Voice message to a list of recipients.
Version Information
Template Name | Extension Name | Extension Version |
---|---|---|
Twilio | ue-twilio | 1.0.0 |
Refer to Changelog for version history information.
Software Requirements
This integration requires a Universal Agent and a Python runtime to execute the Universal Task.
Software Requirements for Universal Template and Universal Task
Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.
Software Requirements for Universal Agent
Both Windows and Linux agents are supported:
- Universal Agent for Windows x64 Version 7.1.0.0 and later with python options installed.
- Universal Agent for Linux Version 7.1.0.0 and later with python options installed.
Software Requirements for Universal Controller
Universal Controller Version 7.1.0.0 and later.
Network and Connectivity Requirements
- Universal Agent where the extension is deployed should be able to reach the Twilio API.
- A Twilio Account should be created and the respective obtained Account SID and Auth Token can be found in Twilio console page.
Key Features
This Universal Extension provides the following key features:
- Actions
- Send SMS/WhatsApp/Voice message to a list of recipients.
- Input/Output
- Statistical Information as Extension Output
- Enhanced Logging when task is run in Debug mode providing trace of the API calls.
- Other
- Capability to use HTTP or HTTPS proxy instead of direct communication to Twilio.
Known Issues
Task instance "Status Description" in case of cancellation of a task instance when task is run on Universal Agents of versions 7.1 or 7.2 is incorrect. Issue is resolved on Universal Agent with version 7.3 and onwards.
Import Universal Template
To use the Universal Template, you first must perform the following steps.
This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow the instructions here.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.
Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.
Configure Universal Task
Before creating a new task you need to have a Twilio Account with the respective SID and Auth Token.
For a new Universal Task, create a new task, and enter the required input fields.
Input Fields
The input fields for this Universal Extension are described below.
Field | Input type | Default value | Type | Description |
---|---|---|---|---|
Action | Required | Send SMS Message | Choice | Αction performed upon the task execution. Available actions are listed below.
|
Twilio Credentials | Required | - | Credentials | The Credentials definition should be as follows.
|
Sender | Required | - | Text | Senders identifier (phone number) in E.164 format. |
Recipient List | Required | - | Large Text | A list of message Recipient identifiers (phone numbers) , separated by comma. E.164 format. Max characters: 4000 |
Message | Required | - | Large Text | Body of the message.
|
Answer Timeout | Optional | 30 | Integer | Max wait time until a call is answered in seconds.
On average 3-5 seconds are consumed until the phone starts ringing. So estimate respectively. Required when Action = "Send Voice Message". |
Call Max Duration | Optional | 60 | Integer | Maximum talk time per call in seconds.
Required when Action = "Send Voice Message". |
Proxy Type | Optional | -- None-- | Choice | Type of proxy connection to be used. Available options listed below.
|
Proxy | Optional | - | Text | Proxy server in the following format: http://proxyip:port or https://proxyip:port . Required when Proxy Type is not "-- None --". |
Proxy CA Bundle File | Optional | - | Text | The path to a custom certificate bundle to use when establishing SSL/TLS connections with proxy. The Bundle needs to include certificates for both proxy and Twilio sites. Used when Proxy Type is configured for "HTTPS" or "HTTPS With Credentials". |
Proxy Credentials | Optional | - | Credentials | The Credentials definition should be as follows.
|
Task Examples
Send SMS Message to one recipient
Send WhatsApp Message to a list of recipients with HTTPS Proxy
Send Voice Message with HTTPS With Credentials Proxy
Task Output
Exit Codes
The exit codes for this Universal Extension are described below.
Exit Code | Status Classification Code | Status Classification Description | Status Description |
---|---|---|---|
0 | SUCCESS | Successful Execution | SUCCESS: Task executed successfully. |
1 | FAIL | Failed Execution | FAIL: < Error Description >. |
2 | AUTHENTICATION_ERROR | Bad credentials | AUTHENTICATION_ERROR: Account cannot be authenticated. < Error Details >. |
3 | AUTHORIZATION_ERROR | Insufficient Permissions | AUTHORIZATION_ERROR: Account is not authorized to perform the requested action. < Error Details >. |
10 | CONNECTION_ERROR | Bad connection data or connection timed out | CONNECTION_ERROR: < Error Description >. |
20 | DATA_VALIDATION_ERROR | Input fields validation error | DATA_VALIDATION_ERROR: < Error Description >. |
21 | FAIL | Not all messages were queued | FAIL: Some messages were not possible to be queued. Check STDERR for more information. |
Extension Output
In the context of a workflow, subsequent tasks can rely on the information provided by this integration as Extension Output.
Attribute changed
is populated as follows:
- true if at least 1 message was queued successfully to Twilio.
- false otherwise.
result
section includes the following attributes:
Attribute | Type | Description |
---|---|---|
stats | object | Object with the statistics of the queued messages to Twilio with "Success" or "Failure". |
msg_queued_count | number | Number of messages successfully queued to Twilio. Part of stats array. |
msg_failed_count | number | Number of messages failed to queue to Twilio Part of stats array. |
Extension Output on "Cancel" command execution, is supported for Universal Agent 7.3 and above.
Extension Output example for a successful execution of Send SMS Message to one recipient.
{
"exit_code": 0,
"status_description": "SUCCESS: Task executed successfully.",
"changed": true,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "sms_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999"
],
"message_body_text": "Hello World",
"call_max_duration": null,
"answer_timeout": null,
"proxy": null,
"proxy_type": null,
"proxy_ca_bundle_file": null,
"proxy_credentials_user": null,
"proxy_credentials_password": null
}
},
"result": {
"stats": {
"msg_queued_count": 1,
"msg_failed_count": 0,
}
}
}
Extension Output example for a failed execution of Send WhatsApp Message to a list of recipients with HTTPS Proxy, with 1 out of 3 messages queued to Twilio.
{
"exit_code": 21,
"status_description": "FAIL: Some messages were not possible to be queued. Check STDERR for more information.",
"changed": true,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "whatsapp_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999",
"+3069888888",
"+3069777777"
],
"message_body_text": "Hello World",
"call_max_duration": null,
"answer_timeout": null,
"proxy": "https://proxy_example.com:8080",
"proxy_type": "HTTPS",
"proxy_ca_bundle_file": "/path_to_bundle/proxy_and_end_point_certificates",
"proxy_credentials_user": null,
"proxy_credentials_password": null
}
},
"result": {
"stats": {
"msg_queued_count": 1,
"msg_failed_count": 2,
}
}
}
Extension Output example for a failed execution of Send Voice Message with HTTPS With Credentials Proxy.
{
"exit_code": 1,
"status_description": "FAIL: <Error Description>.",
"changed": false,
"invocation": {
"extension": "ue-twilio",
"version": "1.0.0",
"fields": {
"action": "voice_message",
"twilio_credentials_user": "****",
"twilio_credentials_password": "****",
"sender": "+1568888888",
"recipient_list": [
"+3069999999",
],
"message_body_text": "Hello World",
"call_max_duration": 60,
"answer_timeout": 30,
"proxy": "https://proxy_example.com:8080",
"proxy_type": "HTTPS",
"proxy_ca_bundle_file": "/path_to_bundle/proxy_and_end_point_certificates",
"proxy_credentials_user": "****",
"proxy_credentials_password": "****",
}
},
"result": {
"stats": {
"msg_queued_count": 0,
"msg_failed_count": 1,
}
}
}
STDOUT and STDERR
STDOUT and STDERR provide additional information to User. The populated content can be changed in future versions of this extension without notice. Backward compatibility is not guaranteed.
Extension Cancellation & Rerun
A task instance can be cancelled in any of the following statuses: Queued, Action Required, Started, Running.
Information will be printed on the STDERR regarding the cancelled task such queued, failed, not sent messages. Cancelling almost immediately cancels the queuing to Twilio.When you re-run a task instance, the Controller uses the same task instance. That is, the new task instance that has the same sys_id and input that will resend the same messages to the defined recipients.
Integration Modifications
Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.
- Python code modifications should not be done.
- Template Modifications
- General Section
- "Name", "Extension", "Variable Prefix", "Icon" should not be changed.
- Universal Template Details Section
- "Template Type", "Agent Type", "Send Extension Variables", "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
- Success and Failure Exit codes should not be changed.
- Success and Failure Output processing should not be changed.
- Fields Restriction Section
The setup of the template does not impose any restrictions, However with respect to "Exit Code Processing Fields" section.- Success/Failure exit codes need to be respected.
- In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining success or failure of a task.
- General Section
Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.
Document References
This document references the following documents.
Document Link | Description |
---|---|
Universal Templates | User documentation for creating, working with and understanding Universal Templates and Integrations. |
Universal Tasks | User documentation for creating Universal Tasks in the Universal Controller user interface. |
Credentials | User documentation for creating and working with credentials. |
Resolvable Credentials Permitted Property | User documentation for Resolvable Credentials Permitted Property. |
Changelog
ue-twilio-1.0.0 (2022-11-22)
Initial Version