Twilio

Overview

Twilio SMS API adds robust messaging capabilities.

D3 SOAR is providing REST operations to function with Twilio.

Twilio is available for use in:

D3 SOAR	V12.7.83.0+
Category	Email Messaging
Deployment Options	Option II, Option IV

Known Limitations

Tokens are valid for a default period of 10 minutes once generated. You can customize the validity period of your service's tokens to any value between 2 minutes and 24 hours by contacting Twilio's support team.

You may request the status of a verification no more than:

60 requests in one minute
180 requests in one hour
250 requests in one day

Please refer to Rate Limits and Timeouts for detailed information.

Connection

To connect to Twilio from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL (domain level)	The Twilio domain level Server URL.	https://api.twilio.com
Account SID	The Account SID to authenticate the connection.	ACbcc1b43fdcf90f827d9ed9c170059c9b
Auth Token	The Auth Token to authenticate the connection.	******
API Version	The version of the API to use for the connection.	2010-04-01

Permission Requirements

Trail mode can be applied when using all the current commands. Usage of trial mode will appear in the billing section of your Twilio account.

Configuring Twilio to Work with D3 SOAR

Log into the Twilio portal. You will be able to see the Account SID and Auth Token under Account Info.

Configuring D3 SOAR to Work with Twilio

Log in to D3 SOAR.
Find the Twilio integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Twilio in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Twilio.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add your desired description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the domain level Server URL. The default value is https://api.twilio.com.
  2. Copy the Account SID from the Twilio platform. Refer to Configuring Twilio to Work with D3 SOAR.
  3. Input the Auth Token. Refer to Configuring Twilio to Work with D3 SOAR.
  4. Input the API Version. The default value is 2010-04-01.
10. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tick box. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
11. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green check mark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Twilio includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Twilio API, please refer to the Twilio API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Twilio to Work with D3 SOAR for details.

Note for Time-related parameters

The input format of time-related parameters may vary based on your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

Navigate to Configuration Application Settings. Select Date/Time Format.
Choose your desired date and time format.

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

List SMS Messages

Lists SMS Messages associated with the provided account.

Input

Input Parameter	Required/Optional	Description	Example
Sender	Optional	The sender phone number to filter messages.	+120*****
Receiver	Optional	The recipient phone number to filter messages.	+120*****
Include Conversation Messages	Optional	The option to include all conversation messages between the sender number and the receiver number. This parameter is only applicable when both the Sender and Receiver parameters are defined.	False
Date Sent After	Optional	The sent date after which to filter messages.	2023-11-27 00:00
Date Sent Before	Optional	The sent date before which to filter messages.	2023-11-26 00:00
Limit	Optional	The maximum number of messages to return. The default value is 50. If the Include Conversation Message parameter is set to True, the limit will apply to both sender and recipient messages individually.	10

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "first_page_uri": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages.json?To=+18148015454&from_=+xxxxxxxxxx&DateSent%3E=&account_sid=xxxxxxxxxxxxxxxxxxxxxxxx&PageSize=100&Page=0",
        "end": 1,
        "previous_page_uri": null,
        "messages": [
            {
                "body": "Hello",
                "num_segments": "1",
                "direction": "inbound",
                "from": "+xxxxxxxxxx",
                "date_updated": "Thu, 06 Jul 2023 23:43:31 +0000",
                "price": null,
                "error_message": null,
                "uri": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SM3e1d73b246158c83a8bd46cc051159db.json",
                "account_sid": "xxxxxxxxxxxxxxxxxxxxxxxx",
                "num_media": "0",
                "to": "+18*****",
                "date_created": "Thu, 06 Jul 2023 23:43:31 +0000",
                "status": "received",
                "sid": "*****",
                "date_sent": "Thu, 06 Jul 2023 23:43:31 +0000",
                "messaging_service_sid": null,
                "error_code": null,
                "price_unit": "USD",
                "api_version": "2010-04-01",
                "subresource_uris": {
                    "media": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SM3e1d73b246158c83a8bd46cc051159db/Media.json",
                    "feedback": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SM3e1d73b246158c83a8bd46cc051159db/Feedback.json"
                }
            },
            {
                "body": "Hi",
                "num_segments": "1",
                "direction": "inbound",
                "from": "+xxxxxxxxxx",
                "date_updated": "Thu, 06 Jul 2023 23:24:54 +0000",
                "price": null,
                "error_message": null,
                "uri": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SMb7da8a82debf6512686fdc2db1fe4e16.json",
                "account_sid": "xxxxxxxxxxxxxxxxxxxxxxxx",
                "num_media": "0",
                "to": "+18*****",
                "date_created": "Thu, 06 Jul 2023 23:24:54 +0000",
                "status": "received",
                "sid": "*****",
                "date_sent": "Thu, 06 Jul 2023 23:24:54 +0000",
                "messaging_service_sid": null,
                "error_code": null,
                "price_unit": "USD",
                "api_version": "2010-04-01",
                "subresource_uris": {
                    "media": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SMb7da8a82debf6512686fdc2db1fe4e16/Media.json",
                    "feedback": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages/SMb7da8a82debf6512686fdc2db1fe4e16/Feedback.json"
                }
            }
        ],
        "uri": "/2010-04-01/Accounts/xxxxxxxxxxxxxxxxxxxxxxxx/Messages.json?To=+18148015454&from_=+xxxxxxxxxx&DateSent%3E=&account_sid=xxxxxxxxxxxxxxxxxxxxxxxx&PageSize=100&Page=0",
        "page_size": 100,
        "start": 0,
        "next_page_uri": null,
        "page": 0
    }
]

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

FIRST SENT	LAST SENT	COUNT
2023-07-06 19:06:27	2023-07-07 19:06:27	50

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List SMS Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Twilio portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: invalid username.

Error Sample Data

List SMS Messages failed.

Status Code: 400.

Message: invalid username.

Send SMS Messages

Sends SMS Messages to the provided phone numbers.

Input

Input Parameter	Required/Optional	Description	Example
Sender	Required	A valid Twilio phone number in E.164 format, an alphanumeric sender ID, or a Channel Endpoint address suitable for your message type. Twilio-purchased phone numbers or short codes are also acceptable. Note: Using private cell phone numbers for spoofing is prohibited.	+15*****
Receiver	Required	The recipient's phone number in E.164 format for SMS/MMS or the Channel user address for other third-party channels.	[ "+16*****" ]
Message	Required	The text content of the message you want to send. Messages can be up to 1,600 characters in length.	Hello from my Twilio line!

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "sid": "*****",
        "date_created": "Mon, 29 Jun 2020 17:47:57 +0000",
        "date_updated": "Mon, 29 Jun 2020 17:47:57 +0000",
        "date_sent": null,
        "account_sid": "*****",
        "to": "+16*****",
        "from": "+15*****",
        "messaging_service_sid": null,
        "body": "Sent from your Twilio trial account - Hello from my Twilio line!",
        "status": "queued",
        "num_segments": "1",
        "num_media": "0",
        "direction": "outbound-api",
        "api_version": "2010-04-01",
        "price": null,
        "price_unit": "USD",
        "error_code": null,
        "error_message": null,
        "uri": "/2010-04-01/Accounts/*****/Messages/*****.json",
        "subresource_uris": {
            "media": "/2010-04-01/Accounts/*****/Messages/*****/Media.json"
        }
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

JSON

[
    {
        "sid": "*****",
        "date_created": "Mon, 29 Jun 2020 17:47:57 +0000",
        "date_updated": "Mon, 29 Jun 2020 17:47:57 +0000",
        "date_sent": null,
        "account_sid": "*****",
        "to": "+16*****",
        "from": "+15*****",
        "messaging_service_sid": null,
        "body": "Sent from your Twilio trial account - Hello from my Twilio line!",
        "status": "queued",
        "num_segments": "1",
        "num_media": "0",
        "direction": "outbound-api",
        "api_version": "2010-04-01",
        "price": null,
        "price_unit": "USD",
        "error_code": null,
        "error_message": null,
        "uri": "/2010-04-01/Accounts/*****/Messages/*****.json",
        "subresource_uris": {
            "media": "/2010-04-01/Accounts/*****/Messages/*****/Media.json"
        }
    }
]

Return Data

Indicates one of the possible command execution states: Successful, Partially Successful, or Failed.

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

SENDER	RECEIVER	DATE CREATED
+1*****	+18*****    2023-07-06 19:06:27

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Send SMS Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Twilio portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: invalid username.

Error Sample Data

Send SMS Messages failed.

Status Code: 400.

Message: invalid username.

Send SMS For Response

Sends SMS Messages to the provided phone numbers for response actions.

Reader Note

When the Message parameter is set to include the placeholder <<UserActionRequiredURL>>, the resulting text message will appear as a hyperlink. An example is shown in screenshot below:
Ensure you register your preferred phone number with Twilio as a new Caller ID to receive SMS messages. Without adding your phone number, the command will execute successfully, but the receiving number will not receive any messages.
If the Sender parameter is not defined, a number will be automatically assigned from the input Messaging Service's sender pool. To access and manage this sender pool, navigate to Messaging > Services > Messaging Services in Twilio. Note that if any sender is inputted, it must also be selected from this designated sender pool.

Input

Input Parameter	Required/Optional	Description	Example
Sender (From)	Optional	A valid Twilio phone number in E.164 format, an alphanumeric sender ID, or a Channel Endpoint address suitable for your message type. Twilio-purchased phone numbers or short codes are also acceptable. Note: Using private cell phone numbers for spoofing is prohibited.	+15*****
Receiver (To)	Required	The recipient's phone number in E.164 format for SMS/MMS or the Channel user address for other third-party channels.	[ "+16*****" ]
Message	Optional	The text content of the message you want to send for the response action. Messages can be up to 1,600 characters in length. Ensure either the Message or Content SID parameters are defined. If the message requires a response action from the recipient, include the placeholder <<UserActionRequiredURL>> within the message text. The URL will appear as a hyperlink in the text message.	Please check request approval page: <<UserActionRequiredURL>>
Send as MMS	Optional	The option to deliver the message as an MMS message, when set to True.	True
Managing Service SID	Required	The SID of the messaging service to associate with the message. When you include this SID and leave out the Sender parameter, Twilio will automatically select the most suitable sender from the available pool within the Messaging Service. Optionally, you can also specify a sender to use a particular sender from this pool. If you wish to utilize a content template, ensure to define this parameter. For more information on using content templates with messaging services, refer to Send Templates Created with the Content Template Builder from Twilio's documentation.	MG177*****a8
Content SID	Optional	The SID of the content template that will be utilized for the message. If this parameter is not defined, a content template will not be applied. You can locate the SID in the Twilio Console under the Content Template Builder section. Note: It is required to define either the Message or Content SID parameters. For more information, refer to Create templates with the Content Template Builder in Console from Twilio's documentation.	HXXXXXXXXXXX
Content Variables	Optional	The JSON object containing key-value pairs, where the keys represent template variables and the values are their corresponding substitutions. The Content SID parameter must also be defined when using this parameter. If values are not defined in the content_variables parameter, the template's default placeholder values are used.	{ "1": "coupon_code", "2": "docs", "3": "images/library-logo-resource2x.width-1000.png" }
Callback Webhook URL	Optional	The webhook URL for callbacks, to which Twilio will send updates each time there is a change in status.	http://postb.in/1234abc

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "body": "Sent from your Twilio trial account - Hello World! Welcome to visit d3security.com",
            "num_segments": "1",
            "direction": "outbound-api",
            "from": "+120*****",
            "date_updated": "Fri, 13 Oct 2023 17:26:12 +0000",
            "price": null,
            "error_message": null,
            "uri": "/2010-04-01/Accounts/*****/Messages/*****.json",
            "account_sid": "*****",
            "num_media": "0",
            "to": "+16*****",
            "date_created": "Fri, 13 Oct 2023 17:26:12 +0000",
            "status": "queued",
            "sid": "*****",
            "date_sent": null,
            "messaging_service_sid": null,
            "error_code": null,
            "price_unit": "USD",
            "api_version": "2010-04-01",
            "subresource_uris": {
                "media": "/2010-04-01/Accounts/*****/Messages/*****/Media.json"
            }
        }
    ]
}

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results

{'body': 'Sent from your Twilio trial account - Hello World! Welcome to visit *****.com', 'num_segments': '1', 'direction': 'outbound-api', 'from': '+12*****', 'date_updated': 'Fri, 13 Oct 2023 17:26:12 +0000', 'price': None, 'error_message': None, 'uri': '/2010-04-01/Accounts/*****/Messages/*****.json', 'account_sid': '*****', 'num_media': '0', 'to': '+16*****', 'date_created': 'Fri, 13 Oct 2023 17:26:12 +0000', 'status': 'queued', 'sid': '*****', 'date_sent': None, 'messaging_service_sid': None, 'error_code': None, 'price_unit': 'USD', 'api_version': '2010-04-01', 'subresource_uris': {'media': '/2010-04-01/Accounts/*****/Messages/*****/Media.json'}}

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Send SMS For Response failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Twilio portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The 'From' number xxx is not a valid phone number, shortcode, or alphanumeric sender ID.

Error Sample Data

Send SMS For Response failed.

Status Code: 400.

Message: The 'From' number xxx is not a valid phone number, shortcode, or alphanumeric sender ID.

Test Connection

Allows you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help you locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Twilio portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: invalid username.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: invalid username.