phone_number claim in E.164 format, next to
phone_number_verified.
When Veriqa asks for the number
Veriqa asks only when your application needs the number and the channel has not already given it. The need is the requirement level of thephone_number claim:
A requirement counts only when the sign-in asks for the
phone scope. With a Required number the
sign-in page offers only the channels able to provide one; if none is left, /connect/authorize
answers 400 no_channel_for_required_phone (troubleshooting).
The request comes once the user has confirmed the sign-in — in the chat or with “Yes” on the
confirmation page in the browser. The bot sends it to the chat the user signed in from: a short text,
a button that shares the number and a second button whose meaning depends on the level. The texts
are shown in the user’s language.
The text of the request is a message whose kind
follows the level: phone-number-request for an Optional number, phone-number-request-required
for a Required one. For either the product ships Share your phone number — and a wording of its
own for Instagram and for Messenger — and you may reword it for a tenant,
for one application or for one channel — the last at
Veriqa:MessageTemplates:{kind}:BySurface:in-channel:ByChannel:{channel}:Templates.
The labels of the buttons are not part of that message: they are localizable strings, translated
through the locale files.
A wording stated for one kind does not apply to the other. If you reworded
phone-number-request and ask for a Required number, state your wording under
phone-number-request-required as well — otherwise the user gets the shipped text of that kind.
The window is 60 seconds by default. Change it with
Veriqa:ClaimCompletion:PhoneOptionalWindow, or
for one application with the ClaimCompletionPhoneOptionalWindow member of its client entry (see
keys in the declaration catalog). The
window never runs past the transaction: the step is skipped at least 5 seconds before the
transaction expires.
When the shared number completes the sign-in, the chat shows the usual receipt of a confirmed
sign-in; Cancel sign-in shows the receipt of a declined one.
What your application receives
phone_number— in E.164:+and digits. A number a channel hands over in any other form counts as absent: it is not issued, and the step waits as if the user had not answered.phone_number_verified— a JSON boolean:trueonly when the channel proves that the number belongs to the user who sent it, otherwisefalse.- Both claims go out only under a granted
phonescope.
Channel by channel
The “Who” column shows whose code gets the number: Veriqa’s channel adapter, or your own integration with the platform. Channels whose adapter is not shipped yet show what the platform’s API allows.Telegram
The bot sends a reply keyboard: the share button on top, the second button below it; the keyboard hides after a tap, and the message that reports the outcome of the sign-in removes it for good. A sign-in that expires with the request still waiting is reported as a new message for the same reason: only a new message removes the keyboard. Veriqa accepts only the user’s own contact: theuser_id of the contact must be
the sender, and a forwarded contact or a card from the address book is rejected.
Telegram’s website login (Log In With Telegram) can
return the phone number as well — that is your own integration with Telegram, outside Veriqa.
MAX
The bot sends the share button and a callback button with the second action. The number is taken fromvcf_info only when the contact’s hash signature matches — computed with the bot token of the
tenant that received the contact. When the sign-in ends — confirmed, declined, failed or expired —
the buttons are removed from the request message, and the outcome arrives as a new message below it.
The bot asks for the number in both update modes, Webhook and Polling.
phone_number with
phone_number_verified: true, and nothing is asked.
A user who has turned on a WhatsApp username may hide the number, and their messages come without
it. When your application asks for the number of such a user, the request is sent, addressed by the
BSUID: the request_contact_info interactive message, followed by a separate message with the second
button — the request carries no buttons of its own. A contact card the user sends manually
(origin = other) is rejected. The shipped Meta Cloud API provider sends the request, the Twilio
provider does not; a WhatsApp provider of your own (IWhatsAppProvider) sends it only if it
implements SendContactRequestAsync — otherwise the request is not delivered and the step waits as
it does with no answer.
phone_number with phone_number_verified: false. A number the user types into the
chat is not accepted — only the one the button sends.
Because of that the product words the request for Instagram itself, telling the user what to do
without a number in the profile:
A wording of yours at the same address replaces the shipped one; keep the hint in it.
Messenger
The Page sends the same message as an Instagram account does: the text of the request with two quick-reply buttons under it — the one Messenger draws, which shares the phone number of the user’s profile, and the one for the second action of the step. Messenger does not say that it has checked the number, so the token carriesphone_number with phone_number_verified: false. A number the
user types into the chat is not accepted — only the one the button sends.
The product words the request for Messenger itself, with the same two texts as for
Instagram: the one for an Optional number at
phone-number-request:BySurface:in-channel:ByChannel:messenger, the one for a Required number at
phone-number-request-required:BySurface:in-channel:ByChannel:messenger. A wording of yours at the
same address replaces the shipped one; keep the hint in it.
Viber
The bot sends the text of the request with two buttons under it: theshare-phone button of the
platform, which shares the phone number of the user’s Viber account, and the button for the second
action of the step. The number arrives as a contact message. Viber does not say whether a contact
came from that button or was picked from the address book, and it does not state that the number
belongs to the sender — so the token carries phone_number with phone_number_verified: false,
and the channel never rejects a contact as somebody else’s. A number the user types into the chat
is not accepted — only a contact is.
The share-phone button needs a Viber client with API level 3 or later; the request message
tells the platform so, and an older client does not get it. The step has not been run against the
live platform — see Viber.
A channel connected over HTTP
A channel whose adapter is an external service gives the number in the same two ways, and its registration says which — withHttp:Capabilities:PhoneNumber:
- on request (
OnRequest) — Veriqa sends your adapter the request with the captions of both buttons; the adapter shows them the way its platform does and posts the shared number, or the second action, back as an event; - automatically (
Automatic) — the adapter puts the number into the identity of the events it posts, and nothing is asked.
phone_number_verified is true only when both hold: the registration declares Proof: Proven, and
the number came on request or the event itself states it verified. A registration without Proven
never yields true — Veriqa downgrades what the adapter states and writes a warning. The number is
always in E.164: your adapter converts it to that form, Veriqa does not repair it.
LINE, KakaoTalk, WeChat and Zalo — your integration
These platforms give the phone number only to their own login or mini-app, which you register and the platform approves — not to a bot. Veriqa does not get the number there. If your application needs it from these users, obtain it in your own code through the platform’s login and keep it on your side.Discord and Threema
Neither platform gives a bot the user’s phone number.Limitations
- The window of an
Optionalnumber is kept in the memory of the instance that sent the request. If that instance stops before the window runs out, the step is not skipped, and the transaction waits until it expires. - The record that ties a chat to its waiting request is in-process by default. With more than one replica, move it to Redis together with the other channel stores (channel stores) — otherwise a number that arrives at another replica finds no request.
- When one chat has two sign-ins waiting for a number, the number goes to the one whose request came last; the other waits for its window or until it expires. In Telegram the message that ends either of them removes the reply keyboard, whichever request it belongs to: the keyboard is one per chat. The request of the sign-in still waiting is then left without its buttons.
- The buttons of the request are removed by the message that ends the sign-in — the receipt of its outcome (confirmed, declined or failed) or the notice that it expired — where the platform allows it; the channel sections above say how. Until that message they stay in the chat — also while a web step follows the phone step — and in WhatsApp, where a delivered message cannot be changed, they are not removed at all. Veriqa keeps the reference to the request with the record of the chat the sign-in was started from, one of the channel stores: when that record is lost, the request stays and the expiry is not reported. A number shared from them after the step is over finds no waiting request and is not accepted, and the bot does not answer it; a tap on the second button is then an ordinary message to the bot.