About Aircall Messaging API

Introduction

The Aircall Message API is part of Aircall's suite of developer tools that allow external applications and services to interact programmatically with Aircall's messaging capabilities. This provides businesses the ability to create automations, integrations, and streamline workflows related to SMS and MMS.

This article covers:

• Overview of the Messaging API 
  • Selecting the proper endpoint for your needs
    • Option 1: ‘Send Message’
    • Option 2: ‘Send Message in Agent Conversation’
  • Use case examples
• Considerations when using the API for sending SMS 
  • General guidance on Aircall regulations
  • Rate limit specifications
• Pricing details

Overview of the Messaging API

Through this public API, admins can retrieve messaging activity, send messages, and ensure compliance, among other capabilities. When it comes to sending messages, you can leverage the Messaging API with two distinctly different endpoints. Using the descriptions and examples below, it is important to select the endpoint option that fits your needs (since they behave differently). 

It is not possible to use both endpoint options on the same Aircall number simultaneously.

Selecting the Proper Endpoint for Your Needs

Before selecting an option, please note: 

• API Messaging is only possible for Aircall numbers that are enabled for SMS
• Aircall numbers with API Messaging can still be used for inbound & outbound calling in Aircall apps.

Option 1: ‘Send Message’ Endpoint

When using the Send Message endpoint with an Aircall number, the SMS/MMS sent & received are not viewable within Aircall apps or webhooks. This means messages sent & received will not be visible for users to see directly in Aircall. Therefore, with this option, it is the client's responsibility to record any messages sent & received in an external location of your choice.

❌ Sent & received SMS/MMS will not appear in Aircall webhooks

✅ MMS is supported with this option

⚠️ Once a number is configured with this endpoint, it can no longer send/receive messages from the Aircall app interfaces. To revert back to users sending/receiving messages in Aircall apps, the configuration must be deleted from the number.

Use case examples

• Build an integration so users can see and reply to text messages directly from an external tool (see blog for more inspiration)
• Send non-conversational messages like one-time verification codes for two-factor authentication purposes, automated order confirmations, or delivery notifications via SMS
• Send non-conversational messages for marketing and promotional content via SMS

This article and tutorial further explain how to leverage the Send Message endpoint with an Aircall number.

Option 2: ‘Send Message in Agent Conversation’ Endpoint

When using the Send Message in Agent Conversation endpoint with an Aircall number, the SMS sent & received are viewable directly in Aircall apps (unlike option 1). 

❌ Sending MMS via API is not currently supported with this option

✅ Sent & received SMS are viewable in Aircall apps and via Message Event Webhooks 

⚠️ This option combines automation and the ability for Aircall users to continue the conversation as shown below. 

Use case examples 

• Send an automated message to greet customers that text your Aircall number. Let them know they will be assisted shortly (screenshot below). This also illustrates how the messages sent via API are displayed with “External Tool” as the sender name in Aircall apps. 

• Triggering messages based on CRM activities. For example, if a customer moves to a specific stage, the API can send a message to engage the customer and any response appears in Aircall for a team member to continue the conversation.

As shown above, customers can respond to messages sent via API, and those responses will be displayed directly in the conversation view for Aircall users to have visibility and continuity as they communicate with customers. 

This article further explains how to leverage the Send Message in Agent Conversation endpoint with an Aircall number.

Aircall API Messaging Features and Regulations

Regardless of the tool you use to send SMS, industry standard and local regulations still apply. 

In the US or Canada, sending SMS in an automated way and for marketing content is acceptable given that the number is registered for the proper purpose (see article on A2P 10DCL registration and toll-free) and that you can prove consent.

Mobile lines are meant to be personal, meaning they should only be attached to a single agent. When using the API with mobile lines, you must ensure only the said agent controls the use case implemented.

In France for instance, mobile lines are meant for personal and conversational use cases only, meaning using the API to send SMS in an automated way is forbidden. Still, it is possible to engage in conversational communication via API. 

⚠️ Seek local guidance to ensure you are setting up compliant use cases. 

Considerations when using the Messaging API

Regulatory Requirements

• The configuration of US long codes or US/CA toll free numbers will only work for fully registered numbers. 
• We only allow domestic sending, with the exception of messages between US and Canada — same as the behavior described for messaging directly from Aircall applications.

Rate Limits

• Aircall API limits the number of requests to 60 per minute regardless of the endpoint used. Some specific restrictions are also applied to avoid overuse of the send message function. Aircall implements specific hourly, daily and monthly limits that are different for each type of numbers and country. These limits are subject to change without prior notice to ensure proper usage.  
• US and CA numbers are given 1,000 hourly, 10,000 daily, and 20,000 monthly outbound segment SMS limits.
• French mobile lines are given 100 hourly, 1,000 daily, and 10,000 monthly limits to ensure conversational use cases.
• Other line limits are 500 hourly, 2,000 daily, 20,000 monthly outbound SMS segments.

Pricing 

Access to send message API is included in the Professional plan. Contact your Customer Success Manager or support team if interested in upgrading your subscription plan. 

• Fees per volume sent are the same as the fees when sent via Aircall apps. 
• Volume coming from both API and Application sources will be summed up in your invoices.  

To proceed with option 1, continue reading: Getting Started with Sending Messages using Aircall’s API.

To proceed with option 2, continue reading: Getting Started with ‘Send Message in Agent Conversation’ Endpoint in Aircall’s API