# Kustomer hand-off callbacks

This server supplies formatted callbacks for Voiceflow's built-in Kustomer Handoff provider. It is not an alternative customer chat interface. Use Node.js 22.13+ with node:sqlite available, one worker process, a persistent private state volume and an HTTPS reverse proxy to the loopback listener. Keep this deployment single-replica; do not share the SQLite file between independent workers.

Set KUSTOMER_ORG, KUSTOMER_API_KEY, KUSTOMER_CALLBACK_SECRET, VF_HANDOFF_SECRET, KUSTOMER_HUMAN_IDS (comma-separated IDs of administrator-approved human teammates) and KUSTOMER_STATE_PATH (an absolute file path in a private persistent directory). The API key needs conversation/message read. VF_HANDOFF_SECRET matches secretKey in Voiceflow's Kustomer connection. KUSTOMER_CALLBACK_SECRET is a different random secret for Kustomer Workflows to this receiver. Run node start.mjs.

Expose only POST /kustomer/callbacks. Enforce a 64 KiB body limit, HTTPS, rate limits and server secret storage at the proxy. Configure a message Workflow matching direction out OR app voiceflow, including incoming seed records; configure a separate done-status-change Workflow restricted to conversation names starting with [Voiceflow]. Use that prefix in the native Handoff Title and retain it through resolution. Configure their REST steps to supply x-kustomer-callback-secret and JSON {"event":"message","conversationId":"..."} or {"event":"end","conversationId":"...","messageCount":12}. Do not use a raw outbound-webhook envelope. A 202 means durably queued, not delivered.

The worker re-reads the provider, verifies the conversation's Voiceflow-origin messages, follows up to five 100-message pages and forwards only public outbound message records authored by approved human users. It excludes voiceflow-origin and automated messages. Internal notes are not fetched. Origin-less unrelated conversations are ignored; ending jobs for [Voiceflow]-prefixed conversations retain their terminal intent and count while the seed is pending; the later Voiceflow seed must trigger a fresh reconciliation so an early human reply is not lost. It requires stable message counts at least as large as the closure event count, delivers any unsent qualifying messages before end, checks that the conversation remains resolved and deduplicates normal event replay in SQLite. Actor names are intentionally the fixed label Support teammate. It does not forward teammate attachments or synthesize a join event.

Monitor callbacks.pending() and redacted worker diagnostics. Jobs with provider failures, incomplete/changing history, unsupported history size, or refused Voiceflow callbacks remain pending for subsequent drain calls. Investigate persistent failures; do not delete state to force retry. Keep the normal support channel available. The receiver does not place a later callback outage on the Workflow's initial Failure path.

Delivery is at least once: a crash after Voiceflow accepts a reply but before SQLite records it can cause a duplicate on recovery, because the native callback has no idempotency key. Do not claim exactly-once delivery. Replays and rapid reply-then-resolution are covered by local tests; external account permissions, callback delivery and customer UI rendering still need sandbox acceptance. Keep the selected messages read-only in this service; it does not modify or resolve Kustomer records.
