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. Send SMS Message Send WhatsApp Message Send Voice Message To use WhatApp set up is required
Twilio Credentials	Required	-	Credentials	The Credentials definition should be as follows. Account SID as "Runtime User". Auth Token as "Runtime Password". Twilio Credentials can be found on Twilio console page.
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. Min Characters: 1 Max Characters: 1600
Answer Timeout	Optional	30	Integer	Max wait time until a call is answered in seconds. Min Value: 1 Max Value: 600 Timeout helps avoid voicemail, by hanging up automatically after the defined time has passed. 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. Min Value: 1 Max Value: 14400 This option allows to limit charges per call. Cases such, the line is left open, or a voicemail keeps recording for long time. Required when Action = "Send Voice Message".
Proxy Type	Optional	-- None--	Choice	Type of proxy connection to be used. Available options listed below. -- None -- HTTP HTTPS HTTPS With Credentials
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. Proxy Username as "Runtime User". Proxy Password as "Runtime Password". Required when Proxy Type is configured for "HTTPS With Credentials".

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.
  1. Success/Failure exit codes need to be respected.
  2. 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.

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