What are AI Events?

AI Events are records created when an external system sends activity into your account through the AI Events API (Zapier).

They are typically used to log customer interactions from tools like AI phone agents, chatbots, SMS workflows, or other automations.

Each event can optionally be matched to an existing customer record so your team can see it in the right place without adding it manually.

To connect systems through Zapier, see the Zapier API Integration Guide.

How AI Events work

1. A system sends an AI Event

An external system sends event data to the AI Events API.

Each request includes:

  • customer_lookup, which is used to find the customer
  • ai_event, which contains the event details

2. We try to match the event to a customer

The customer_lookup object is required. You must provide at least one of these:

  • email
  • phone
  • first_name and last_name

We try to find a customer in this order:

  1. Email
  2. Phone
  3. First name + last name

Note: Name matching is only used when both first_name and last_name are provided. If multiple customers share the same name, the first match is used.

3. The event is saved

If a customer match is found, the event is linked to that customer.

If no match is found, the event is still created but remains unmatched.

Data Elements

The ai_event object contains the event details.

Required fields

  • event_type — Type of event
  • source — Name of the system sending the event
  • summary — Short description shown in the CRM timeline
  • raw_payload — Full event data from the source system
  • occurred_at — When the event happened, in ISO8601 format

Optional fields

  • confidence — Confidence score from the source system
  • idempotency_key — Unique key used to prevent duplicates
  • source_eid — External reference ID for the sending system’s own tracking, such as a call ID, session ID, or Zap run ID. This is stored for reference but is not used by the CRM for matching, display logic, or other behavior.

Limits

  • summary max length: 500 characters
  • raw_payload max length: 5000 characters

Example Request

{
“customer_lookup”: {
“phone”: “+1 (555) 867-5309”
},
“ai_event”: {
“event_type”: “phone_call”,
“source”: “retell”,
“summary”: “Customer called about delayed shipment for order #789.”,
“raw_payload”: “{\”transcript\”: \”Hi, I’m calling about…\”, \”duration\”: 245}”,
“confidence”: 0.92,
“source_eid”: “call_abc123”,
“idempotency_key”: “retell-abc123-1”,
“occurred_at”: “2026-03-10T14:30:00Z”
}
}

Event types

The event_type must be one of the following:

phone_call, sms, email, chat, workflow, note, review, escalation, other

Duplicate prevention

To prevent duplicate records, each event can include an idempotency_key.

If the same idempotency_key is sent more than once, a new event is not created. Instead, the API returns the existing event.

If no idempotency_key is provided, one is generated automatically.

Where to view AI Events

For a customer

Open the customer’s details page and look for the AI Events section.

For unmatched events

On any AI Events list page, click View Unmatched Events to see events that were created without a customer match.

How to associate an unmatched event

  1. Open any AI Events page.
  2. Click View Unmatched Events.
  3. Open the Event Details Page
  4. Select the correct customer from the dropdown.
  5. Click Associate Customer.