Questa pagina è pubblicata in inglese e in ucraino; qui sotto c’è la versione inglese.

Sending requests to your CRM or inbox

For developers, in code: posting every contact a visitor leaves to your own endpoint — a POST tool as the delivery endpoint, the {{handoff.*}} placeholders, what is recorded, and what the demo inbox shows.

When a visitor leaves a contact — through the in-chat form or by asking for a person — the lead is saved in the panel’s Requests screen and mailed to the site’s support address. Delivery adds a third destination: your own endpoint, a CRM, a help desk, a spreadsheet, called the moment the lead arrives.

Delivery is part of the Growth plan and above.

In the panel: Agent → Escalation → Send each request to your system (Agent).

Set it up

Create a custom tool with method POST, your endpoint’s URL, your token as a secret in a header, and a body template with the lead’s fields:

POST https://crm.example.com/leads
Authorization: Token {{secret.crm}}
Content-Type: application/json

{ "email": "{{handoff.contact}}", "kind": "{{handoff.contact_kind}}",
  "question": "{{handoff.question}}", "comment": "{{handoff.comment}}",
  "page": "{{handoff.page}}", "language": "{{handoff.language}}",
  "source": "{{handoff.source}}", "ref": "{{handoff.ref}}", "id": "{{handoff.id}}" }

On the agent’s Escalation card, pick it under Send each request to your system.

The tool is taken out of the model’s tools: delivery is the system’s job on the handoff path, not something the assistant decides in a conversation.

The placeholders

Placeholder	Value
`{{handoff.contact}}`	the contact the visitor left, decrypted for this call
`{{handoff.contact_kind}}`	`email` or `phone`, detected
`{{handoff.question}}`	the question that led to the request
`{{handoff.comment}}`	the visitor’s comment, if any
`{{handoff.page}}`	the page the request was made on
`{{handoff.language}}`	the conversation’s language
`{{handoff.source}}`	`agent` (the assistant gave up), `asked` (the visitor asked), `menu` (the Contact us button)
`{{handoff.ref}}`	a reference you can quote back; never the conversation id
`{{handoff.id}}`	the request’s id in the panel

Percent-encoded when they land in the URL; raw in headers and the body; control characters stripped. {{user}} and {{screen.*}} are empty on this path — the lead may arrive long after the conversation. One substitution pass: a visitor’s comment can never expand into your secret.

How the call runs

In the background, on its own session, after the visitor’s request has been answered — your endpoint may take the full ten seconds and nobody is kept waiting. No cache, no retry. The same egress policy as every tool: https, public host, no redirects.

What is recorded

`delivery_status`	When
`off`	no delivery tool is set — almost every lead
`sent`	your endpoint answered 2xx
`failed`	anything else: the egress policy refused the host, the call timed out, a non-2xx status, the tool was disabled or belongs to another site, the plan does not include delivery

A short delivery_error names the reason — the status, never your response body. The Requests screen shows a warning on a failed row, and the contact is still there: a rotated token turns every lead into a silent 401 at your end, and this is what makes that visible.

Try it

The runtime ships a mock inbox for exactly this: POST /_demo/leads accepts a lead with a bearer token and 401s without one, and GET /_demo/leads reads them back. It is off by default (DEMO_ENDPOINTS_ENABLED) because it holds real leads with plain contacts; on a development stack, manage.py seed_handoff_demo wires a lead_delivery tool at it so the sent and failed paths can both be watched.