How to push live events into AI calls and chats: only what changes the next sentence

By the end of this guide, your payment gateway, order system and CRM will post short facts into whatever conversation a customer is having with your AI agent right now: a phone call, a WhatsApp thread, a website chat. The agent can mention a cleared payment at a natural pause instead of talking over the caller and, if it verifies identity, won't read an account update to someone who hasn't proved who they are.

The API call is one POST request. The real work is deciding which events deserve a place in a live conversation, who may hear them, and what stops a stale lookup contradicting them. The rule: push only what changes the agent's next sentence. Everything else stays in your CRM, where a lookup can find it.

Connecting your CRM covers lookups before the agent speaks and results flowing back by webhook. This guide covers the third direction: your systems telling a conversation already under way. New to agents? Start with the complete guide to AI voice agents.

Before you start

• An agent live on at least one channel, talking to contacts in your Callaro workspace.
• An API key with messaging write permission, kept on your server.
• Access to the systems that will send events: gateway webhooks, order system, CRM automations.
• A phone and a WhatsApp or chat session you control, for testing.
• If your agent verifies identity before sharing account details, its verification profile.

1. List the moments where an out-of-date agent costs you

Write down where an agent that doesn't know something causes harm. Typical cases:

• A payment clears while the agent is still asking for it.
• An order ships, or slips, while the customer is asking where it is.
• A loan is approved or a document is received while the customer is chatting about it.
• The customer books on your website while still on the phone with the agent.

For each, write what the agent should stop saying and what it should say instead. If you can't fill in both, it isn't a live event.

Start with two or three. Live context is deliberately small: a contact holds only its few most recent updates, and they go stale after a short window. It is for "what just happened"; history is the pre-call lookup's job.

2. Store the Callaro contact ID on your records

Events are posted to a contact's events endpoint (/api/v1/contacts/{id}/events), so your system needs the Callaro contact ID. Two easy ways to get it: create the contact through the contacts API with its phone number, which finds or creates it and returns the ID either way, or read it from the full contact record in the post-call webhook.

Store it next to your own ID. Contacts are unique per phone number within a workspace, so two CRM leads who share a number are one Callaro contact, and an event for either reaches the same conversations. A family sharing a landline is the classic case, and one more reason step 4 matters.

3. Write each event as a fact, not a script

An event has four parts: a short type label (payment, order shipped), one short sentence of text, optional structured data, and a speak flag.

Write the text as a plain fact in your business's words: "Payment received for the March instalment." or "Order shipped, delivery expected Thursday." The agent decides how to say it, and in which language. Post in English and the agent tells a Marathi-speaking caller in Marathi.

Don't write "Say: Great news, your payment is in!" A script fights the agent's own voice. On a call, the update arrives labelled as a platform update the caller didn't say, so the model treats it as information, not lines to read.

Keep it to one sentence; the API rejects long text. Put reference IDs and statuses in the data for tracing, but anything the agent should say must be in the text. A useful side effect: an amount stated in an event counts as a known figure on that call, so the agent's figure check won't treat it as invented.

4. Classify each event: account or general

Ask who may hear this. Callaro decides by type, never by wording. A small set of types, such as booking, appointment, callback, reminder, handover and transfer, are general: fine for anyone on the line. Every other type, including any you invent such as payment or order shipped, is account data by default. You can also set the class explicitly in the event's data.

This matters when an agent checks identity before sharing account details. On a live call, an account event waits until the caller passes the check, then goes in, in arrival order, and is spoken then if it asked to be.

In one reviewed call, before this rule existed, a payment confirmation landed while the caller was partway through a keypad verification step, and the agent announced it to someone who hadn't yet proved who they were. Classifying by type closed that gap, because nothing depends on how the text is worded.

Leave the default unless the fact is safe for a relative answering a shared phone to hear. If the agent has no verification profile, nothing is held, so settle verification first. The omnichannel explainer covers how identity links across channels.

5. Decide what speaks and what stays quiet

Without speak, the agent simply knows. On a call, the update is in front of the model for its next reply. In a chat, it becomes a note your team sees in the inbox and the customer doesn't, and the agent reads it on its next turn.

With speak on a call, the agent brings it up at the next opening. On the standard speech-to-text, LLM and text-to-speech pipeline it waits for the caller to finish, and if the caller takes the turn first, that reply already carries the update, so the separate announcement is dropped rather than repeated.

With speak in a chat the AI is handling, the agent gets a turn of its own: it can send a message, or stay silent if nothing is worth saying. On WhatsApp outside Meta's 24-hour customer-service window, free text can't go out, so that turn stays silent unless an approved template fits.

Use speak for what the customer is waiting on: the payment they just made, the approval they asked about. Keep everything else quiet. And send one event per meaningful change: if your CRM saves five fields in a row, post one event that sums up what changed.

6. Target the right sessions and make retries land once

By default an event goes to the contact: every live call and open conversation with that person. You can narrow it to one live call, by its call reference, or to one conversation, not both, and it then stays there. Narrow it when the event belongs to one session, such as a payment link sent in one WhatsApp thread.

Post even when nothing is live. The response says which calls and conversations it reached and confirms the update was stored. On agents that don't hold account details back for verification, a stored update also reaches, while fresh, the next turn of a chat and a call that connects shortly afterwards, even an outbound call still ringing when you posted.

Send your own idempotency key, ideally the source's event ID. Without one, Callaro derives a key from the type, text and data, which absorbs a quick retry but not a late one.

Gateways retry for longer than you might expect: Stripe's webhook docs warn that an event can arrive more than once and out of order, and Razorpay's best practices describe at-least-once delivery with a unique event ID for spotting duplicates. Check the current status at the source before posting, so a late "payment failed" never follows a "payment captured".

One thing not to post: payments through a link the agent created with Callaro's own payment connection. The platform already tells a live call when those are paid or fail. Post events for money that arrives another way: your own checkout, a bank transfer, a branch counter.

7. Teach the agent what each update means

The event says what happened; the prompt says what to do about it. Add one rule per event type:

• When an update says a payment arrived, thank the customer once, stop asking for payment and confirm the next step.
• When an update says an order is delayed, apologise once, give the new date from the update and offer a callback.
• When an update says a document was received, don't ask for it again.

The prompt-writing guide covers where rules like these belong.

Then deal with lag in your own records. In another reviewed call, an agent was told a payment had arrived, then called a balance lookup that still showed the instalment as overdue, and believed the lookup: a tool's answer outweighed an earlier note.

Callaro now treats a call's earlier lookup answers as out of date once an update arrives, and a later lookup carries the update alongside its result, so the model knows which came first. Do your part too: post the event after your own record is updated, or point the lookup at the same source.

8. Test on real sessions, then keep watching

Events reach real sessions only: dashboard test-panel calls and builder test chats are kept apart from live context. Test with a real call to a phone you own and a real chat on a contact you created:

1. Post a speak event while you're mid-sentence. The agent should wait, not cut in.
2. On a verification-gated agent, post an account event before you pass the check. Nothing should be said until you pass, then it should be.
3. Post the same event twice with the same key. It should land once.
4. Keep a chat open during a call and post once. Both should get it.
5. On an agent without identity gating, post with nothing live, then message it on WhatsApp from that contact's number. It should know.
6. Post a speak event to a WhatsApp thread whose 24-hour window has closed. No free text should go out.

After launch, read a sample of inbox threads, where events show as system notes, alongside call transcripts. Look for updates the agent ignored, repeated or announced at the wrong moment; each usually points to a prompt rule or speak flag to change.

Common questions

Can an event start a conversation?

No. Events go to conversations already in progress, and are held briefly for ones about to start. To call someone the moment something happens, use the outbound-call API, which the CRM guide walks through.

Should I use events instead of the pre-call lookup?

Use both: the lookup gives the record as it stands when the conversation starts, and events cover what changes during it.

Launch checklist

• [ ] Two or three events chosen, each with what the agent should stop and start saying
• [ ] Callaro contact ID stored on every customer record that can receive events
• [ ] Event text written as one short fact in plain language, never a script
• [ ] Every type classified, with general reserved for facts anyone may hear
• [ ] Speak set only for what the customer is waiting on, one event per meaningful change
• [ ] Idempotency key taken from the source event ID
• [ ] Stale and out-of-order source events filtered before posting
• [ ] Payments through Callaro-created links not posted a second time
• [ ] One prompt rule per event type, and lookups reading the same source as the events
• [ ] Tested on a real call and a real chat, not the test panel
• [ ] Verification-gated agents tested with an account event before and after the check

Where to go next

Live events make an agent feel like part of your business, but only when they are few, short and classified. Pick the two moments where a stale agent hurts most, wire them, and test them on a real call this week. Orchestration shows how events sit alongside tools and cross-channel actions; integrations lists what you can connect.