Welcome to the Jose Madrid Salsa developer docs — explore features, APIs, and deployment guides.
Jose Madrid SalsaJMS Docs

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:

  1. 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.

  2. 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.

  3. 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.

FileResponsibility
lib/aircall/client.tsAircall API client: insight cards, call comments, ping
lib/aircall/lookup.tsMatches a phone number to customers, orders, fundraisers and fundraiser contacts
lib/aircall/insight-card.tsBuilds the insight card and the call summary
lib/aircall/webhook.tsPayload schemas, token check, call description
app/api/webhooks/aircall/route.tsThe webhook endpoint
lib/aircall/voice-agent.tsCaller verification and spoken answers for the AI Voice Agent
lib/aircall/voice-agent-route.tsBearer auth, input parsing and rate limits shared by the voice agent actions
app/api/integrations/aircall/order-status/route.tsVoice agent action: order status
app/api/integrations/aircall/fundraiser-status/route.tsVoice agent action: fundraiser status

Setup

  1. In Aircall, go to Integrations & API → API Keys and create a key. Set AIRCALL_API_ID and AIRCALL_API_TOKEN in Vercel.
  2. Go to Integrations & API → Webhooks and add a webhook pointing at https://www.josemadridsalsa.com/api/webhooks/aircall with the events call.created and call.ended. Copy the webhook's token into AIRCALL_WEBHOOK_TOKEN.
  3. 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:

RecordField
CustomerCustomer.phone
Online ordersOrder.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)
FundraisersFundraiser.contactPhone
Past fundraiser groupsFundraiserContact.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

EventEffect
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.endedCustomer 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 elseAcknowledged 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>.

ActionEndpointCaller must giveThe agent can say
Order status/api/integrations/aircall/order-statusorder_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-statusphone (the fundraiser's coordinator phone) and group_nameStatus, 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 contactPhone and 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_found answer, 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

  1. Generate a long random secret (for example openssl rand -hex 32) and set it as AIRCALL_VOICE_AGENT_TOKEN in Vercel (storefront project, Production). Redeploy.
  2. In the Aircall dashboard, open AI Voice Agents → Custom capabilities, add an authentication method of type Bearer Token, and paste the same secret.
  3. Add a custom action Get order status: method POST, URL https://www.josemadridsalsa.com/api/integrations/aircall/order-status, the bearer authentication above, and body {"order_number": "{{order_number}}", "phone": "{{phone}}"}. Add the parameters order_number and phone (both required). Map the outputs found, reason and summary (JSONPath found, reason, summary).
  4. Add Get fundraiser status the same way with URL .../api/integrations/aircall/fundraiser-status, body {"group_name": "{{group_name}}", "phone": "{{phone}}"} and parameters group_name and phone.
  5. In the agent's guidelines, tell it to collect those details before calling the action, to read summary back to the caller, and to offer a transfer to the team when found is false. Use Test call on each action with a real order before turning it on for the main line.

How is this guide?

Edit on GitHub

Last updated on

On this page