In pilots. Asking by phone number is enabled for pilot companies. Ask us to turn it on for yours.
phone_number:
Name the person one way only. A request with
phone_number and any other way to name the person is refused with one_addressee_required.
Ask
curl
agentlink/inquire answers the same way, with status: "queued", card_id, ttl_at, request_id and match_number.
The answer is the same whether or not anyone holds the number, and every answer takes about the same time. Send the number with the country code when it is outside the US. BotShield checks only the number’s form: an international number with + and the country code, or 10 digits (or 11 starting with 1) for the US and Canada. A malformed number is refused with phone_invalid.
Show the match number
Showmatch_number to the person where you are talking to them: on your screen, in your agent’s conversation, or read aloud on the call. In the BotShield app, the card shows three two-digit numbers. The person picks yours, then approves with their passkey.
A wrong pick ends the request: it reads denied, and no token or proof is issued. This is what stops someone from approving an ask that was meant for another conversation.
What the person receives
What happens next depends on who holds the number, and none of it changes the answer you got.Read the status
Read the status withGET /gates-api/actions/request-status or GET /agentlink/check-status, as for any ask. Until a card exists, the request reads queued, then expired when expires_at passes. That is the same for a number nobody holds, an introduction that is never allowed, a person who blocked you, and a card a limit stopped. Once the card exists, it reads as itself: approved, denied, expired or cancelled.
Withdraw a request the usual way, with gates-api/actions/request-cancel or agentlink/cancel. It is withdrawn the same whether or not a card was ever made.
Rules
- The number is used once. BotShield uses it for one lookup, then drops it. It is never stored, logged or sent in a webhook.
- High-value actions are never asked by number. An action marked high-value is refused with
action_requires_signed_inbefore anything about the number is read. Ask for it withpartner_user_ref, from your customer’s signed-in session. - Production needs a verified business. In Production, only an organization that has passed business verification can ask by phone number. Development keys and development agents can ask without it.
- Your company’s limits. Asks by phone number are limited per API key or agent per hour (
send_rate_limited), and by how many of your company’s asks by number in the last 24 hours went unanswered (unanswered_limit_reached). Both answer HTTP status429withretry_after_seconds, and nothing is sent. - One
request_id, one way. Arequest_idalready used with a user ref or anopaque_idcannot be reused by number, and the reverse. Both are refused withrequest_id_reused.
Error codes
Errors arrive asdata.error with HTTP 200. These are the codes particular to asking by phone number. The other codes of each operation are listed on Ask through an agent and Propose an action.
Next steps
Ask through an agent
The full request, the terms, the token and withdrawing.
Propose an action
Your agent’s own proposal, with
phone_number.Place an action
Mark an action high-value.
Privacy boundary
What BotShield never tells you about a person.
