Getting Started

Aircall generates two types of AI summaries for completed calls:

Every eligible call gets a standard summary automatically. If the account also has a custom summary template configured, that call gets both — the standard summary and the structured custom summary are generated independently.

To learn more about how they work and how to set them up you can check our help center articles for AI assist and custom summaries.

If you are going to try some of the code examples make sure you have:

• An Aircall account with access to AI and Transcription API
• At least one completed, recorded call to test against.
• For custom summaries, a custom summary template used in at least one of your Aircall numbers.
• A valid OAuth access token or Basic Auth credentials

Standard summaries

The standard summary endpoint returns a single content string — a free-text paragraph describing what happened on the call. This is the simplest way to get a readable call note into your integration.

Subscribing to a webhook

The recommended approach is to subscribe to a summary.created webhook. See API reference here and also our webhook tutorial if you need help creating it.

The webhook contains the payload with the summary so there is no need to call anything else after that. Here is an example

{
  "resource": "conversation_intelligence",
  "event": "summary.created",
  "timestamp": 1779960465,
  "token": "some-webhook-token",
  "data": {
    "id": "81330225",
    "call_id": "3811606146",
    "call_uuid": "some-call-uuid",
    "content": "Agent from Aircall called to follow up and offer a product trial. Customer said they were waiting for a password; agent admitted she forgot to send it and committed to sending the password after the call. Customer agreed to test the product and email the agent when finished. Agreed action items: agent will send the password; customer will send a test completion email.",
    "number_id": 123456,
    "participants": [
      {
        "participant_type": "internal",
        "user_id": 123456
      },
      {
        "participant_type": "external",
        "phone_number": "+555 555 555 "
      }
    ]
  }
}

☝️ Always verify the data structure in the API reference. This snipetts might be outdated.

Using the REST API

You can also retrieve the standard summary with a call ID using the REST API. See more details in the API reference.

Custom summaries

Custom summaries extract structured data from a call based on a template configured by an account admin. Instead of a single paragraph, you get an array of named fields. Learn more about custom summaries in our help center.

For custom summaries we also recommend subscribing to a webhook (See API reference and webhook tutorial) but there are two key differences when compared to standard summaries

1. The webhook will not contain the actual summary
   It will only provide information on whether the data has been generated or not. More precisely is missing the content key. You will need to fetch it from the REST endpoint after you receive the webhook.
2. The custom summary data can be edited by users
   Because of that you will also need to subscribe to custom_summary.result_updated. See API reference.

This is an example of a webhook delivery. Notice how there is no content key in the summary_template_results array items:

{
  "resource": "conversation_intelligence",
  "event": "custom_summary.result_created",
  "timestamp": 1779960592,
  "token": "some-webhook-token",
  "data": {
    "id": 1433006,
    "custom_summary": {
      "name": "Test for Dev Portal"
    },
    "language": "EN",
    "call_id": "123456",
    "user_id": 123456,
    "number_id": 123456,
    "summary_template_results": [
      {
        "name": "Overall Summary",
        "type": "DISCOVERY",
        "ai_generated": true,
        "created_at": "2026-05-28T09:29:52.426Z"
      },
      {
        "name": "Budget Approved",
        "type": "OPTIONS",
        "ai_generated": true,
        "created_at": "2026-05-28T09:29:52.199Z"
      },
      {
        "name": "Demo",
        "type": "VALIDATION",
        "ai_generated": true,
        "created_at": "2026-05-28T09:29:52.243Z"
      }
    ]
  }
}

Understand template results

The summary_template_results array contains one entry per field defined in the template. Object properties are explained in the API reference.

Detect manual edits

Agents can edit custom summary fields after a call. When a field has been manually updated, two additional properties appear on the template result entry: updated_at (ISO 8601 timestamp) and updated_by (user ID of the agent who made the edit).

If your integration needs to distinguish between AI-generated and agent-corrected data — for example, to flag human-verified qualification answers — check both ai_generated and the presence of updated_at.

for (const field of result.summary_template_results) {
  const source = field.updated_at
    ? `edited by agent ${field.updated_by} at ${field.updated_at}`
    : field.ai_generated
      ? 'AI-generated'
      : 'manually entered';

  console.log(`${field.name}: ${field.content} (${source})`);
}

This works when you're already fetching summaries on demand. To find out about edits as they happen — subscribe to webhook events instead.