Wiring a voice agent to a calendar and a CRM
The default behaviour of most voice platforms is to keep their own record of every caller, and that is how you end up with a third customer list nobody trusts. A voice agent should own almost no data. It should read availability at the moment it speaks, write to your systems while the caller is still on the line, and hold nothing that outlives the call except a log of what it did. Everything below follows from that one rule.
Which system holds the truth?
Decide this before any connector is configured, and write it down as a single sentence per data type. The calendar owns availability and appointments. The CRM owns people, companies and the history of contact. The voice platform owns transcripts, recordings and call metadata, because those are genuinely its own artefacts. Nothing else belongs to it.
The failure this prevents is subtle and expensive. Once the voice platform keeps its own contact list, two records exist for the same person and they diverge on the first correction. Someone updates a mobile number in the CRM, the agent keeps ringing the old one, and the discrepancy is discovered by a customer rather than by you.
The test is a question you can ask in a meeting: if the CRM and the voice platform disagree about a caller's phone number, which one is wrong? If the answer is anything other than an immediate the voice platform, you have two sources of truth and the argument has already started.
Write the same sentence for outbound facts, because that is the half people forget. If the agent quotes prices, opening hours or service coverage, those facts need one home that a human updates and the agent reads. A price held in the agent's prompt is a second source of truth wearing a different hat, and it will disagree with your website within a quarter. Prompts should carry behaviour, not business facts.
How should booking actually work?
Read availability live, at the moment the agent is about to speak the options, and never from a cached copy refreshed on a schedule. A five minute old cache is enough to offer a slot that a walk-in customer took two minutes ago, and the caller finds out by receiving a cancellation later. If the calendar API is too slow to query live, that is a latency problem to solve, not a reason to cache.
Then write before you confirm. The order matters: offer the slot, get agreement, write the booking, read back the confirmed detail from the response. An agent that says that is booked for Tuesday at ten and then attempts the write has already committed you to something that may fail. Confirming from the write response also catches the case where the calendar accepted a different time than requested.
Two mechanisms prevent double booking. A short hold or provisional block placed the moment the caller expresses interest, released automatically if the call ends without confirmation. And an idempotency key on the write, so a network retry does not create a second appointment. Ask any vendor about both; the answers separate the platforms that have handled real volume from the ones that have not.
What goes wrong when the agent keeps its own copy?
Duplicates, first, and they arrive faster than you expect. The agent creates a contact for every caller because it cannot reliably match, and within a month your CRM has three entries for a regular customer whose number was entered differently by three systems. Deduplication after the fact is manual work nobody schedules.
Then stale state. Anything the agent caches becomes wrong the moment a human changes it in the real system: opening hours, prices, service coverage, staff availability. Cached business facts are the most common source of a confidently wrong answer, because the agent is not hallucinating, it is faithfully reporting something that was true last week.
The third is the one that damages trust internally. When the voice platform holds its own copy, reporting disagrees. Your CRM says forty enquiries, the voice dashboard says fifty-two, and nobody can reconcile them, so both numbers stop being used. One source of truth is a reporting decision as much as a data one.
| Data item | Where it should live | What the agent may hold | Failure if duplicated |
|---|---|---|---|
| Appointment slots | Calendar | Nothing, read live per call | Double booking, then a cancellation call |
| Contact details | CRM | The number for this call only | Diverging records, wrong number dialled |
| Opening hours and prices | One published source | A reference fetched at call time | Confidently wrong answers to callers |
| Call transcript and audio | Voice platform | All of it, this is its own data | None, but retention still applies |
| Enquiry or lead | CRM | An idempotency key while writing | Two leads, two people calling back |
| Service coverage rules | One published source | A fetched reference | Quoting for work you do not cover |
How should the caller be matched to an existing record?
Start with the calling number, normalised to a single international format before any lookup. Numbers stored inconsistently are the reason matching fails: the same mobile written with a leading zero, a country code, spaces or brackets will not match itself. Normalise on the way in and on the way out.
When the number matches exactly one record, use it and say something that proves recognition without asserting identity: I have your details from last time, can I check the name on the account. When it matches more than one, or matches a household or an office switchboard, ask rather than guess. When it matches none, capture what you need and create the record with a source field marking it as created by the agent, so you can audit later.
Never let the agent merge records, and never let it overwrite a field a human has filled in. Appending a note is safe; changing an address on the strength of a misheard postcode is not. Write access should be additive by default, with updates restricted to fields the agent is explicitly allowed to own.
What happens when a write fails mid-call?
The caller has to be told the truth, immediately, in the same breath the agent would have used to confirm. Something like: I am not able to complete that booking right now, so I will take your details and someone will confirm within the hour. What must not happen is a cheerful confirmation followed by a silent failure, because the caller now believes they have an appointment and you find out when they arrive.
Behind the scenes, the failed write should land in a queue a human sees within minutes, not a log file. Include the transcript, the intended action and the error. This is where most integrations are weakest: the happy path is well tested and the failure path writes to somewhere nobody watches.
Retries need care. Retrying a read is free; retrying a write without an idempotency key creates duplicates. If your CRM or calendar does not support idempotency keys, the safer pattern is to fail once, tell the caller, and let a human complete it, rather than to retry and hope.
What should you build first?
Read-only, in both directions, for a fortnight. Let the agent read availability and read the caller's record, and let it write nothing except a call log with a transcript. You will learn more from two weeks of that than from any amount of design: which questions callers actually ask, how often matching succeeds, and how frequently the calendar answer would have been wrong.
Add writes one at a time, starting with the lowest-consequence one. Logging a call comes first, then creating an enquiry, then booking into a single named calendar, then rescheduling. Rescheduling and cancellation last, because they can destroy an existing commitment and they are where a misheard name does the most harm.
Then run the test that catches the real problem: change something in your CRM by hand, and see how long the agent keeps telling callers the old answer. If the answer is longer than the length of one call, something is cached that should not be.
Then run the same test on the calendar. Have a colleague move a booking by hand and see whether the agent still offers that slot to the next caller. Both tests ask the same question: does the agent find out about changes made outside it. The usual reason a voice agent starts giving wrong answers three months in is that nobody ever checked which direction the information flows.
Common questions
- Can an AI receptionist book directly into our calendar?
- Yes, and it should read availability live at the moment it offers a slot rather than from a cache. A cache even a few minutes old can offer a slot someone else has taken. The safe order is offer, get agreement, write the booking, then confirm from the write response, so the caller is never told something is booked before it is.
- How do you stop a voice agent double booking?
- Two mechanisms. A short provisional hold placed the moment the caller expresses interest in a slot, released automatically if the call ends without confirmation. And an idempotency key on the write, so a network retry cannot create a second appointment. Ask a vendor about both; the answers show whether the platform has handled real volume.
- Will an AI receptionist create duplicate CRM records?
- It will, unless matching is deliberate. Normalise the calling number to one international format before any lookup, because the same mobile stored with a leading zero or a country code will not match itself. Match on exactly one record or ask the caller; never guess, never merge, and never let the agent overwrite a field a human filled in.
- Should the voice platform keep its own customer list?
- No. It should own transcripts, recordings and call metadata, which are genuinely its own, and nothing else. Once it holds contacts, two records exist for the same person and they diverge at the first correction, usually discovered by a customer rather than by you. Reporting diverges too, and then both sets of numbers stop being trusted.
- What should happen if the booking fails while the caller is on the line?
- The agent should say so plainly and offer a specific commitment instead: take the details and confirm within a named period. A cheerful confirmation followed by a silent failure means the caller believes they have an appointment and you discover it when they arrive. The failed write belongs in a queue a person checks within minutes, with the transcript attached.
- Which integration should we build first?
- Read-only for a fortnight: let the agent read availability and caller records, and write nothing but a call log. Then add writes in order of consequence, starting with logging a call, then creating an enquiry, then booking, and leaving rescheduling and cancellation until last because they can destroy an existing commitment.
