Skip to main content
Veriqa takes a phone number only from the channel: the messaging app hands it over, the user never types it. The sign-in page has no phone field, and a number typed into the chat as a message is not accepted. Your application receives it as the standard 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 the phone_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: true only when the channel proves that the number belongs to the user who sent it, otherwise false.
  • Both claims go out only under a granted phone scope.
A contact that fails the channel’s ownership check — somebody else’s contact card, a forwarded contact, a missing or wrong signature — is not accepted, and the bot asks again. A request that cannot be delivered to the chat even after retries changes nothing: the step waits as it does with no answer.

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: the user_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.
If you route the bot’s updates yourself — one bot shared by your code and Veriqa, and your code decides which update goes to Veriqa with OwnsInboundEvent (see phone number on request) — the Skip and Cancel sign-in buttons reach your bot, not Veriqa: in Telegram they are plain text buttons with no marker to recognize. The shared contact itself is recognized. An Optional number is then skipped by the window, and a Required one waits until the transaction expires. The other ways to share a bot are compared in You already have a bot.

MAX

The bot sends the share button and a callback button with the second action. The number is taken from vcf_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.

WhatsApp

Veriqa identifies a WhatsApp user by the business-scoped user ID (BSUID), not by the number. While WhatsApp sends the number with a message, the token carries 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.

Instagram

The account sends one message: the text of the request with two quick-reply buttons under it. The first is drawn by Instagram and shares the phone number of the user’s Instagram profile; the second carries the second action of the step. Instagram does not say that it has checked the number, so the token carries phone_number with phone_number_verified: false. A number the user types into the chat is not accepted — only the one the button sends.
Not every user sees the button. Instagram shows the button that shares the number only in its mobile app and only to a user whose profile has a phone number; on a computer it shows no quick replies at all — the second button included (Meta: quick replies). The channel still counts as able to provide a number, so a Required number keeps Instagram on the sign-in page. A user who gets no button cannot share the number: an Optional number is skipped when its window runs out, and with a Required one the sign-in waits until the transaction expires or the user cancels it. There is no other way to hand the number over in this channel.
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 carries phone_number with phone_number_verified: false. A number the user types into the chat is not accepted — only the one the button sends.
Not every user sees the button. Messenger shows the button that shares the number only to a user whose profile has a phone number (Meta: quick replies). The channel still counts as able to provide a number, so a Required number keeps Messenger on the sign-in page. A user who gets no button cannot share the number: an Optional number is skipped when its window runs out, and with a Required one the sign-in waits until the transaction expires or the user cancels it.
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: the share-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 — with Http: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.
A channel that declares neither gives no number and is left out of a sign-in that requires one. 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 Optional number 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.