Offering SMS support to callers using the Ring to via API widget

Long hold times are one of the fastest ways to frustrate a caller. Instead of leaving customers waiting in a queue, or turning them away when every agent is busy, you can use your IVR to offer them support over SMS instead. When a caller chooses this option, Aircall sends a text message from one of your SMS-capable numbers to the caller. The caller replies at their own pace, and the conversation lands in your agents' Aircall inbox, where it's handled like any other SMS conversation.

This is useful in two common situations:

• Proactive choice: offer SMS up front so callers who prefer messaging never have to wait on hold.
• Overflow, all agents busy: when no agent is available, offer SMS as a way to still get help instead of only waiting in the queue or dropping off.

Because SMS only reaches callers in the countries your sending number covers, it works best when your callers and your numbers are in the same market. To offer messaging to callers anywhere, you can offer WhatsApp on the same branch as well: one WhatsApp-capable number reaches any caller who uses the app, whatever their country. See Offering WhatsApp support to callers using the Ring to via API widget.

Note: This setup involves building an API request inside a call flow, including a JSON body and Basic authentication. You don't need to be a developer, but you should be comfortable following technical, step-by-step instructions.

How it works

1. A customer calls your Aircall number and enters your call flow.
2. The caller reaches a point where SMS is offered, either as a menu option ("Press 1 to get help by text message instead of waiting") or as an overflow branch that triggers when no agent is available.
3. On that branch, the Ring to via API widget sends a request to Aircall's messaging endpoint, specifying which SMS-capable number to send from, the text to send, and which number to send to (the caller's own number).
4. The caller receives the SMS and can reply. Their reply lands in the same conversation in the Aircall inbox, visible to your agents.
5. The call ends with a short spoken confirmation.

Important: The Ring to via API widget sends the request but cannot branch the call based on the API response. Everything after the widget (a confirmation message, ending the call, or an alternative route) has to happen regardless of whether the message actually sent.

Before you begin

Make sure the following are already true before starting:

• Plan: you're on the Aircall Professional plan. Both the Ring to via API widget and direct Messaging API access are Professional features; Custom plans include everything in Professional. To upgrade, contact your Aircall account manager.
• Access: you have Admin access to the Aircall Dashboard and the call flow editor.
• An SMS-capable sending number: the number the text is sent from must be enabled for SMS in your account.

The specific IDs and credentials you'll need (number ID, API key ID and token) are retrieved in Steps 1 and 2 below, you don't need to gather those in advance. For general background on how Aircall's API works, see Aircall for Developers: API references. For messaging-specific background, please see Aircall Messaging API and SMS overview for developers.

Step 1: Choose the number the SMS is sent from

The message is sent from one of your Aircall numbers, and that number decides where the conversation lives. Pick it before you build anything.

Steps

1. Confirm the number is SMS-enabled. Please see SMS (Business Text Messaging) for eligibility by country and number type.
2. Check who should see the replies. Every agent assigned to that number sees the conversation and can reply from their Aircall app, so choose a number the right team already manages.
3. Decide whether to reuse the number the caller dialed. Running a call flow doesn't stop a number from sending SMS, so the number the caller dialed can also be the sender, provided it's SMS-capable. Many voice numbers aren't, so the safest default is to hard-code a number you know is SMS-enabled.

Note: Optionally, the request can name a specific agent with the agentId field, which attributes the outgoing message to that user. That user must be assigned to the sending number, otherwise the request is rejected. Leave the field out and the message is attributed to "external tool" in the Aircall Workspace.

Step 2: Gather your Number ID and API credentials

You need two things for the request, both retrieved outside the call flow editor.

API ID and API token

Go to Aircall Dashboard > Integrations > API Keys and click on Generate API Key. Enter a key name, then copy the API ID and API token before closing the window, the token isn't shown again. These are the credentials the widget uses to authenticate. Please see Getting your Aircall API key for more detail.

Number ID

The ID of the SMS-capable number the text is sent from. There are two ways to get it:

• From the Dashboard URL (quickest): open Numbers, select the number, and read the ID from the address bar. In https://dashboard.aircall.io/numbers/1186183/call-distribution, the number ID is 1186183.
• From the API: call the List all Numbers endpoint; each number in the response has an id.

Either way, this is the value you put in the request URL.

Important: The number ID goes in the URL path of the request, not in the request body.

Step 3: Build the call flow in the Flow editor

Steps

1. Go to Aircall Dashboard > Numbers > Numbers.
2. Select the number and click the green Edit button to open the Flow editor.
3. Decide where SMS is offered:

   • As a menu option: add an IVR menu widget, for example, "To continue by text message instead of waiting, press 1. To stay on the line, press 2."

     

   • As an overflow: place the Ring to via API widget on the branch reached when no agent is available.

     

Step 4: Configure the Ring to via API widget

Add the Ring to via API widget on the SMS branch and configure the request as follows. This request uses the Send message in agent conversation endpoint, which is what makes the conversation visible to agents.

Authentication

The endpoint uses HTTP Basic authentication. In the widget's authentication settings, choose Basic and enter:

• Username: your API ID

• Password: your API token

  

The widget builds the authorization for you, no manual encoding needed.

Request configuration

• Method: POST
• URL: https://api.aircall.io/v1/numbers/1018591/messages/native/send, replace 1018591 with your own number ID from Step 2.

Request body:

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply to this text and an agent will help you shortly."
}

Request body, attributed to a specific agent (optional):

{
  "to": "{{callerNumber}}",
  "body": "Thanks for calling! Reply here and an agent will pick this up shortly.",
  "agentId": 456789
}

Field reference:

• to (required): the number the SMS is sent to. Use E.164 format, with a + and the country code. Use {{callerNumber}} so the Flow editor inserts the caller's own number at runtime, it already resolves to E.164.
• body (required): the text to send, up to 1,600 characters. Longer messages are rejected.
• agentId (optional, integer): the Aircall user ID the message should be attributed to. The user must be assigned to the sending number.
• The number ID is not a body field, it's the :id segment of the URL.

Call flow variables you can use in the URL or body: {{callerNumber}}, {{targetNumber}}, {{callUUID}}, and {{lineId}}. If your flow contains an Input IVR widget, its captured input is available as an extra variable named after that widget. Substitution works in both the URL and the request body.

Hard-coding the sending number ID in the URL, as above, is the clearest approach. You can instead use {{lineId}}, which resolves to the number the caller dialled, but only if that number is itself SMS-capable.

Important: {{callerNumber}} sends the text to the number the caller is dialling from. If that number can't receive SMS, a landline, or an international number outside your number's allowed destinations, delivery will fail. Keep this in mind when deciding whether to offer the SMS option to every caller.

Response configuration

The widget requires a response configuration before the flow will publish, even though this flow doesn't route on the response (the call is closed in the next step regardless of the result). Fill these with a placeholder that intentionally doesn't resolve:

• Response type: Aircall number (internal)
• Path: null

The SMS is sent before the widget looks at the response, so the message still goes out. Because the path never resolves, the widget treats the response as invalid and simply continues to the next step in your flow, which is what you want here.

Note: All Aircall public API endpoints share a limit of 120 requests per minute. Each number also has its own hourly, daily, and monthly message caps, which reset in UTC and are shared with the skipping-inbox endpoint (US and Canada long code and toll-free: 5,000 / 10,000 / 100,000; UK, Australian, German, Spanish, and French platform numbers: 500 / 2,000 / 20,000; French mobile numbers: 100 / 1,000 / 10,000). This shouldn't affect a typical call flow, but is worth knowing if you're testing at volume. Requests from the widget time out after 10 seconds and are not retried.

Step 5: Close the call flow

Because the widget can't react to the API response, finish the branch cleanly regardless of outcome.

Steps

1. After the widget, click + and add an Audio Message such as: "We've just sent you a text message. You can reply there whenever you're ready. Thanks."
2. End the call, or route to voicemail or another team as a fallback.

Note: The Flow editor greys out the steps that follow a Ring to via API widget, because it assumes the call leaves the flow to ring a target. In this setup the call doesn't leave the flow, so those steps do run. The greyed-out styling is a known display quirk and you can safely ignore it.

Step 6: Test the flow

Test the request from inside the widget first, then place a real call once it works.

Test from the widget

The widget can simulate a caller, so you don't have to publish the flow or dial in to check that the SMS goes out.

Steps

1. In the widget, find the Test request field and enter a payload naming the number to simulate:

{
  "callerNumber": "+15551234567"
}

2. Click Test request. The widget behaves as if that number had called and reached this point in the flow, so the SMS is really sent, use a number you can check.
3. Confirm the text arrives, and that the conversation appears in the Aircall inbox.

Note: The test will report an error even when the message sends correctly. That's expected: the response configuration deliberately points at a path that never resolves, so the widget judges the response invalid. Ignore the error and confirm the result on the handset and in the inbox instead.

Test the whole flow

Steps

1. Click Publish in the top-right corner.
2. Call the number from a mobile phone that can receive SMS.
3. Reach the SMS branch (select the option, or trigger the overflow condition).
4. Confirm: you receive the text, the wording is right, the spoken confirmation plays, and replying opens, or continues, a conversation in the Aircall inbox.

If the message doesn't arrive, see the troubleshooting table below.

Troubleshooting

The full list of response codes for this endpoint is in the API reference.

FAQs

Will my agents see the SMS conversation if the caller replies?

Yes. This request uses the Send message in agent conversation endpoint, so both the outgoing message and the customer's reply appear in the Aircall inbox for every agent who manages the sending number, and in Message webhook events.

Do I need an approved template for the message?

No. The text is free-form, written directly in the request body, up to 1,600 characters. There's no template to get approved and no messaging window to respect.

What about callers in other countries?

SMS through the API is domestic only, with the exception of US–Canada, so a caller can only be texted from a number that covers their country. If your callers are spread across countries, either add a local SMS-capable number per market, or offer messaging over WhatsApp on the same branch instead, WhatsApp isn't tied to the caller's country, so one WhatsApp-capable number reaches anyone who uses the app. See Offering WhatsApp support to callers using the Ring to via API widget.

Can I send an image or PDF instead?

No. MMS isn't supported on this endpoint. If you need media, use the Send Message Skipping Aircall Inbox endpoint, but those messages don't appear in the Aircall app, so agents can't pick up the conversation.

Can I send from the same number the caller dialled?

Yes, as long as that number is SMS-capable and isn't configured for skipping-inbox messaging. Running a call flow, including one with an IVR menu, doesn't prevent a number from sending SMS. In practice many voice numbers aren't SMS-enabled, which is why this article hard-codes a known SMS-capable number. If the dialled number is SMS-capable, you can use {{lineId}} in the URL instead.

Can I personalise the message with caller data?

Yes, within what the call flow editor exposes. You can insert {{callerNumber}}, {{targetNumber}}, {{callUUID}}, or {{lineId}} into the body text, plus any input captured by an Input IVR widget earlier in the flow. Anything richer (a name from your CRM, for example) would need a middleware layer that looks the caller up and calls the Aircall API itself.

What happens if the caller's number can't receive SMS?

Delivery fails, and the widget can't tell the caller. Since the message goes to whatever number the caller dialled in from, always keep a spoken fallback and a queue or voicemail route on that branch.