Skip to main content
In pilots. Asking by phone number is enabled for pilot companies. Ask us to turn it on for yours.
When a customer gives you their phone number, for example on a support call or in a chat with your agent, you can ask them to approve by that number instead of by your own user ref. BotShield looks the number up once and drops it. No answer tells you whether anyone holds it: every ask gets the same answer, and you show the person a two-digit number to pick in the BotShield app before they can approve. Two operations take a 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

Show match_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 with GET /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_in before anything about the number is read. Ask for it with partner_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 status 429 with retry_after_seconds, and nothing is sent.
  • One request_id, one way. A request_id already used with a user ref or an opaque_id cannot be reused by number, and the reverse. Both are refused with request_id_reused.

Error codes

Errors arrive as data.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.