Skip to main content
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.
The Messages API creates messages under the specified Twilio account. The Messaging Service determines which configured sender to use.
AirMDR authenticates to Twilio using HTTP Basic authentication. Configure either of the following credential pairs: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. 
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

A paid (upgraded) Twilio account with messaging enabled and sufficient balance to send notifications.
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.
Trial accounts have recipient, destination, content, and duration restrictions and are unsuitable for production alerting. Use an upgraded account for AirMDR notifications and complete the applicable sender registration and account compliance requirements.

Setup Steps

1

Obtain the Account SID

  1. Sign in to the Twilio Console.
  2. Select the account or subaccount that will send messages.
  3. Open its home page or account dashboard.
  4. On the Console Home page, locate the card named after the selected account and copy its Account SID, which begins with AC. In the legacy Console, this information appears under Account Info.
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.
2

Obtain the Username and Password

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

Option A: Create a Standard API Key

  1. In the Twilio Console, open Settings → Account settings → API keys & auth tokens.
  2. Select the appropriate Region. For example: United States (US1)
  3. Click Create API key.
  4. Enter an API key name, such as AirMDR-SMS-Production.
  5. Select Standard as the key type.
  6. Click Next.
  7. Copy the generated API Key SID and Secret.
  8. Store the Secret securely before leaving the page.
  9. Select Got it!, then click Finish.
For the legacy Console,
  1. Open Admin → Account management → Keys & credentials → API keys & tokens.
  2. Click Create API key.
  3. Enter a Friendly name.
  4. Select the Region and Standard key type.
  5. 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.
  6. Click Done.
Enter the following values in AirMDR:
Create the API key in United States (US1). AirMDR calls Twilio’s US1 API hosts; credentials created in another Region will be rejected.
You can also open API keys & auth tokens from the bottom of the account card on the Console Home page.

Option B: Use the Account SID and Auth Token

  1. Open the selected account’s Twilio Console home page.
  2. Navigate to Settings → Account settings → API keys & auth tokens.
  3. Select the Auth tokens tab, and locate Primary auth token.
  4. Click the eye icon to reveal and copy the Auth Token.
Enter the following values in AirMDR:
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.
3

Obtain the Messaging Service SID

Choose one of the following methods.
Option A: Use an Existing Messaging Service
(or)
Option B: Create a Messaging Service
If Messaging Services is not visible in the sidebar, use the Twilio Console search to search for Messaging Services.

Option A: Use an Existing Messaging Service

  1. In the current Twilio Console, open Communications → Messaging → Services. In the legacy Console, open Messaging → Services.
  2. Select the service AirMDR should use.
  3. Open Properties.
  4. Copy the Messaging Service SID, which begins with MG.
  5. Open Sender Pool and verify that the service contains a sender that can reach your intended recipients. If it does not, click Add Senders and add a phone number, short code, or supported alphanumeric sender ID.
    When sending to US recipients from a US 10DLC number, ensure that the number belongs to the selected Messaging Service and is associated with an approved A2P 10DLC campaign.

Option B: Create a Messaging Service

If an appropriate service does not exist:
  1. Open Communications → Messaging → Services, or Messaging → Services in the legacy Console.
  2. Click Create a Messaging Service.
  3. Enter a descriptive name, such as AirMDR Security Notifications.
  4. Select the messaging use case appropriate for your notifications.
  5. Continue through the setup wizard.
  6. Add an eligible sender to the Sender Pool.
  7. Complete any applicable sender registration or verification requirements.
  8. 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

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.

Configure Twilio in AirMDR Integrations Dashboard

  1. Navigate to AirMDR, provide the credentials and click Login
  2. Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select ADMIN → Integrations.
  3. Use the search option, enter the keyword “Twilio”, select the Connections tab, and click + New Connection button.
  4. Use the following values in the AirMDR integration configuration screen:
    1. In Remote Agent, select an AirMDR Remote Agent when Twilio requests must run through an approved network route. Ensure the selected agent can resolve and reach both api.twilio.com for sending messages and messaging.twilio.com for connection verification over HTTPS on TCP port 443. For direct connectivity from AirMDR, leave this field unselected.
    2. 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.
  5. Click Save.

Skills provided by this Integration & Permissions required

Messaging — Outbound Actions
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.
The Account SID and Messaging Service SID come from the saved connection. Twilio selects the sender from the Messaging Service’s Sender Pool.Request BehaviorEach skill execution makes one POST request. AirMDR does not automatically retry the send request.Requests use application/x-www-form-urlencoded encoding. A successful message creation returns HTTP 201 and a Twilio Message resource.
If an execution times out, check Twilio’s logs before running it again. A manual rerun can create another message even though the integration itself does not automatically retry.
  1. Review the account, credential pair, and Messaging Service SID.
  2. Click Save.
  3. Open the Skills tab.
  4. Locate Send Twilio Text Message and click Run skill.
  5. Select the connection if prompted.
  6. Enter the recipient phone number in international E.164 format, such as +14155550123, and enter a short test message.
  7. Run the skill once.
  8. Record the returned Message SID and status.
  9. Confirm the message’s final delivery status in Twilio.
E.164 format uses +, the country code, and the subscriber number without spaces or punctuation.
You can optionally validate the Twilio request.When you save the connection, AirMDR verifies it. If verification fails, the connection is not saved.AirMDR retrieves the configured Messaging Service using: GET https://messaging.twilio.com/v1/Services/{MessagingServiceSID}It checks that the returned account_sid matches the Account SID saved in the connection.This verification reads the service configuration and does not send an SMS. Successful verification confirms access to the service and account ownership; it does not confirm delivery to a particular recipient.
An optional test message can be sent separately using Send Twilio Text Message. This sends a real SMS and may incur charges.
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.
accepted confirms that Twilio received the request. Delivery and pricing information may become available later. Review the Message SID in Twilio’s Messaging Logs for the latest status.

Additional Information

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.
Review Execution Results in AirMDR
  1. Open the result of the skill execution or the playbook step that ran it.
  2. Review the returned Message SID and status.
  3. Record any Twilio error code and error message.
  4. Use the Message SID to correlate the execution with Twilio’s logs.
Review Messaging Logs in Twilio
  1. Sign in to the sending account in the Twilio Console.
  2. Open Monitor → Logs → Messaging.
  3. Search for the Message SID or filter by recipient and time.
  4. Click the message’s linked date to open its details.
  5. Review the delivery steps, status, sender, recipient, and errors. See Twilio Messaging Logs.
Interpret Message StatusMessage status can change after the initial API response. See Track the message status of outbound messages.Sample Monitoring RecordThe following is an illustrative record for operational logging, rather than an exact AirMDR log format:
Recommended Log LevelsWhere your logging system supports configurable levels:
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.
  • 📧 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 Standard API key in the same Twilio account using United States (US1).
    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.
  • To revoke a dedicated API key, open Settings → Account settings → API keys & auth tokens, select the key, and click Delete this key after confirming that it is no longer required.
Data ExchangedThe 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
Twilio’s message ValidityPeriod is separate from the Expiry field on the AirMDR connection. Connection Expiry does not set the SMS queue lifetime.