create_session
Create a new phone verification session. Returns deep_link, qr_code (base64 PNG), and qr_text (UTF-8 text QR for terminal display). Sessions provide a hosted verification flow with callbacks.
Agent usage: After creating a session, pass the response's deep_link to render_auth_link so the user can open or scan it. Never hand qr_text to a link renderer — it is that link already rendered as QR art. Print it verbatim inside a fenced code block only when a real terminal needs the QR. On sms the person texts a short code from the number being proven, as in SMS login: deep_link is an sms: link to our default number with the message pre-filled, so render it the same way, and also show sms_message (what they send) with the numbers in sms_dids (one per region, each with its own QR), because a person reading on a computer texts from their phone. They get no reply SMS. An SMS proof can still be revoked about a minute after the session completes, if the delayed spoof check finds the sender was not a real mobile line, so before relying on it check it with validate_proof. Then use wait_for_session to poll until the session reaches a terminal state (verified, failed, or expired).
The user does not see tool results — most clients fold them away, render_auth_link's output included. Before you wait or poll, put what the user must act on into your own reply text: the link itself (not a sentence announcing it), the SMS text and number, or a note to check their inbox.
ACCESS: needs a Proof account. Authenticate this client (Claude Code: /mcp → Authenticate), then call this tool again. start_login does NOT open this tool.
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": {
"channel": "<channel>"
},
"name": "create_session"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| channel | Yes | How the person proves the number: telegram or whatsapp (the bot reads it from their account) or sms (they text a short code from it). No phone number is sent | |
| context | No | ||
| profile_id | No | Sub-account whose name and templates the bot uses; omitted: the key's sub-account, else the primary | |
| client_metadata | No | Your own key-value data, stored with the session |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Session id | |
| status | No | ||
| channel | No | How the person proves the number: `telegram` or `whatsapp` (the bot reads the number from their account), or `sms` (they text a short code from the number to one of ours). | |
| qr_code | No | Base64-encoded PNG QR code for `deep_link` | |
| qr_text | No | UTF-8 text QR for `deep_link`, for terminal/agent rendering | |
| sms_code | No | The short code the person texts (`sms` only) | |
| sms_dids | No | Every number an `sms` session's code can be texted to, one per configured region (a region with no number is absent), each with its own QR code. `deep_link` uses the default region's number; the request comes from your server, so nothing in it says where the person is. | |
| deep_link | No | Opens the messenger (`https://t.me/…`, `https://wa.me/…`) or the messaging app (`sms:<number>?body=…`) with what the person sends | |
| expires_at | No | ||
| sms_message | No | The message to send, as pre-filled in the links (`sms` only) | |
| instructions | No | One line telling the person what to do |