redeem

Exchange a nonce for a chat handle. Single use: the nonce is consumed even if a later step fails. Ends the call through end_call when the nonce was registered with a call ID and end_call is configured, waits for capture_leg to confirm the voice leg’s record, and only then issues a handle for a new leg of the same conversation via the gateway’s mint_handle(). This is what POST /handoff calls.

Parameters

Returns

str | None — The signed handle, or None for an unknown, expired, or already-redeemed nonce. The three cases are deliberately indistinguishable.

Example

handle = await handoff.redeem(nonce)
if handle is None:
    return {"error": "not found"}, 404
return {"handle": handle}

See HandoffRouter for the route this backs.