Twilio

Purpose

The Twilio integration enables you to send an SMS message to one phone number at a time from AirMDR.Use this integration to:

Notify an on-call responder about a security incident.
Send a time-sensitive investigation update.
Ask a user to review suspicious activity.

Each AirMDR connection uses one Twilio account and one Messaging Service. Create separate connections when using different accounts or services.

Supported Versions

Component	Compatibility
Twilio platform	Twilio cloud-hosted Programmable Messaging.
Messages API	REST API version `2010-04-01`.
Sending configuration	A Twilio Messaging Service identified by its `MG` SID.
Authentication	Standard API Key SID and Secret, or Account SID and Auth Token.
AirMDR operation	Outbound SMS to one recipient per skill execution.

The Messages API creates messages under the specified Twilio account. The Messaging Service determines which configured sender to use.

Authentication

AirMDR authenticates to Twilio using HTTP Basic authentication. Configure either of the following credential pairs:

Authentication Method	Username	Password
Standard API key — recommended for this integration	API Key SID beginning with `SK`.	API Key Secret generated when the key is created.
Account credentials — alternative	Account SID beginning with `AC`.	Auth Token for that account.

The Username and Password fields contain API credentials, rather than the email address and password used to sign in to the Twilio Console. Twilio supports API Key SID and Secret authentication for REST API requests.A dedicated API key allows you to revoke AirMDR’s credential independently. However, a Standard key has broad API access within its account; it is not restricted to the selected Messaging Service.

Role-based access considerations

Use a Twilio account role that permits access to API credentials, phone numbers, and messaging configuration. Twilio’s general Developer role provides access to development resources and credentials; Administrator and Owner roles provide broader account access. Apply your organization’s access policy when assigning roles.The Console role controls what the person configuring the integration can manage. Runtime API requests use the permissions of the credentials saved in AirMDR.

Pre-requisites

An active Twilio account with messaging enabled and sufficient available balance or trial allowance.

Twilio Console access to manage API credentials and Messaging Services.

A Messaging Service containing at least one sender suitable for the destination country.

Running the messaging skill sends a real SMS message and may incur Twilio charges. A message that has been sent cannot be recalled.

Setup Steps

Obtain the Account SID

Sign in to the Twilio Console.
Select the account or subaccount that will send messages.
Open its home page or account dashboard.
Locate Account Info.
Copy the Account SID, which begins with AC.

Twilio displays the Account SID and Auth Token on the Console home page.

Use the account that owns the Messaging Service. When using a subaccount, obtain the credentials and Messaging Service from that same subaccount.

Obtain the Username and Password

Choose one of the authentication method.
Option A: Create a Standard API Key
(or)
Option B: Use the Account SID and Auth Token

Option A: Create a Standard API Key

In the Twilio Console, open Settings → Account settings → API keys & auth tokens.
Select the appropriate Region.
Click Create API key.
Enter an API key name, such as AirMDR-SMS-Production.
Select Standard as the key type.
Click Next.
Copy the generated API Key SID and Secret.
Store the Secret securely before leaving the page.
Select Got it!, then click Finish.

For the legacy Console,

Open Admin → Account management → Keys & credentials → API keys & tokens.
Click Create API key.
Enter a Friendly name.
Select the Region and Standard key type.
Click Create.
**Copy the credentials, and acknowledge the confirmation **Save the credentials in an approved Password Manager or Vault.The Secret is displayed only when the key is created. If it is lost, create a replacement key.
Click Done.

Enter the following values in AirMDR:

AirMDR Field	Twilio Value
Username	API Key SID beginning with `SK`.
Password	API Key Secret.

Twilio API credentials are region-specific. Confirm that the key’s Region matches the Twilio endpoint used by your AirMDR deployment.

Option B: Use the Account SID and Auth Token

Open the selected account’s Twilio Console home page.
Locate Account Info.
Copy the Account SID.
Reveal and copy the Auth Token using the available display control.

Enter the following values in AirMDR:

AirMDR Field	Twilio Value
Username	Account SID beginning with `AC`.
Password	Auth Token for that account.

You can also manage account credentials through the API Keys & Tokens page.

Before rotating an account Auth Token, identify other applications that use it to avoid interrupting their access

Obtain the Messaging Service SID

Choose one of the method.
Option A: Use an Existing Messaging Service
(or)
Option B: Create a Messaging Service

Option A: Use an Existing Messaging Service

In the current Twilio Console, open Communications → Messaging → Services. In the legacy Console, open Messaging → Services.
Select the service AirMDR should use. Twilio
Open Properties.
Copy the Messaging Service SID, which begins with MG.
Open Sender Pool and verify that the service contains a suitable sender. Twilio

Option B: Create a Messaging Service

If an appropriate service does not exist:

Open Communications → Messaging → Services, or Messaging → Services in the legacy Console.
Click Create a Messaging Service.
Enter a descriptive name, such as AirMDR Security Notifications.
Select the messaging use case appropriate for your notifications.
Continue through the setup wizard.
Add an eligible sender to the Sender Pool.
Complete any applicable sender registration or verification requirements.
Open the created service and copy its Messaging Service SID.

The service must belong to the Account SID entered in AirMDR.Its Sender Pool must include at least one eligible phone number, short code, or supported alphanumeric sender.An empty Sender Pool prevents sending.

Twilio’s setup wizard guides you through sender configuration, application integration, and applicable compliance requirements.

Twilio Credential Reference Table

AirMDR Field	Value to Enter	Where to Obtain It
Account SID	SID of the account that sends the messages; begins with `AC`.	Twilio Console home page → Account Info.
Username	Standard API Key SID beginning with `SK`, or the Account SID for account-based authentication.	API key creation result, or Account Info.
Password	Secret belonging to the API key, or the account Auth Token.	API key creation result, or the account’s Auth Token display.
Messaging Service SID	SID of the sending service; begins with `MG`.	Messaging → Services → select the service → Properties.

Keep the credential pair together. An API Key SID must use its corresponding API Key Secret. An Account SID must use the corresponding account Auth Token.

Validate Connectivity

You can optionally validate the Twilio request. The following example illustrates the underlying Twilio request. It is not an AirMDR configuration import. Populate the environment variables securely before running the command.

Sample Request

For API key authentication, TWILIO_USERNAME is the API Key SID and TWILIO_PASSWORD is its Secret. The Account SID remains a separate value in the URL. This request creates a real outbound SMS.

curl --request POST \
  "https://api.twilio.com/2010-04-01/Accounts/${TWILIO_ACCOUNT_SID}/Messages.json" \
  --user "${TWILIO_USERNAME}:${TWILIO_PASSWORD}" \
  --data-urlencode "MessagingServiceSid=${TWILIO_MESSAGING_SERVICE_SID}" \
  --data-urlencode "To=${TWILIO_RECIPIENT}" \
  --data-urlencode "Body=AirMDR integration validation message."

Configure Twilio in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
Use the search option, enter the keyword “Twilio”, select the Connections tab, and click + New Connection button.

Use the following values in the AirMDR integration configuration screen:

Field	Description	Example
Instance	A unique name identifying this connection.	`Twilio-Production`
Organization	The AirMDR organization that will use the connection.	Select the appropriate organization.
Description	A short explanation of the connection’s purpose.	`SMS notifications for security responders.`
Account SID	Twilio account that owns the Messaging Service.	`AC` followed by the account identifier.
Username	Standard API Key SID, or Account SID when using account credentials.	`SK` followed by the key identifier.
Password	Corresponding API Key Secret or Auth Token.	Enter the secret securely.
Messaging Service SID	Twilio service used to send messages.	`MG` followed by the service identifier.

Expand Advanced Configuration if required. (Optional)

In Remote Agent, select an AirMDR Remote Agent when Twilio API requests must run through an approved network route. Ensure the selected agent can resolve and reach api.twilio.com over HTTPS on TCP port 443. For direct connectivity from AirMDR, leave this field unselected.
In Expiry, select a date according to your organization’s credential rotation policy, or an earlier date if the configured Twilio credentials will become invalid sooner.

Expiry controls credential validity in AirMDR. It does not automatically rotate, extend, or revoke credentials in Twilio. For API key rotation, create a replacement key, update Username with its API Key SID, Password with its Secret, and Expiry with the revised date. Save and validate the connection, then delete the previous key when it is no longer required. If using an Account SID and Auth Token, coordinate token rotation with other applications that use the same token.

Click Save.

Skills provided by this Integration & Permissions required

Messaging — Outbound Actions

Skill	Purpose	Required Access	Applicable role	Required permissions	Required Endpoint	Output
Send Twilio Text Message	Sends an SMS to one phone number through the Messaging Service configured on the connection.	Valid credentials for the sending account and access to create messages. The Messaging Service must belong to that account and contain an eligible sender.	Developer or Administrator for credential setup. Skill execution uses the credentials saved in the AirMDR connection.	Permission to create messages through `POST /2010-04-01/Accounts/{AccountSid}/Messages.json`. Authenticate using a Standard API Key SID and Secret, or the Account SID and Auth Token.	`POST /2010-04-01/Accounts/{AccountSid}/Messages.json`	Twilio Message resource, including its `sid`and current `status`.

An accepted or queued status confirms that Twilio accepted the request. It does not confirm delivery to the recipient.

Twilio Console roles govern user access during setup. Runtime access depends on the saved API credentials. A Standard API key provides broader account API access than message sending alone.

To view the details of Input Parameters and Output for the respective skills

Go to AirMDR → Twilio Integration page.
Select the Skills tab and click on the required listed skills.

Save and Validate the Connection (Optional)

Review the account, credential pair, and Messaging Service SID.
Click Save.
Open the Skills tab.
Locate Send Twilio Text Message and click Run skill.
Select the connection if prompted.
Enter the recipient phone number in international E.164 format, such as +14155550123, and enter a short test message.
Run the skill once.
Record the returned Message SID and status.
Confirm the message’s final delivery status in Twilio.

E.164 format uses +, the country code, and the subscriber number without spaces or punctuation.

Additional Information

🧰 Error Handling

Error or Symptom	Likely Cause	Recommended Action
20003 — Permission denied	Incorrect, revoked, mismatched, or wrong-account credentials.	Verify the Account SID and credential pair. Check the key’s account and Region. Replace invalid credentials.
21211 — Invalid recipient number	The recipient number is invalid or incorrectly formatted.	Use E.164 format and verify the country code and number.
21408 — Destination permissions disabled	The destination is disabled in Geo Permissions or is unsupported.	Review Messaging → Settings → Geo Permissions and the destination’s messaging requirements.
21608 — Unverified recipient restriction	Trial or account compliance restrictions prevent sending to the recipient.	Verify the test recipient or complete the account upgrade and compliance requirements identified by Twilio.
21704 — No available senders	The Messaging Service has no eligible sender in its Sender Pool.	Add a suitable sender and confirm it can reach the destination.
21610 — Recipient unsubscribed	The recipient opted out of messages.	Respect the opt-out. Resume messaging only through the applicable recipient consent and resubscription process.
20429 / HTTP 429 — Too many requests	API concurrency limits were exceeded.	Reduce concurrent requests and retry rejected requests with exponential backoff.
Remote Agent connection failure	The selected agent is unavailable or cannot reach Twilio.	Check agent availability, DNS resolution, proxy configuration, and outbound TCP `443` access.
Message accepted but not received	Delivery is pending or failed after request acceptance.	Find the Message SID in Twilio’s Messaging Logs and review the latest status and error details.

If a request times out without a clear result, check Twilio’s logs before resending. The original request may already have created a message, and repeating it may send a duplicate.

🔄 Monitoring & Logs

Review Execution Results in AirMDR

Open the result of the skill execution or the playbook step that ran it.
Review the returned Message SID and status.
Record any Twilio error code and error message.
Use the Message SID to correlate the execution with Twilio’s logs.

Review Messaging Logs in Twilio

Sign in to the sending account in the Twilio Console.
Open Monitor → Logs → Messaging.
Search for the Message SID or filter by recipient and time.
Click the message’s linked date to open its details.
Review the delivery steps, status, sender, recipient, and errors. Twilio

Interpret Message Status

Status	Meaning
`accepted`	Twilio accepted the request through the Messaging Service.
`queued`	The message is waiting to be sent.
`sending`	Twilio is sending the message.
`sent`	The upstream carrier accepted the message; recipient delivery is not yet confirmed.
`delivered`	Twilio received delivery confirmation.
`undelivered`	Twilio received a delivery-failure indication.
`failed`	The message could not be sent.

Message status can change after the initial API response. TwilioSample Monitoring RecordThe following is an illustrative record for operational logging, rather than an exact AirMDR log format:

{
  "integration": "Twilio",
  "skill": "Send Twilio Text Message",
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "status": "accepted",
  "recipient": "+********0123",
  "delivery_confirmed": false
}

Recommended Log LevelsWhere your logging system supports configurable levels:

Level	Recommended Use
INFO	Execution outcome, Message SID, timestamp, and status.
WARNING	Delivery delays or repeated transient failures.
ERROR	Authentication failures, rejected requests, and failed delivery.
DEBUG	Temporary troubleshooting with secrets and sensitive message content removed.

🛑 Security & Access Best Practices

✅ Do	❌ Don’t
Use a dedicated Twilio Standard API key for the AirMDR connection.	Don’t reuse one API key across unrelated applications or environments.
Enter the API Key SID as Username and its Secret as Password. Alternatively, use the Account SID and its Auth Token.	Don’t mix credential pairs or enter your Twilio Console login credentials.
Limit access to connection credentials and permission to run the messaging skill.	Don’t grant administrative access solely to send SMS notifications.
Store secrets securely and redact them from troubleshooting evidence.	Don’t include API secrets, Auth Tokens, or Authorization headers in screenshots, logs, or support tickets.
Allow HTTPS access to the required Twilio endpoint.	Don’t disable certificate validation to bypass connectivity errors.
Enable only the destination countries required for your notifications.	Don’t enable unnecessary destinations in Messaging Geo Permissions.
Send messages only to approved recipients and respect opt-out preferences.	Don’t repeatedly message recipients who have unsubscribed.
Keep SMS content brief and link recipients to an authenticated system for sensitive details.	Don’t include passwords, access tokens, or confidential investigation details in SMS messages.
Rotate credentials according to policy, update the AirMDR connection, and validate before retiring the previous credential.	Don’t assume the AirMDR Expiry field rotates or revokes credentials in Twilio.
Review the Message SID and delivery status before retrying an uncertain execution.	Don’t automatically resend after a timeout; the original request may already have created a message.
Monitor delivery failures, message volumes, and account usage.	Don’t treat `accepted`, `queued`, or `sent` as confirmation of recipient delivery.
Coordinate account Auth Token rotation with every application using that token.	Don’t replace a shared Auth Token without assessing the impact on other integrations.

A Standard API key provides broad API access within its Twilio account. Selecting a Messaging Service in AirMDR does not restrict the key’s permissions to that service.

👉 Support & Maintenance

📧 Contact AirMDR Support through your designated support channel.
🔁 Rotate credentials regularly. Recommended cadence: As per your internal security policy.
Rotate API Credentials
1. Create a replacement API key in the correct Twilio account and Region.
2. Update the AirMDR connection’s Username and Password.
3. Save the connection.
4. Run one controlled validation.
5. Confirm that the new credential works.
6. Delete the previous API key in Twilio after confirming that it is no longer required.
Deleting an API key revokes its access.
Maintain the Integration
- Review the connection’s Expiry date and credential renewal schedule.
- Confirm that the Messaging Service retains an eligible sender.
- Review destination permissions, account balance, and sender registration status.
- Monitor failed messages, delivery delays, and unexpected usage.
- Revalidate the connection after changing credentials, the Messaging Service, or the Remote Agent.
- Review dependent playbooks before retiring a connection.

🛑 Data Flow & Security

Data Exchanged

Direction	Data
AirMDR to Twilio	Authentication credentials, Account SID, Messaging Service SID, recipient phone number, and message text.
Twilio to AirMDR	Message resource containing the Message SID, current status, and other response metadata.
Twilio to recipient	SMS content sent through the selected sender and telecommunications network.

The skill’s returned status reflects the message state at execution time. Use Twilio’s messaging logs to check subsequent delivery changes.Encryption and Network Requirements

Area	Requirement
API transport	HTTPS protects communication with the Twilio REST API. Unencrypted HTTP is not supported.
Destination	`api.twilio.com` for the standard Messages API endpoint.
Port	Outbound TCP `443`.
Authentication	HTTP Basic authentication over HTTPS.
At-rest controls	Consult the current AirMDR and Twilio security documentation and service agreements for storage encryption and retention requirements.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Pre-requisites

Setup Steps

Option A: Create a Standard API Key

Option B: Use the Account SID and Auth Token

Option A: Use an Existing Messaging Service

Option B: Create a Messaging Service

Twilio Credential Reference Table

Validate Connectivity

Configure Twilio in AirMDR Integrations Dashboard

Skills provided by this Integration & Permissions required

Additional Information

​Pre-requisites

​Setup Steps

​Option A: Create a Standard API Key

​Option B: Use the Account SID and Auth Token

​Option A: Use an Existing Messaging Service

​Option B: Create a Messaging Service

​Twilio Credential Reference Table

​Validate Connectivity

​Configure Twilio in AirMDR Integrations Dashboard

​Skills provided by this Integration & Permissions required

​Additional Information

Pre-requisites

Setup Steps

Option A: Create a Standard API Key

Option B: Use the Account SID and Auth Token

Option A: Use an Existing Messaging Service

Option B: Create a Messaging Service

Twilio Credential Reference Table

Validate Connectivity

Configure Twilio in AirMDR Integrations Dashboard

Skills provided by this Integration & Permissions required

Additional Information