Sending customer events

A call is one thing that happens with a customer. A WhatsApp message, an email, an order, a support ticket and a note in your CRM are others. POST /customer-events lets any system tell Callens about one of them, so that it is stored on the same customer as their calls.

There is one endpoint and one shape for every kind of event. Callens has no connector for WhatsApp, a shop or a CRM: whatever system holds the event sends it — a few lines in n8n, Zapier, or your own backend.

{
  "customer": {
    "phone": "+201001234567",
    "email": "ahmed@example.com",
    "external": [{ "namespace": "shopify", "id": "82931" }],
    "name": "Ahmed Mohamed"
  },
  "event": {
    "type": "message_received",
    "channel": "whatsapp",
    "occurred_at": "2026-10-04T14:32:00Z",
    "content": "ممكن أعرف السعر؟",
    "source": "n8n",
    "external_id": "wamid.HBgMMjAxMDAxMjM0NTY3"
  }
}

One event per request. There is no batch endpoint.

Before you start

Two things must be true, and each has its own refusal.

• The key has the events scope. Mint one under Settings → API keys. A key that can only submit calls cannot submit events, and a key that can only submit events cannot submit calls. See authentication.
• Your plan includes customer events. If it does not, every request is refused with 403 and customer_events_not_in_plan. Retrying does not help; ask for the feature to be added.

The customer

Send at least one of phone, email and external, and send every one you have.

Callens looks each identifier up, exactly as written. Nothing is matched by name, by similarity or by guesswork.

Phone numbers

Callens reads a number into international form, so 01001234567, 00201001234567, 201001234567 and +201001234567 are one customer.

A number written in national form, such as 01001234567, is read in your organization's own country. That country is a reading rule. It is not a way to find out where a customer is.

A string that cannot be read as a phone number — an extension, a short code — is kept as written and matches only the identical string.

The event

content is text

content is the message text, the note, or one line describing what happened, such as "Order 1234 placed, 5,000 EGP".

Callens stores that sentence as it is. It does not parse it. From "Order 1234 placed, 5,000 EGP" Callens does not conclude that an order with id 1234, an amount of 5,000 or a currency exists, and an order_created event does not create an order anywhere. If you want something understood, say it in content in words.

What content is used for

Besides appearing on the customer's timeline, the content of an event can inform the analysis of that customer's later calls: when a call is analysed, the most recent events that came before it are given to the model as background, beside the customer's earlier calls. Only content is used, cut to its first 300 characters — never metadata and never the identifiers in customer. It is sent to the AI provider as a call's transcript is. An event whose identifiers named two different customers is kept on the timeline and is not used this way.

The same is true while a call is in progress. When a call arrives over Live Connect and says who is calling, the line Callens suggests to the agent can be written with that customer's most recent events as background, under the same limits and the same exclusion. The agent may read that line aloud.

It can also inform a summary of the customer. Where the customer summary is switched on, Callens writes a short account of where things stand with a customer and shows it at the top of the journey card on the customer's page. It is written from the same background — the customer's calls and most recent events — under the same limits and the same exclusion, and content is sent to the AI provider for it as it is for a call's analysis. The summary is derived from the record and does not outlive it: it is written again as the record changes, and when a call or an event is deleted, what was written from it goes with it.

So put in content what you are happy for the analysis of the next call to have read, for an agent on the next call to be prompted by, and for a summary on the customer's page to be written from.

What type, channel and direction are used for

The customer's page also carries a journey card: who had the last word, through which channels you deal with this customer, and how often. Those are computed when the page asks for them, from the customer's calls and events of the last 90 days, and are stored nowhere. (The written summary at the top of the card, where it is switched on, is the one part of it written from content, and the one part that is kept; it is described above.) Of an event the rest of the card reads type, channel, direction and occurred_at — never content or metadata — so what you send in those fields decides what it says:

• direction decides who had the last word. A customer whose newest contact is an inbound event is shown as awaiting your reply; one whose newest contact is outbound, as awaiting theirs. A call answers whatever came before it. An event with no direction — an order, a visit — is counted, answers nothing, and is nobody's last word. So send direction with a chat, form or ticket event when it is the customer speaking or being spoken to.
• channel is what it is counted under. Without one, an event is counted under the category of its type. An event you send on the channel call is counted with the customer's calls.
• A note_added event is counted as a note, not as contact. customer_created and customer_updated describe the record and are not counted.

Types

message_received and email_received are inbound; message_sent and email_sent are outbound.

Calls are not events. Send a call with POST /calls.

Retries

An event is identified by its source and external_id together. Sending the same pair again returns the event that was stored the first time, with 200, and changes nothing — not the event, not the customer, not the name. An event is never updated: a retry that carries different content gets the stored event back unchanged.

first request   external_id = abc123   → 201, event stored
retry           external_id = abc123   → 200, the same event

Responses

{
  "success": true,
  "message": "Event accepted.",
  "data": {
    "id": "gQ7bYx",
    "customer_id": "k3Vn8p",
    "identity": { "matched_on": "phone", "customer_created": false, "conflict": false }
  }
}

201 for a new event, 200 for a retry. Both ids are opaque strings.

identity.matched_on is the kind of identifier that named the customer — phone, email or external — or new when storing this event created the customer. phone_raw means the phone string could not be read as a number and was matched as written.

Refusals

The key and its scope are checked first, then the fields, then the plan.

How long events are kept

Events are kept for as long as your organization keeps calls. An event is removed once occurred_at is older than your retention period, so an event you send today about something that happened before that period is removed in the next nightly run. When a customer has no call and no event left, the customer record is removed with them.

A customer's events are erased with the customer when you file an erasure request for them.