Phone calls and SMS notifications

Caution

As of 2025-03-11, Grafana OnCall OSS has entered maintenance mode, and will be archived on 2026-03-24. No further feature development will occur; however, we will still provide fixes for critical bugs and for valid CVEs with a CVSS score of 7.0 or higher. For more information, refer to our blog post.

Open source

Phone and SMS notifications for Grafana OnCall OSS

Warning

As of March 24, 2026, Cloud Connection features for phone calls, SMS, and push notifications will no longer be supported in Grafana OnCall OSS.

To learn more about this update, refer to the Maintenance mode notice for Grafana OnCall (OSS)

To ensure uninterrupted notifications, OnCall OSS users must set up phone and SMS notifications using one of these alternatives:

  • Use a third-party provider – Configure Twilio, Exotel, or Zvonok to send SMS and phone calls
  • Use webhooks – Set up OnCall to trigger custom SMS and call workflows via self-hosted solutions

This guide provides step-by-step instructions for configuring phone and SMS notifications using third-party providers.

Configure Twilio for OnCall OSS

To configure notifications with Twilio, you’ll need the following:

  • A Twilio account (sign up at twilio.com)
  • A Twilio phone number with SMS and Voice capabilities
  • API credentials (Account SID and Auth Token)
  • Administrator access to your Grafana OnCall OSS instance

Set up a Twilio phone number

  1. Log in to Twilio Console
  2. Navigate to Phone Numbers > Buy a Number
  3. Ensure the number supports SMS and Voice
  4. Copy your Account SID and Auth Token from the Twilio dashboard

Configure an outgoing webhook in OnCall

  1. In Grafana OnCall OSS, go to Outgoing Webhooks
  2. Click + Outgoing Webhook
  3. Configure the webhook:
    • URL: https://api.twilio.com/2010-04-01/Accounts/YOUR_TWILIO_SID/Messages.json
    • Method: POST
    • Headers:
json
{
  "Authorization": "Basic BASE64_ENCODED(TWILIO_SID:TWILIO_AUTH_TOKEN)",
  "Content-Type": "application/x-www-form-urlencoded"
}
  • Body (for SMS notifications):
json
{
  "From": "+YOUR_TWILIO_NUMBER",
  "To": "{{ user_phone }}",
  "Body": "New OnCall Alert: {{ alert_title }}"
}
  • Body (for phone call notifications):
json
{
  "From": "+YOUR_TWILIO_NUMBER",
  "To": "{{ user_phone }}",
  "Url": "https://handler.twilio.com/twiml/EHXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
  1. Click Save & test to verify the configuration

Your OnCall notifications should now be sent via Twilio.

Configure Exotel for OnCall OSS

To configure notifications with Exotel, you’ll need the following:

  • An Exotel account (sign up at exotel.com)
  • API credentials (SID, API Key, and Auth Token)

Set up Exotel API credentials

  1. Log in to Exotel Dashboard
  2. Navigate to API Settings
  3. Generate and copy the SID, API Key, and Auth Token

Configure an outgoing webhook in OnCall

  1. In Grafana OnCall OSS, go to Outgoing Webhooks
  2. Click + Outgoing Webhook
  3. Configure the webhook:
    • URL: https://api.exotel.com/v1/Accounts/YOUR_EXOTEL_SID/Sms/send
    • Method: POST
    • Headers:
json
{
  "Authorization": "Basic BASE64_ENCODED(EXOTEL_SID:EXOTEL_AUTH_TOKEN)",
  "Content-Type": "application/x-www-form-urlencoded"
}
  • Body (for SMS notifications):
json
{
  "From": "YOUR_EXOTEL_VIRTUAL_NUMBER",
  "To": "{{ user_phone }}",
  "Body": "New OnCall Alert: {{ alert_title }}"
}
  • Body (for phone call notifications):
json
{
  "From": "YOUR_EXOTEL_VIRTUAL_NUMBER",
  "To": "{{ user_phone }}",
  "CallerId": "YOUR_EXOTEL_CALLER_ID",
  "CallType": "trans"
}
  1. Click Save & test to verify the configuration

Your OnCall notifications should now be sent via Exotel.

Configure Zvonok for OnCall OSS

To configure notifications with Zvonok, you’ll need the following:

  1. Follow Zvonok’s documentation to create an API endpoint for sending SMS and calls
  2. Configure Outgoing Webhook in OnCall using Zvonok’s API URL and required parameters
  3. Test the setup to verify that phone/SMS notifications are working

Next steps

  • If you also use push notifications via Cloud Connection, refer to the Push Notification guide
  • Update your notification workflows before March 24, 2026 to ensure a smooth transition
  • Test your configuration to verify successful alert delivery

SMS notification behavior

OnCall reduces alert noise and distraction by bundling SMS notifications. When multiple alert groups require notification within a short period, the first alert group triggers an immediate SMS. A 2-minute “waiting period” follows, during which additional alerts are bundled. After this period, a single SMS with all alert information is sent.

Notifications are bundled based on their importance. Alerts from “default” and “important” notification policies are bundled separately.

Example bundled notification

If a user needs to be notified about 5 alert groups from 2 different integrations (3 from “Grafana Alerting” and 2 from “Health Check”), they will receive an immediate notification for the first alert group and a bundled SMS for the remaining alerts after 2 minutes:

Example bundled notification text:

Grafana OnCall: Alert groups #101, #102, #103 and 1 more, from stack: TestOrg, integrations: GrafanaAlerting and 1 more.

Route incoming calls to the on-call engineer

For guidance on configuring incoming call routing, refer to our documentation and blog post.

About phone call and SMS notifications

Please note the following about phone calls and SMS notifications:

  • Additional costs: There are no additional costs for outgoing calls or SMS notifications
  • Rate limits: There are no specific rate limits, but we reserve the right to stop sending SMS/calls in case of abnormal volume
  • Grafana OnCall phone numbers: To learn the phone number used by OnCall, make a test call from the “Phone Verification” tab

Country support for SMS/Voice

Note

Be aware that due to limitations in telecom provider services, some numbers within supported countries may occasionally be flagged as “high-risk” when verifying your phone number, preventing you from receiving notifications.

Ensure that you test your notification rules to confirm that OnCall can reach you. For added reliability, consider backing up phone calls and SMS notifications with additional methods, such as push notifications.

Refer to the following list for countries currently supported by Grafana IRM for SMS and phone notifications:

For a comprehensive list of all supported countries, please visit the Twilio international coverage page.