Getting Started

Playbooks are a sales-focused feature of AI Assist Pro that guide agents through structured methodologies during live calls. To learn how playbooks work, how to configure them, and which templates are available, see the Using Playbooks with AI Assist Pro help center article.

With Aircall APIs you can use data generated by AI playbooks — including per-topic results and adherence scores. Use this endpoint to pull playbook data into your integration. This works really well for cases such as CRM enrichment, QA dashboards, coaching workflows, or any system that benefits from structured call qualification data.

This guide helps you get started retrieving the data. We recommend you also review our API documentation for Playbooks and Conversation intelligence webhooks.

Before you stat ensure you have:

• An Aircall account with an AI Assist Pro license
• At least one completed call on a number with a playbook enabled.
• A valid OAuth access token or Basic Auth credentials

If you are going to use this in an application or flow, the recommend approach is to first wait for the webhook playbook_result.created to notify you that the playbook results are ready. The time is always after the call but it can be ready sooner or later depending on different factors such as call length and so on.

Playbooks can also be updated by a user or supervisor so it's recommended that there is another webhook set for playbook_result.updated

Walkthrough

Subscribe to the webhook event playbook_result.created and playbook_result.updated to react to playbook results in real time instead of polling the REST API. If you are new to webhooks check our webhooks tutorial here.

Playbook webhooks do not contan the result data. They are just notifications so you know when it's ready. After you receive them you must retrieve the actual result using the REST API. Below we add a basic example for setting it up:

Configure the webhooks

const createWebhook = async (accessToken) => {
   const response = await fetch('https://api.aircall.io/v1/webhooks', {
      method: 'POST',
      headers: {
         'Authorization': `Bearer ${accessToken}`,
         'Content-Type': 'application/json'
      },
      body: JSON.stringify({
         custom_name: 'YOUR_APP_NAME',
         url: 'https://your.server.com/aircall/webhook',
         events: ['playbook_result.created', 'playbook_result.updated']
      })
   });

   const data = await response.json();

   if (!response.ok) {
      throw new Error(data.message || 'Failed to create webhook');
   }

   const webhookToken = data.webhook.token;
   return webhookToken;
};

Setup a handler to retrieve playbooks

const express = require('express');
const app = express();
app.use(express.json());

app.post('/aircall/webhook', async (req, res) => {
  res.sendStatus(200);

  const { event, data } = req.body;

  if (event === 'playbook_result.created' || event === 'playbook_result.updated') {
    const callId = data.call_id;

    const response = await fetch(
      `https://api.aircall.io/v1/calls/${callId}/playbook_result`,
      {
        headers: { 'Authorization': `Bearer ${process.env.AIRCALL_ACCESS_TOKEN}`}
      }
    );

    const result = await response.json();
    console.log(result);
  }
});

app.listen(3000);

Response

A successful request returns 200 OK with the playbook result object:

{
  "id": 75266,
  "call_id": 123456789,
  "user_id": 1234567890,
  "number_id": 112233,
  "adherence_score": 0,
  "playbook_result_topics": [
    {
      "name": "Budget",
      "result": "Budget: The agent explicitly asked ..."
    },
    {
      "name": "Authority",
      "result": "Authority: The agent explicitly asked ..."
    },
    ... 
  ],
  "created_at": 1777463792
    }