Initiate Handoff
initiate_handoffBegin a handoff from the agent to either a human operator (SMS/email via lead_routing_json) or another agent (signed continuation URL). In human mode the notification body is composed by the server from the contact and reason fields — callers supply those fields, not the message text. Idempotent: re-using the same idempotency_key returns the original handoff.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"slug": "<slug>",
"mode": "<mode>",
"idempotency_key": "<idempotency_key>"
},
"name": "initiate_handoff"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | Handoff mode: human (SMS/email) or agent (continuation URL) | |
| slug | Yes | Business slug identifier | |
| reason | No | Why the user wants to reach a human | |
| message | No | Deprecated alias for `reason`. The notification body is composed by the server from the fields above; this value is delivered as the reason line, not as the message itself. Supplying both is an error. | |
| purpose | No | Purpose description for agent-mode continuation | |
| urgency | No | How time-sensitive (default: normal) | |
| agent_id | No | Optional agent identifier, 1 to 128 printable ASCII characters. In agent mode it binds replays of this handoff to you, and an id outside that range is refused (invalid_agent_id); in human mode such an id is not recorded. | |
| contact_name | No | End-user's name | |
| contact_email | No | End-user's email | |
| contact_phone | No | End-user's phone | |
| reservation_id | No | Optional link to a prior reservation | |
| idempotency_key | Yes | Unique key for idempotent handoff |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | Yes | The handoff's mode, and which of the fields below are present. Normally the mode you asked for — but an idempotent replay returns the STORED handoff's mode, which differs when an idempotency_key is reused with a different mode than the call that created it. | |
| reason | No | human mode, not delivered: 'form_routing_configured', 'no_recipient_configured', 'sms_consent_missing', a shape-mismatch skip, a spend-cap denial, or a provider failure code | |
| status | No | human mode replay while the original send is still in flight: 'pending' | |
| channel | No | human mode, skipped before sending: the channel that would have been used ('sms' or 'email'), or 'form' when the business only takes leads through a web form | |
| form_url | No | human mode, channel 'form': the business's own contact form for the user to complete | |
| delivered | No | human mode: present only as false, when nothing was sent — see reason | |
| ticket_id | No | human mode, delivered: the provider's message id, or the handoff_id when the provider issues none | |
| expires_at | No | agent mode: Unix seconds when continuation_url stops working (one hour) | |
| handoff_id | Yes | ||
| delivered_via | No | human mode: 'sms' or 'email' — the channel the notification went to | |
| handshake_token | No | agent mode: the bare token carried inside continuation_url | |
| continuation_url | No | agent mode: signed URL the next agent redeems exactly once at /a2a/continue | |
| idempotent_replay | No | Present and true when this idempotency_key already had a handoff; nothing was re-sent and no token was re-minted | |
| continuation_expired | No | agent mode replay: true when the stored continuation has already expired; it is never re-minted — start a new handoff |