# Live agent handoff learning server

Read the [connection guide](https://www.voiceflow.com/docs/developers/handoff/connect).

Node.js 22+, no installed packages. Download all four `.mjs` files into one folder.
Run `node --test test.mjs` for local contract tests.

Set these environment variables outside source control:

- `HANDOFF_TOKEN`: secret for Voiceflow requests (`Authorization: Bearer ...`).
- `EVENT_TOKEN`: a different secret for trusted normalized events.
- `WEBHOOK_SECRET`: random secret of at least 32 characters, matching Voiceflow.
- `VOICEFLOW_PROJECT_ID`: the only project this example accepts.
- `VOICEFLOW_WEBHOOK_URL`: your runtime's `/handoff/webhook/custom` endpoint.
- `PROVIDER`: `mock` (default) or `chatwoot`.

Run `node server.mjs`. It listens on localhost:8787; use an HTTPS reverse proxy
for a Voiceflow test. Mock mode creates no external support conversations.

For Chatwoot, set `CHATWOOT_URL`, `CHATWOOT_ACCOUNT_ID`, `CHATWOOT_TOKEN`,
`CHATWOOT_INBOX_ID`, `CHATWOOT_CONTACT_ID`, and `CHATWOOT_SOURCE_ID`. The fixed
contact must belong to the API inbox. Set `CHATWOOT_WEBHOOK_SECRET` and register a signed account webhook at
`/provider-events` for `message_created` and `conversation_status_changed`.
The pilot verifies the raw-body signature and relays public outgoing human-user replies and
resolution; AgentBot, Captain assistant and unknown sender types are excluded. Initial
escalation context is a private note. Customer lookup is not implemented: the pilot uses one fixed contact.
Other providers implement their own authenticated receiver and normalize public
human events before calling `/events` with the separate event token.
The provider integration manuals describe their translation work. Read the
[complete Chatwoot manual](https://www.voiceflow.com/docs/guides/integrations/chatwoot/overview#live-agent)
for contact-inbox mapping, account webhook registration and end-to-end checks.

## Provider hooks

- `create(request, connectionId)` returns the provider conversation ID.
- `message(providerConversationId, message)` forwards a customer message.
- `end(providerConversationId)` closes the conversation.
- Optional `files: true` declares implemented file transfer; otherwise files
  receive an explicit 422 response.

Use `createHandoffServer` from `server.mjs` to inject your implementation.
It stores the remote ID and handles Voiceflow-facing routes and event signing.

## Scope

This is a one-process, text-first teaching example. State is in memory. Restarting
loses it. A lost response after a successful provider operation can produce an
ambiguous result; reconcile with provider state before retrying in production.
Do not deploy this unchanged to customer traffic. Production needs durable,
tenant-scoped mappings, atomic idempotency, a durable event outbox, authenticated
provider receivers, retention, timeout reconciliation and monitoring.

Tests use fixtures, not authenticated vendor accounts. They verify the Voiceflow
wire contract, auth rejection, message/event deduplication during one process,
callback retries and Chatwoot request mapping. They do not certify a deployed
integration or vendor account permissions.
