Twilio
LAST UPDATED: OCT 21, 2024
Overview
Twilio SMS API adds robust messaging capabilities.
D3 SOAR is providing REST operations to function with Twilio.
Twilio is available for use in:
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. | ACbc*****9c9b |
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.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Twilio in the search box to find the integration, then click it to select it.
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.
Connection Name: The desired name for the connection.
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.
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.
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.
Description (Optional): Add your desired description for the connection.
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.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
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.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.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.
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.
Click OK to close the alert window.
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
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
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. |
JSON
|
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. | ***** |
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. | H*****X |
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. |
JSON
|
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
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
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. |