Aircall
Phone connector that shows callers' orders and fundraisers to the agent, logs calls, and lets the AI Voice Agent answer order and fundraiser questions.
Aircall
The Aircall connector links the business phone line to the storefront's order and fundraiser data. It does three things:
-
While the phone rings, it looks the caller's number up and shows an insight card on the agent's Aircall phone: the customer's name and lifetime spend, their three most recent online orders (status, total, date, tracking number, fundraiser), and any fundraiser they coordinate. Every line links into the admin panel.
-
When the call ends, it adds a dated note to the matched customer's account timeline ("Inbound call, 3m 12s, answered by Mike") and leaves a summary comment on the call in Aircall's call history.
-
With no one on the line, Aircall's AI Voice Agent can tell a caller where their order is, or tell a fundraiser coordinator how their fundraiser is doing, once the caller has proved who they are. See Self-serve answers.
Callers with no record get no card, and their calls get no note.
| File | Responsibility |
|---|---|
lib/aircall/client.ts | Aircall API client: insight cards, call comments, ping |
lib/aircall/lookup.ts | Matches a phone number to customers, orders, fundraisers and fundraiser contacts |
lib/aircall/insight-card.ts | Builds the insight card and the call summary |
lib/aircall/webhook.ts | Payload schemas, token check, call description |
app/api/webhooks/aircall/route.ts | The webhook endpoint |
lib/aircall/voice-agent.ts | Caller verification and spoken answers for the AI Voice Agent |
lib/aircall/voice-agent-route.ts | Bearer auth, input parsing and rate limits shared by the voice agent actions |
app/api/integrations/aircall/order-status/route.ts | Voice agent action: order status |
app/api/integrations/aircall/fundraiser-status/route.ts | Voice agent action: fundraiser status |
Setup
- In Aircall, go to Integrations & API → API Keys and create a key. Set
AIRCALL_API_IDandAIRCALL_API_TOKENin Vercel. - Go to Integrations & API → Webhooks and add a webhook pointing at
https://www.josemadridsalsa.com/api/webhooks/aircallwith the eventscall.createdandcall.ended. Copy the webhook's token intoAIRCALL_WEBHOOK_TOKEN. - Redeploy, then check Admin → Settings → Integrations: Aircall should read healthy.
Without AIRCALL_WEBHOOK_TOKEN the endpoint refuses every event (503). Without the API
key and ID the webhook still records ended calls on customer timelines but cannot show
insight cards or comment on calls.
How callers are matched
The caller's US number (ten digits, or eleven starting with 1) is matched against:
| Record | Field |
|---|---|
| Customer | Customer.phone |
| Online orders | Order.guestPhone, the shipping or billing address phone, the account holder's User.phone, and the matched customer's own orders (their linked account, or their email as guest or account email) |
| Fundraisers | Fundraiser.contactPhone |
| Past fundraiser groups | FundraiserContact.phone |
Phone numbers are stored as they were typed, and the lookup runs through Prisma, so it
matches the common US spellings of the number (7405551234, +17405551234,
(740) 555-1234, 740-555-1234, 740.555.1234 and similar). A number stored in an
unusual format won't match. Only US numbers (10 digits, or 11 starting with 1) are looked up; international callers are never matched, so their last ten digits can't be mistaken for a US customer's.
Webhook behaviour
| Event | Effect |
|---|---|
call.created (inbound) | Insight card for a known caller. Outbound calls are skipped. A failed card is logged and acknowledged, because a retry would arrive after the phone stops ringing. |
call.ended | Customer timeline note + Aircall comment. The note and a WebhookEvent row whose primary key is aircall:call.ended:<callId> are written in one transaction, so a retried or concurrent duplicate delivery hits the key and is skipped, and a failed write leaves nothing behind (500, Aircall retries). A failed Aircall comment is only logged. |
| anything else | Acknowledged and ignored |
Aircall webhooks have no signature header. Each event carries the webhook's secret
token in its JSON body, and the route compares it to AIRCALL_WEBHOOK_TOKEN in
constant time.
Self-serve answers (AI Voice Agent)
Aircall's AI Voice Agent (an Aircall add-on) can call our API in the middle of a call through
custom actions. Two actions are available. Both accept GET or POST, read their inputs
from the query string or a JSON body, and need Authorization: Bearer <AIRCALL_VOICE_AGENT_TOKEN>.
| Action | Endpoint | Caller must give | The agent can say |
|---|---|---|---|
| Order status | /api/integrations/aircall/order-status | order_number and phone (a number recorded on the order) | Status, order date, ship date and carrier, delivery estimate or date, last four of the tracking number, items, fundraiser supported |
| Fundraiser status | /api/integrations/aircall/fundraiser-status | phone (the fundraiser's coordinator phone) and group_name | Status, start and end dates, order count, total sold, the group's earnings, goal |
What keeps it private
- Two facts, like the web order tracker. An order is only described when the phone given
matches a phone on that order (guest phone, account phone, shipping or billing phone). A
fundraiser is only described when the phone is its
contactPhoneand the group name shares a distinctive word with the fundraiser's name or organization (generic words like "school", "high" or "boosters" don't count). - One answer for every miss. Wrong order number, wrong phone and no record all return the
same
not_foundanswer, so the line can't be used to discover orders or numbers. - Rate limited: 10 tries an hour per phone, and for orders also per order number. The fundraiser lookup only searches the spoken phone's fundraisers, so its phone limit covers the record. Aircall calls from its own servers, so there is no per-IP limit.
- Nothing sensitive is spoken. Answers carry no address, email, payment method or full tracking number.
- Only US phone numbers are accepted.
Order numbers
Callers say order numbers in whatever form they have. A bare number such as 12345 is
tried as BC-12345 (main store) and BCF-12345 (fundraising store), and missing dashes are
restored (ORD2026110042 → ORD-202611-0042). The phone check picks the right order when
both stores have the same number.
Responses
Lookups answer 200 with JSON so the agent can always speak a result; Aircall treats any
other status as a broken action.
{ "found": true, "order_number": "BC-12345", "status": "shipped", "summary": "Order BC-12345, placed Tuesday, November 10, is shipped. ..." }
{ "found": false, "reason": "not_found", "summary": "I couldn't find a match for those details. ..." }reason is not_found, invalid_input or rate_limited. Every answer has a summary
sentence the agent can read as is. A missing or wrong bearer is 401, an unset
AIRCALL_VOICE_AGENT_TOKEN is 503, and a database failure is 500.
Fundraisers mirrored from the BigCommerce fundraising store often have no contactPhone, so
their coordinators can't use the fundraiser action until a phone is added in the admin.
Setup
- Generate a long random secret (for example
openssl rand -hex 32) and set it asAIRCALL_VOICE_AGENT_TOKENin Vercel (storefront project, Production). Redeploy. - In the Aircall dashboard, open AI Voice Agents → Custom capabilities, add an authentication method of type Bearer Token, and paste the same secret.
- Add a custom action Get order status: method
POST, URLhttps://www.josemadridsalsa.com/api/integrations/aircall/order-status, the bearer authentication above, and body{"order_number": "{{order_number}}", "phone": "{{phone}}"}. Add the parametersorder_numberandphone(both required). Map the outputsfound,reasonandsummary(JSONPathfound,reason,summary). - Add Get fundraiser status the same way with URL
.../api/integrations/aircall/fundraiser-status, body{"group_name": "{{group_name}}", "phone": "{{phone}}"}and parametersgroup_nameandphone. - In the agent's guidelines, tell it to collect those details before calling the action, to
read
summaryback to the caller, and to offer a transfer to the team whenfoundis false. Use Test call on each action with a real order before turning it on for the main line.
How is this guide?
Last updated on