Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Software Requirements for Universal Template and Universal Task

Requires Python 3.7.0 or higher. Tested with the Universal Agent bundled Python distribution.

...

  1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

  2. To import the Universal Template into your Controller, follow the instructions here.

  3. 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.

FieldInput typeDefault valueTypeDescription
ActionRequiredSend SMS MessageChoiceΑ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 CredentialsRequired-CredentialsThe 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.
SenderRequired-TextSenders identifier (phone number) in E.164 format.
Recipient ListRequired-Large TextA list of message Recipient identifiers (phone numbers) , separated by comma. E.164 format.

Max characters: 4000
MessageRequired-Large TextBody of the message.
  • Min Characters: 1
  • Max Characters: 1600
Answer TimeoutOptional30IntegerMax 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 DurationOptional60IntegerMaximum 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 TypeOptional-- None--ChoiceType of proxy connection to be used. Available options listed below.
  • -- None --
  • HTTP
  • HTTPS
  • HTTPS With Credentials
ProxyOptional-TextProxy server in the following format: http://proxyip:port or https://proxyip:port.

Required when Proxy Type is not "-- None --".
Proxy CA Bundle FileOptional-TextThe 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 CredentialsOptional-CredentialsThe 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

Image Added

Send WhatsApp Message to a list of recipients with HTTPS Proxy

Image Added

Send Voice Message with HTTPS With Credentials Proxy

Image Added

Task Output

Exit Codes

The exit codes for this Universal Extension are described below.

Exit CodeStatus Classification CodeStatus Classification DescriptionStatus Description
0SUCCESSSuccessful ExecutionSUCCESS: Task executed successfully.
1FAILFailed ExecutionFAIL: < Error Description >.
2AUTHENTICATION_ERRORBad credentialsAUTHENTICATION_ERROR: Account cannot be authenticated. < Error Details >.
3AUTHORIZATION_ERRORInsufficient PermissionsAUTHORIZATION_ERROR: Account is not authorized to perform the requested action. < Error Details >.
10CONNECTION_ERRORBad connection data or connection timed outCONNECTION_ERROR: < Error Description >.
20DATA_VALIDATION_ERRORInput fields validation errorDATA_VALIDATION_ERROR: < Error Description >.
21FAILNot all messages were queuedFAIL: 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:

AttributeTypeDescription
statsobjectObject with the statistics of the queued messages to Twilio with "Success" or "Failure".
msg_queued_countnumberNumber of messages successfully queued to Twilio.

Part of stats array.
msg_failed_countnumberNumber of messages failed to queue to Twilio

Part of stats array.


Note

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 LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
CredentialsUser documentation for creating and working with credentials.
Resolvable Credentials Permitted PropertyUser documentation for Resolvable Credentials Permitted Property.

Changelog

ue-twilio-1.0.0 (2022-11-22)

Initial Version


Panel
Table of Contents

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 NameExtension NameExtension Version
Twilioue-twilio1.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.

  1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

  2. To import the Universal Template into your Controller, follow the instructions here.

  3. 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.

FieldInput typeDefault valueTypeDescription
ActionRequiredSend SMS MessageChoiceΑ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 CredentialsRequired-CredentialsThe 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.
SenderRequired-TextSenders identifier (phone number) in E.164 format.
Recipient ListRequired-Large TextA list of message Recipient identifiers (phone numbers) , separated by comma. E.164 format.

Max characters: 4000
MessageRequired-Large TextBody of the message.
  • Min Characters: 1
  • Max Characters: 1600
Answer TimeoutOptional30IntegerMax 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 DurationOptional60IntegerMaximum 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 TypeOptional-- None--ChoiceType of proxy connection to be used. Available options listed below.
  • -- None --
  • HTTP
  • HTTPS
  • HTTPS With Credentials
ProxyOptional-TextProxy server in the following format: http://proxyip:port or https://proxyip:port.

Required when Proxy Type is not "-- None --".
Proxy CA Bundle FileOptional-TextThe 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 CredentialsOptional-CredentialsThe 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 CodeStatus Classification CodeStatus Classification DescriptionStatus Description
0SUCCESSSuccessful ExecutionSUCCESS: Task executed successfully.
1FAILFailed ExecutionFAIL: < Error Description >.
2AUTHENTICATION_ERRORBad credentialsAUTHENTICATION_ERROR: Account cannot be authenticated. < Error Details >.
3AUTHORIZATION_ERRORInsufficient PermissionsAUTHORIZATION_ERROR: Account is not authorized to perform the requested action. < Error Details >.
10CONNECTION_ERRORBad connection data or connection timed outCONNECTION_ERROR: < Error Description >.
20DATA_VALIDATION_ERRORInput fields validation errorDATA_VALIDATION_ERROR: < Error Description >.
21FAILNot all messages were queuedFAIL: 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.

...

{
    "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.

...

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents.

Document LinkDescription
Universal TemplatesUser documentation for creating, working with and understanding Universal Templates and Integrations.
Universal TasksUser documentation for creating Universal Tasks in the Universal Controller user interface.
CredentialsUser documentation for creating and working with credentials.
Resolvable Credentials Permitted PropertyUser documentation for Resolvable Credentials Permitted Property.

Changelog

ue-twilio-1.0.0 (2022-11-22)

Initial Version