Aircall Integration Explained

Introduction

What Events Can Trigger a Webhook?

• User events (e.g., user.created)

• Number events (e.g., number.closed)

• Message events (e.g., sms.sent)

• Call events (e.g., call.ringing_on_agent)

• Contact events (e.g., contact.updated)

• Conversation Intelligence events (e.g., sentiment.created)

💡 Two Ways to Set Up Webhooks
This guide covers the two methods for configuring webhooks in Aircall:

1. Via the Aircall Dashboard: A simple, no-code approach.

2. Via the Public API: A more flexible method for developers.

🖥️ Method 1: Via the Aircall Dashboard

1. From the Aircall dashboard, navigate to the Integrations page and select "Webhook integration".

2. Click "Install".

3. (Optional) Give your webhook a custom name to easily identify it later.

4. In the URL field, enter the endpoint URL from your web server.

⚠️ Important Limitation
You can only provide a single URL, and you cannot customize the request headers for authentication. Any necessary tokens must be included as query parameters in the URL itself.

5. Toggle the switches for the events you want to subscribe to. By default, all events are turned on.

6. Click "Save" to finish the configuration.

👨‍💻 Method 2: Via the Public API

1. Get Your API Credentials (Basic Auth)

1. In your Aircall dashboard, go to your Company's Settings page.

2. In the API Keys section, click "Add a new API key".

3. This will generate an api_id and api_token. In Basic Auth, the api_id serves as your username and the api_token is your password.

2. Create the Webhook with an API Call

1. Create a new HTTP request with the POST method.

2. Set the URL to https://api.aircall.io/v1/webhooks.

3. Set the Content-Type header to application/json.

4. In the Authorization tab, select Basic Auth and enter your api_id as the username and api_token as the password.

5. In the Body of the request, provide a JSON object specifying the webhook's details:JSON

{
  "custom_name": "My Custom Workflow",
  "url": "https://my-server.example.com/webhooks/contacts",
  "events": [
    "contact.created",
    "contact.updated",
    "contact.deleted"
  ]
}

6. Send the request. A successful creation will return a 201 Created status code and the details of your new webhook.JSON

{
  "webhook": {
    "webhook_id": "c2501111-8a69-4342-bb34-bcd6cfe564ab",
    "direct_link": "https://api.aircall.io/v1/webhooks/26316",
    "created_at": "2020-03-24T19:51:24.000Z",
    "url": "https://my-server.example.com/webhooks/contacts",
    "active": true,
    "events": [
      "contact.created",
      "contact.updated",
      "contact.deleted"
    ],
    "token": "df76g76dpziygs567f0"
  }
}

✅ Best Practices & Key Notes

• Use HTTPS: Always use a secure HTTPS URL for your webhook endpoint.

• Return 200 OK: Your server should promptly return a 200 OK status code to acknowledge receipt of the webhook.

• Asynchronous Processing: Handle any time-consuming tasks in an asynchronous queue to avoid timeouts.

• Re-enable Deactivated Webhooks: Monitor for and automatically re-enable any webhooks that get deactivated due to repeated failures.

Difference Between call.hungup and call.ended

• call.hungup: This event fires immediately when a call ends, even if all the data (like recordings) isn't ready. It's best for real-time applications like dashboards.

• call.ended: This event fires after all call data is gathered (usually ~30 seconds after the call ends). It's best for archiving and processing complete call records.

📚 References

• Aircall Developer: Webhooks Guide

• Aircall API Reference: Create a Webhook