Support callbacks: "Request a callback"

A customer asks to be called back from the portal, the chat widget, or your own backend through the API. The request lands on a ticket, so the desk sees it, and carries a promised time that the project's hours honour. This discharges ledger rows D207 and D211's route half: Tier 3 is back on the portal and in the Slip.

• Server: apps/api/src/support/callbacks/
• Table: support_callbacks (migration 0238)
• Types: packages/types/src/support-callbacks.ts

1. Turning it onCopy Anchor Link

A project offers callbacks when voice_enabled OR callback_enabled is true. callback_enabled (0238) turns callbacks on with browser calling off. A sandbox project may turn it on to exercise the integration (see §5). With both off, every surface shows nothing and the routes answer 409 callbacks_off.

2. The window and the promiseCopy Anchor Link

Every time a customer sees comes from the server, worked out on the project's own clock: the SlaClock from resolveSlaClock, the same one behind the ticket SLA and the chat's "we'll reply by".

GET …/callbacks/options returns {enabled, prefillE164, open, nextOpenAt, timezone, asapBy, slots[≤12], live}. The form renders from it alone. Times are shown in the customer's own timezone.

SLA. promisedBy feeds the ticket's first-response deadline: sla_first_due_at becomes the earlier of the two while nobody has replied. An answered callback sets first_replied_at, because a phone call is a reply.

3. The doorsCopy Anchor Link

Refusals, in this order, before anything is written (a refused request costs no ticket number):

1. 409 callbacks_off: the project offers no callbacks.
2. 403 customer_inactive: the customer is blocked or deactivated, or the grant on this project is blocked or missing.
3. The customer already has a live callback on this project. That one is returned (200), not a second. This is the dedupe every door meets, enforced by a unique index.
4. 429 daily_cap: 5 requests per customer per project in 24 h, counted across every door.
5. 422 slot_unavailable: the window, per §2.

A live key never reaches a sandbox callback (read, cancel or list): 404, as for an unknown id. A pinned API key naming another project gets 404, the same answer as an unknown id, so a pin is never an existence oracle.

The ticket. ticketId (portal and API) attaches the callback to the customer's own case. Someone else's case gets a 404. In the widget, the chat's existing case is reused. Otherwise a case "Callback requested" is opened through the one creation family (createFromPortal / createFromChat / createFromApi).

4. Dispatch: who actually dialsCopy Anchor Link

Decided server-side per request and stored as dispatch:

The contact centre's caps hold too ([review]): under one per-number lock, a number already live on the L1 queue, a number with 3 live callbacks in the workspace, or a queue whose daily cap is spent is not booked again. The callback stays manual, so a typed number (many customers, one victim) is never dialled past the operator's limits.

The number policy is the operator's. The contact-centre default is ani_only: call back only a number that called in. A typed number has no inbound call, so on such a queue the callback stays manual instead of overriding the operator. Set the L1 queue to same_country or any to let Gauge dial typed numbers.

The seam. VoiceModule does not export CallbacksService. The support pillar's @Global SupportCallbackVoiceSeam is bound at boot by voice/callbacks/support-callback-port.ts (the D198 seam, run in reverse). With no voice pillar the seam is empty, and every callback is manual.

5. The deskCopy Anchor Link

A case shows its callbacks above its history. The queue shows the project's waiting callbacks above the rack, soonest promise first, with "Overdue" in words as well as in red.

• Call now (voice only): the row becomes the agent's personal callback, and the shipped personal ring dials them first. If the agent isn't routable, the refusal says to call from their phone.
• Call from your phone (manual only): a tel: link.
• Record what happened: answered · no answer · busy · voicemail · wrong number, plus an optional note (≤ 500). Retry policy: answered → completed. Wrong number → failed. A miss → the next try 30 open minutes later, up to 3 tries, then failed. Recording by hand on a voice row cancels the idle voice row, and the callback continues as manual. A call that is ringing right now can't be overwritten (409 in_progress).
• Cancel: by the customer, an agent or the API. Any of them cancels the voice row too.

5a. Events and webhooksCopy Anchor Link

support.callback.requested · .scheduled (a chosen slot, or a retry) · .completed · .failed · .cancelled. They carry ids only: {version, callbackId, projectId, customerId, ticketId}. Never the number, the reason or a note. They are written to the outbox in the same transaction, published in the OpenAPI webhooks block, and audience members. Read the callback itself with GET /v1/support/callbacks/{callbackId}.

6. PrivacyCopy Anchor Link

e164, reason and outcome_note are REST-only and never logged. CustomerErasureService deletes the customer's callbacks, and the contact-centre rows they booked, except one whose call is ringing at that moment. The customer FK cascades as well. The PII census lists every text column.

7. BundlesCopy Anchor Link

The widget arm is a lazy, SRI-pinned chunk, support/callback.js (10.2 KB gz, budget 15 KB). The base is 30.9 KB gz (budget 50, +0.9 KB for the strings, the loader and the type roles). size.mjs fails the build if the chunk is inlined. That guard was proven by inlining the chunk.

8. What this does not do (recorded, not hidden)Copy Anchor Link

• The overflow chain's callback arm OFFERS; it never books. When a browser call's queue overflows on a queue configured callback (or voicemail, which degrades to it), and SupportCallbacksService.options says this customer could book (project offers callbacks, customer active and granted), overflow records callback, opens the call's ticket, and closes the room. The caller's status read then carries callbackOffer: { ticketId }: the portal shows "Nobody could take your call this time. We can call you back instead." with its Tier 3 arm booking against that ticket, and the widget call slip opens the callback form for it. The booking goes through the normal door (edge limit, daily cap, one live callback, sandbox dispatch). Nothing is ever dialled on overflow's say-so: the caller confirms the number. Phone (PSTN) callers and anonymous widget visitors have no customer row, so they get no offer and the chain degrades as before. /chat?embed=1 shows the sentence without a key; the native app books through /v1 (mobile.md), and the support.voice.abandoned event names the action taken.
• Browser calls are separate from callbacks. In-app calls (portal, /chat?embed=1, the widget's own call key) are LiveKit rooms and need nothing from Twilio (docs/ops/support-embed.md §5). Callbacks are the PSTN path and stay on Twilio. The widget Slip shows both when the project has both on.
• Desk reads follow the ticket's data scope (S5). An own/team-scoped agent sees and works a callback only when its ticket passes the support-tickets scope predicate (ticket-scope.ts): the list and every :id route, 404 otherwise. There is still no per-project membership, matching GET /support/tickets.