---
title: "Configure custom SMS and call routing with Twilio | Grafana Cloud documentation"
description: "Set up custom SMS and voice call routing to Grafana IRM using Twilio Studio Flows and a webhook integration."
---

> For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt).

# Configure custom SMS and call routing with Twilio

This guide walks you through setting up a custom system that routes SMS messages and phone calls to Grafana IRM using a Twilio phone number and a webhook integration. When a caller dials or sends a text to your Twilio number, Twilio Studio Flows forward the information to IRM as an alert, which then pages your on-call responders through your configured escalation chain.

Use this setup when you need:

- **SMS and text message alerts** routed to IRM.
- A **caller-selectable routing menu** — for example, “press 1 for Payments, press 2 for Infrastructure.”
- A phone number in a **country outside the US** without opening a support ticket.
- **More than three** routing phone numbers in your organization.

## Before you begin

To complete the steps in this guide, make sure you have:

- A Grafana Cloud account. If you haven’t already, [sign up for Grafana Cloud](/auth/sign-up/create-user).
- A Grafana IRM user account with administrator privileges and notification settings configured.
- A Twilio account. If you haven’t already, [sign up for Twilio](https://www.twilio.com/try-twilio).

## Basic setup

In the basic setup, you’ll create a webhook integration in IRM and configure a phone number in Twilio. This lets you receive alerts in IRM from SMS messages or phone calls made to your Twilio number.

[](/media/docs/grafana-cloud/oncall/big-OnCall-SMS-Diagram.png)

### Grafana IRM setup

In this section, you’ll create a webhook integration and an escalation chain in IRM to receive and route alerts from Twilio.

#### Set up a webhook integration

Create a new integration to establish an endpoint for receiving alerts and connecting them to routes and escalation chains. The [generic webhook integration](/docs/irm/next/guides/integrations/custom-integrations/incoming-webhooks/oncall-webhooks) accepts any payload and allows for customization of how the payload is handled in IRM.

To create the integration:

1. Navigate to **IRM > Integrations**.
2. Click **+ New Integration**.
3. Choose **Webhook (Generic)** as the integration type.
4. Provide a name, description, and optionally assign it to a team.
5. Note the integration URL for later use in Twilio.

#### Add an escalation chain

An escalation chain defines a sequence of notifications and other actions once IRM receives an alert.

Create a simple escalation chain to notify your user during the setup process:

1. Navigate to **IRM > Escalation chains**.
2. Click **+ New Escalation chain**.
3. Provide a name and click **Create Escalation Chain**.
4. For step 1, choose **Notify users** and select your user.

You can customize the [escalation chain](/docs/irm/next/guides/escalation-and-routing/escalation-chains) later to match your on-call process.

#### Connect and test the escalation chain

Connect the escalation chain to the new integration, then test that the setup is working:

1. Return to the webhook integration.
2. Under **Routes**, assign the new escalation chain as the default route using the dropdown.
3. Click **Send demo alert** and verify that you receive a notification.
4. Resolve the demo alert.

Next, configure Twilio to complete the other side of the integration.

### Twilio setup

In this section, you’ll create a Twilio Studio Flow and purchase a phone number to receive calls and messages.

#### Set up a Studio Flow

Twilio [Studio](https://www.twilio.com/docs/studio) flows let you create custom workflows that run when a phone call or SMS message arrives.

To set up the flow:

1. In Twilio, navigate to **Develop > Studio > Flows**. If Studio isn’t visible, select **Explore Products** and navigate to **Studio** under **Developer Tools**.
2. Select **Create new Flow**, enter a flow name, and click **Next**.
3. Select **Import from JSON** and click **Next**.
4. Import the flow JSON from the [Grafana IRM tooling repository](https://github.com/grafana/irm-tooling/blob/main/tools/twilio/basic_flow.json).
5. Replace `<YOUR_INTEGRATION_URL>` (lines 54 and 156) with the webhook integration URL from IRM.
6. Click **Next**, review the flow, and click **Publish**.

#### Understand your flow

The flow you created has two paths:

- **SMS path**: Accepts incoming messages and forwards their contents to IRM via the webhook URL, including the sender’s phone number.
- **Voice path**: Converts voice calls to text and sends them to IRM via the webhook URL.

[](/media/blog/oncall-sms-call-routing/studio-flow.png)

#### Buy a Twilio phone number

Purchase a phone number in Twilio to receive calls and messages:

1. Go to **Develop &gt; Phone Numbers &gt; Manage &gt; Buy a number**. If you don’t see Phone Numbers, select **Explore Products &gt; Super Network &gt; Phone Numbers**.
2. Search for a number in your desired country, select one, and purchase it.
3. Once purchased, the number appears in **Active Numbers**.

> Note
> 
> Some countries and regions require additional information to purchase a phone number, such as a physical address or contact details.

#### Configure the phone number

Configure your Twilio phone number to use the Studio Flow you created:

1. In **Develop &gt; Phone Numbers &gt; Manage &gt; Active Numbers**, select the purchased number.
2. For **Voice**: set **A call comes in** to **Studio Flow**, then select the flow you created.
3. For **Messaging**: set **A message comes in** to **Studio Flow**, then select the flow you created.
4. Save the configuration.

#### Test and troubleshoot

Test via SMS:

- Send an SMS to the purchased number and verify that you receive an “Alert sent” success notification.
- Confirm that you received a notification from IRM using your configured notification method.

Test via phone call:

- Call the purchased number, follow the instructions to describe your alert, and verify that you hear a success message confirming the alert was sent.
- Confirm that you received a notification from IRM using your configured notification method.

If you encounter issues:

- Confirm the correct integration URL is configured in the Studio Flow.
- Check the configuration of your Twilio phone number and confirm that **A message comes in** and **A call comes in** are both set to the correct Studio Flow.
- Review execution logs in Twilio Studio. In **Studio &gt; Flows**, select the flow you created and open **Execution Log**.
- Review the IRM escalation log. Check whether an alert group was created in IRM. If not, the alert didn’t reach the webhook URL. If an alert group exists, view its escalation log to investigate further.

### Basic setup complete

You’ve completed the basic setup to receive alerts via SMS and phone calls in Grafana IRM. Explore the advanced configuration section to learn how to route alerts to different escalation chains based on caller input.

## Advanced SMS and call routing

With the basic setup in place, you can add a caller-selectable routing menu. When a caller or sender contacts your Twilio number, they’re presented with options that determine which escalation chain handles their alert in IRM.

To accomplish this, you’ll add a route and a second escalation chain to your IRM webhook integration, then replace the Studio Flow with a more complex one that presents options to the caller.

### Create an additional escalation chain

1. Navigate to **IRM &gt; Escalation chains**.
2. Click **+ New Escalation chain**.
3. Provide a name and click **Create Escalation Chain**.
4. For step 1, choose **Notify users** and select your user. You can mark this chain as **Important** to differentiate it from the first one.

You can edit the escalation chain later to match your on-call process.

### Add a route

A route in IRM lets you specify how an alert is handled based on its payload, using sequentially matched Jinja2 rules. The first rule that evaluates to `true` for an incoming alert determines how that alert is routed.

In this setup, keep the existing escalation chain from the basic setup as your default route, and direct your new escalation chain to a second route:

1. Return to the webhook integration and click **Add Route**.
2. Click **Edit template** to open the template editor.
3. Enter `{{ "abc" in payload.target.lower()}}` to define routing logic based on alert content, then click **Save**.
4. Select the new escalation chain from the dropdown.

This template routes alerts to this chain when the Twilio payload contains a `target` field with the value `abc`. You can customize this logic to suit your needs — for example, routing by team, service, or region.

### Add an advanced Studio Flow in Twilio

Create a more complex flow that presents options to the caller or SMS sender:

1. In Twilio, navigate to **Develop &gt; Studio &gt; Flows**.
2. Select **Create new Flow**, enter a flow name, and click **Next**.
3. Select **Import from JSON** and click **Next**.
4. Import the flow JSON from the [Grafana IRM tooling repository](https://github.com/grafana/irm-tooling/blob/main/tools/twilio/flow_with_routes.json).
5. Replace `<YOUR_INTEGRATION_URL>` with the webhook integration URL from IRM.
6. Click **Next**, review the flow, and click **Publish**.

#### Understand your flow

This flow maintains the same two paths from the basic setup and adds steps that prompt the caller to specify the target for the alert, with validation to ensure accurate input.

- **SMS path**: Accepts incoming messages and forwards their contents to IRM via the webhook URL.
- **Voice path**: Converts voice calls to text and sends them to IRM via the webhook URL.

[](/media/blog/oncall-sms-call-routing/twilio-add-route.png)

### Reconfigure the Twilio phone number

Update your phone number to use the new flow:

1. In **Develop &gt; Phone Numbers &gt; Manage &gt; Active Numbers**, select the purchased number.
2. For **Voice**: set **A call comes in** to **Studio Flow**, then select the new flow.
3. For **Messaging**: set **A message comes in** to **Studio Flow**, then select the new flow.
4. Save the configuration.

### Test the advanced setup

Test the SMS and voice call paths to verify proper routing and that you receive notifications from IRM.

## Next steps

- [Escalation chains](/docs/irm/next/guides/escalation-and-routing/escalation-chains)
- [Routing rules](/docs/irm/next/guides/escalation-and-routing/routing-rules)
- [Webhook integration](/docs/irm/next/guides/integrations/custom-integrations/incoming-webhooks/oncall-webhooks)