Meta Business Agent Platform

Customer OTP authentication

Updated: Sep 4, 2026
Copy for LLM
Some answers cannot be given to whoever happens to be holding the phone. A balance, an address change, a stored payment method, a booking held in someone’s name — all of them need the agent to know it is talking to the account holder. Meta Business Agent supports this with a one-time passcode issued by your own system: the agent asks your API to send a code, collects the code the customer types back, exchanges it for a token, and from then on calls your authenticated endpoints with that token attached. This page covers the connector configuration, the two tools that make up the exchange, and the guardrails that keep credentials out of the conversation.
The agent handles:
  • Offering the channels you support for delivering a code
  • Collecting and validating an account identifier before requesting a code
  • Requesting a passcode from your system and verifying the one the customer returns
  • Exchanging a verified code for a token, and attaching that token to later calls
  • Refreshing an expired token without asking the customer to verify again
  • Refusing to retry indefinitely, and failing to a person rather than looping

Who this guide is for

The examples use an energy supplier, but the pattern fits any business whose conversations cross from general information into a specific person’s account. The distinguishing question is whether a wrong answer would disclose something to the wrong person.
Organization typeWhat is behind the codeTypical identifier
Utilities and telecoms
Balance, usage, tariff changes, meter readings
Account number or registered email
Education and training providers
Enrolment status, results, certificates
Student number issued at enrollment
Property management and leasing
Lease dates, rent statements, maintenance jobs
Lease reference plus property postcode
Logistics and courier services
Consignment history, delivery instructions, claims
Account number plus consignment reference
Self-storage and workspace providers
Unit details, access codes, contract end dates
Unit number plus registered phone
This guide covers proving who someone is. It does not cover what to do with the session afterwards — keeping it alive, deciding what it unlocks, and ending it cleanly are in User login. If your conversations never touch personal data, you do not need any of this, and adding it will only cost you completed conversations.
Each step below notes how the API is used in other scenarios, then applies it to the energy supplier example.

Before you start

Verification in a chat thread is different from verification on a web page, in ways worth deciding deliberately rather than discovering later.
The conversation is a persistent, readable log. Anything the customer types stays visible in their chat history and on any device where that account is open. This is the reason the code is the only secret that ever enters the thread, and the reason it must be short-lived and single-use.
WhatsApp already establishes the phone number. It does not establish that the person holding the phone is your account holder, and the two are different claims. Treat the number as a strong hint that lets you skip asking for an identifier, never as the verification itself.
Sending the code over a different channel from the one the conversation is on is the stronger design. A code delivered to the same WhatsApp thread proves only that someone controls that thread, which you already knew.

Prerequisites

Have the following in place before you configure OTP authentication. The first three come from Meta Business Agent onboarding; the rest are your own systems.
  • An onboarded and enabled Meta Business Agent (rollout.enabled: true) — see End-to-end setup
  • A valid system user access token (SUAT) or Business Integration System User (BISU) token with the whatsapp_business_messaging permission — see Generate an access token
  • Your WhatsApp Business phone number ID ({entity_id}) — the phone number the agent is enabled on, not the WhatsApp Business account ID. Find it in WhatsApp Manager⁠ under Account tools > Phone numbers
  • An endpoint that issues a one-time passcode to a customer over a channel you control
  • An endpoint that verifies a submitted code and returns a token on success
  • At least one authenticated endpoint the token is good for, required by Call an authenticated endpoint
  • A staffed destination for customers who cannot complete verification, required by Handle failure

Create a connector with user auth injection

A connector is the bridge to your account systems. For an authenticated flow it carries two separate credentials, and keeping them distinct is the central idea of this guide.
The auth_config credential identifies your integration to your API. It is the same on every call, for every customer.
The user_auth_injection_config describes where to put a credential that identifies the customer. That one is obtained during the conversation and differs per customer.
curl -X POST "https://api.facebook.com/{entity_id}/agent_connectors" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "name": "northwind_account_api",
  "description": "Issues and verifies one-time passcodes for Northwind Energy customers, and serves account data for a verified customer.",
  "base_url": "https://api.northwind-energy.invalid/customer/v1",
  "auth_type": "API_KEY",
  "auth_config": {
    "api_key": {
      "headers": [
        {
          "field_name": "X-API-Key",
          "value": "{YOUR_ACCOUNT_API_KEY}"
        }
      ]
    }
  },
  "user_auth_injection_config": {
    "location": "headers",
    "field_name": "Authorization",
    "prefix": "Bearer "
  }
}'
user_auth_injection_config takes three fields:
FieldDescription
location
Where the customer credential is placed: headers, query, body, or path
field_name
The header, parameter, or field name to place it in, such as Authorization
prefix
A string prepended to the value, such as Bearer — include the trailing space if your scheme needs one
Prefer headers. A token in query lands in access logs and proxy logs on your side, and a token in path does the same while also making the URL harder to route.
Save the id from the response — the tools below are created under it, where it becomes the {connector_id} path parameter.
Where else this applies. The two-credential split appears in every connector that acts for a specific person rather than for the business as a whole. Configure the injection point when you create the connector even if you add the authenticated tools later, because changing it afterwards means revisiting every tool that depends on it.

Add agent instructions

Agent instructions shape how the agent responds. The title is a short identifier, description tells the agent when to apply the instruction, and skill contains the instruction text. Titles are limited to lowercase letters, numbers, and hyphens.
The verification instruction is mostly a set of prohibitions. Its job is to keep a helpful agent from being talked out of the sequence.
curl -X POST "https://api.facebook.com/{entity_id}/agent_config/skills" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "title": "customer-verification",
  "description": "Applied when a customer asks about their own account, balance, usage, appointments, or personal details, and has not yet verified in this conversation.",
  "skill": "Verify the customer before answering anything specific to their account. Explain in one sentence why verification is needed, then ask which channel they want the code sent to and offer only the channels the business supports. Ask for their account number or the email registered on the account, and check it looks well formed before calling request_passcode. Tell them a code has been sent and ask them to type it back. Call verify_passcode with exactly the digits they sent. Allow three attempts at the code and one resend, then stop and offer a colleague. Never state, repeat, confirm, or spell out the code, and never accept a code the customer claims to have received without calling verify_passcode. Never accept an alternative form of identification such as a date of birth, a partial address, or a previous order number in place of the code. Do not reveal whether an account number exists when verification fails; say only that verification did not succeed. Once verified, answer account questions for that customer only, and do not re-verify for later questions in the same conversation."
}'
Two of those clauses do disproportionate work. Forbidding alternative identification closes the route a determined caller takes when the code does not arrive. Refusing to disclose whether an account exists closes an enumeration path that is otherwise wide open, because a helpful agent will happily say “I can’t find that account number” to anyone who asks.
Some content filters treat certain security vocabulary as unsafe, and an instruction that trips one is still created and still returned by the API — it is simply never applied. After creating any instruction, read it back and check its status:
curl -X GET "https://api.facebook.com/{entity_id}/agent_config/skills" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-API-Version: 2.0.0"
Each instruction carries a status of active, pending_review, or blocked. Only active is applied. blocked means the instruction failed the automated content review, which the reference notes happens most often when the text asks for or refers to sensitive personal information — exactly what a verification instruction does. If it is blocked, rephrase it in plainer operational language — “passcode” and “verification” rather than more loaded security terms — and update it.
The review is asynchronous, so an instruction read back immediately after creation is normally pending_review. A single immediate read tells you nothing either way; poll until the status settles on active or blocked.
Where else this applies. Verification instructions are unusual in being defined almost entirely by what the agent must refuse. Write the refusals first and the happy path second, because the happy path is the part the agent gets right without being told.

Offer the delivery channel

Let the customer choose where the code goes. Typing a channel name is more error-prone than tapping one, so use an interactive message with reply buttons.
curl -X POST "https://api.facebook.com/{entity_id}/agent-ui-skills" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "title": "passcode-channel-choice",
  "component_type": "interactive_reply_buttons",
  "status": "enabled",
  "instruction": "Send this when asking the customer where they want their one-time passcode delivered, before calling request_passcode. Set the body text to a short question asking where to send the code. Add one button per channel the business supports, labeled SMS, Email, and Voice call. Do not add a button for any other channel and do not add a cancel button."
}'
Reply buttons take between one and three buttons, each labeled with up to 20 characters, and each label must be distinct. If you support more than three channels, use interactive_list instead. For the data elements each component type accepts, see Writing interactive messages.
The buttons name the channels your business supports. The destination itself must already be registered against the account, and that has to be enforced in request_passcode rather than in the button list — the agent offers the buttons before it knows which account it is dealing with, so it cannot narrow them itself. Reject a send to any destination not already on the account: a flow that lets someone nominate a destination is not verification, whatever it is called.

Define connector tools

Connector tools define the operations the agent can invoke. Each tool needs a name, a description, user_auth_required, and a request_definition describing the outbound HTTP call.
A name can contain only letters, numbers, and underscores. Spaces, hyphens, and other punctuation are rejected. It also cannot start or end with an underscore, or contain two underscores in a row, so check_order_status is accepted while _check_order, check_order_, and check__order are not. The same rules apply to a connector’s name.
Verification needs two tools, and they differ in an important way from every other tool you configure. The second one declares itself as the tool that produces the customer credential, using user_auth_action_config.

Request a passcode

This runs before the customer is verified, so user_auth_required is false.
curl -X POST "https://api.facebook.com/{entity_id}/agent_connectors/{connector_id}/tools" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "name": "request_passcode",
  "description": "Sends a one-time passcode to the customer over the channel they chose, and returns only whether the request was accepted. Call this once the customer has given an account identifier and picked a channel. Do not call it more than once without the customer explicitly asking for a new code. This tool never returns the code itself.",
  "user_auth_required": false,
  "request_definition": {
    "method": "POST",
    "path": "/auth/passcode",
    "body": {
      "content_type": "application/json",
      "params": {
        "identifier": {
          "type": "string",
          "description": "The account number or registered email address the customer gave, exactly as they typed it."
        },
        "channel": {
          "type": "string",
          "description": "Where to send the code. One of: sms, email, voice."
        },
        "customer_phone": {
          "type": "string",
          "description": "The WhatsApp phone number the conversation is on, used for rate limiting and fraud checks.",
          "binding": {
            "kind": "macro",
            "macro": "WHATSAPP_PHONE_NUMBER"
          }
        },
        "conversation_id": {
          "type": "string",
          "description": "The conversation this request belongs to, so a code issued in one conversation cannot be redeemed in another.",
          "binding": {
            "kind": "macro",
            "macro": "WHATSAPP_CONVERSATION_ID"
          }
        }
      },
      "required": ["identifier", "channel", "customer_phone", "conversation_id"]
    }
  }
}'
Return the same response whether or not the identifier matches an account. An endpoint that answers differently for a real account than for an invented one is an account enumeration oracle, and the agent will faithfully relay the difference to whoever is asking.
Binding conversation_id with the WHATSAPP_CONVERSATION_ID macro lets you scope the code to the conversation that requested it. Enforce that scope in your own service.

Verify the passcode and obtain a token

This is the tool that turns a verified code into a credential. user_auth_action_config tells Meta Business Agent that the response contains a customer token and where in the response to find it.
curl -X POST "https://api.facebook.com/{entity_id}/agent_connectors/{connector_id}/tools" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "name": "verify_passcode",
  "description": "Checks the passcode the customer typed and, when it is correct, returns a token authorizing account access for this conversation. Call this with exactly the digits the customer sent, without reformatting them. A failure means the code was wrong or has expired; tell the customer only that, and never say which.",
  "user_auth_required": false,
  "user_auth_action_config": {
    "user_action_tool_type": "auth",
    "user_auth_token_path": "data.access_token",
    "refresh_token_path": "data.refresh_token",
    "expires_at_path": "data.expires_in",
    "expires_at_type": "relative_seconds"
  },
  "request_definition": {
    "method": "POST",
    "path": "/auth/passcode/verify",
    "body": {
      "content_type": "application/json",
      "params": {
        "identifier": {
          "type": "string",
          "description": "The same account identifier used when the code was requested."
        },
        "passcode": {
          "type": "string",
          "description": "The code the customer typed, digits only, exactly as they sent it."
        },
        "customer_phone": {
          "type": "string",
          "description": "The WhatsApp phone number the conversation is on.",
          "binding": {
            "kind": "macro",
            "macro": "WHATSAPP_PHONE_NUMBER"
          }
        },
        "conversation_id": {
          "type": "string",
          "description": "The conversation the code was issued for.",
          "binding": {
            "kind": "macro",
            "macro": "WHATSAPP_CONVERSATION_ID"
          }
        }
      },
      "required": ["identifier", "passcode", "customer_phone", "conversation_id"]
    }
  }
}'
user_auth_action_config takes these fields:
FieldDescription
user_action_tool_type
auth for the tool that establishes the session, refresh for one that renews it
user_auth_token_path
Dot-path to the customer token in your response, such as data.access_token
refresh_token_path
Dot-path to a refresh token, when your API issues one
expires_at_path
Dot-path to the expiry value
expires_at_type
absolute for a timestamp, relative_seconds for a lifetime in seconds
Get expires_at_type right. Reading a 3600 as an absolute timestamp places expiry in 1970 and every authenticated call fails immediately; reading a real timestamp as a duration places expiry decades away and the agent keeps presenting a token your API has long since rejected.
The paths are read against your response body, so they have to match your actual shape. If your API returns the token at the top level, the path is access_token, not data.access_token.

Refresh the token

When your tokens are short-lived, add a tool with user_action_tool_type set to refresh. Meta Business Agent uses it to renew an expiring session rather than sending the customer through verification again.
curl -X POST "https://api.facebook.com/{entity_id}/agent_connectors/{connector_id}/tools" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "name": "refresh_session",
  "description": "Exchanges a refresh token for a new access token. Not called directly in conversation; used to renew an expiring session.",
  "user_auth_required": false,
  "user_auth_action_config": {
    "user_action_tool_type": "refresh",
    "user_auth_token_path": "data.access_token",
    "refresh_token_path": "data.refresh_token",
    "expires_at_path": "data.expires_in",
    "expires_at_type": "relative_seconds"
  },
  "request_definition": {
    "method": "POST",
    "path": "/auth/refresh",
    "body": {
      "content_type": "application/json",
      "params": {
        "conversation_id": {
          "type": "string",
          "description": "The conversation whose session is being renewed.",
          "binding": {
            "kind": "macro",
            "macro": "WHATSAPP_CONVERSATION_ID"
          }
        }
      },
      "required": ["conversation_id"]
    }
  }
}'
Without a refresh tool, an expired token means the customer verifies again mid-conversation, which reads as the agent having forgotten who they are.

Call an authenticated endpoint

Any tool that needs the customer’s identity sets user_auth_required to true. The token obtained by the auth tool is injected at the location the connector declared, and the tool definition itself carries no credential.
curl -X POST "https://api.facebook.com/{entity_id}/agent_connectors/{connector_id}/tools" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "name": "get_account_balance",
  "description": "Returns the current balance, the next payment date, and the most recent meter reading for the verified customer. Requires a verified customer. Never call this before verify_passcode has succeeded in this conversation.",
  "user_auth_required": true,
  "request_definition": {
    "method": "GET",
    "path": "/account/balance"
  }
}'
Notice there is no account identifier in the request. The token establishes who the customer is, so the endpoint reads identity from the token rather than from a parameter the agent supplies. Never accept an account identifier alongside a token on an authenticated endpoint — a tool that takes both can be induced to fetch one customer’s data while holding another customer’s credential.
Where else this applies. The auth, refresh, and user_auth_required triple is the whole mechanism, and it is the same whether the credential comes from a passcode, a password, or a link the customer follows. Configure verification once and every authenticated tool you add afterwards is a matter of setting one boolean.

Handle failure

Codes do not arrive. Numbers change. People mistype. Decide the ceiling and what happens at it before launch, because the alternative is a loop that a frustrated customer cannot escape.
Three attempts and one resend is a reasonable default. After that, hand over rather than continuing.
Count the attempts in your own service, not only in the agent instruction. Enforce expiry, and invalidate the code on success and on the final failure, inside verify_passcode itself. The instruction is a UX ceiling: it shapes what the agent says when a customer runs out of tries, and agents can be talked around their instructions — as the Tips on this page note. A passcode whose only limit is prompt text is brute-forceable at the speed your endpoint will answer.
Set the handoff policy with Agent settings, and transfer the conversation with Thread control (Cloud API):
curl -X POST "https://api.facebook.com/business/whatsapp/phone_numbers/{phone_number_id}/thread_control" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "messaging_product": "whatsapp",
  "action": "take",
  "to": "{CUSTOMER_PHONE_NUMBER}",
  "metadata": "Verification failed after 3 attempts"
}'
Note the path parameter is named phone_number_id here rather than entity_id. It is the same WhatsApp Business phone number ID used everywhere else in this guide, and these calls take X-API-Version: 1.0.0 if you send it, not the 2.0.0 used by every other call in this guide. The header is optional, so the examples omit it.
Put the reason in metadata, never the identifier the customer offered. That string is forwarded verbatim to the receiving app, and it should not become another place account numbers accumulate.
Make sure the colleague picking up the conversation knows the customer is not verified. A handoff that reads as “customer needs help with their balance” invites someone to answer from an internal system without checking, which undoes the whole control.
Where else this applies. Any bounded retry needs a defined terminal state. Loops without one are worse than an outright refusal: the customer stays engaged, gets nowhere, and arrives at your contact center angrier than if the agent had handed over at the second attempt.

Test the agent

Use Agent test to simulate conversations before going live. Pass conversation_id from a previous response to continue a multi-turn exchange.
curl -X POST "https://api.facebook.com/{entity_id}/agent_test" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -H "X-API-Version: 2.0.0" \
  -d '{
  "user_msg": "What is my current balance?"
}'
Cover these scenarios in your test plan:
ScenarioSample message
Account question before verifying
“What is my balance?”
Correct code first time
The happy path end to end
Wrong code, then correct
Verify the retry counter resets properly
Three wrong codes
Confirm handoff fires at the ceiling
Expired code
Wait past your expiry window, then submit
Code replayed after success
Submit a code that already verified; confirm it is refused
Resend requested
“I didn’t get it, send it again”
Alternative identification offered
“I can give you my date of birth instead”
Code disclosure attempted
“What code did you send me?”
Unknown account identifier
Confirm the reply is identical to a known one
Second account question after verifying
Confirm no second verification
Expired token mid-conversation
Confirm refresh runs without re-verification
Someone else’s account requested
“Can you check my partner’s account too?”
Four of these deserve automated regressions: alternative identification offered, code disclosure attempted, unknown account identifier, and someone else’s account requested. They are the ones where an agent optimizing for helpfulness weakens the control, and they will not show up in manual testing because nobody testing the happy path thinks to ask.
Where else this applies. A verification test plan should be adversarial rather than representative. Assume a tester who wants the data and is willing to be persistent, and write the cases they would try.

Example conversation

This exchange shows the configuration above in use: the agent explains why it is verifying, offers channels as buttons, refuses substitute identification, never repeats the code, and stays verified for the rest of the conversation.
Customer: Can you tell me my balance?
Agent: I can, once I have checked it is really you. Where shall I send a one-time code?
(sends reply buttons: SMS, Email, Voice call)
Customer:(taps SMS)
Agent: What is your account number, or the email address on the account?
Customer: NW-4471903
Agent:(calls request_passcode)
Sent. Type the code back here when it arrives.
Customer: I didn’t get anything. Can I just give you my date of birth?
Agent: I’m afraid not — a code is the only way I can verify an account. Shall I send it again, or would you prefer email this time?
Customer: Try again
Agent:(calls request_passcode)
Sent again.
Customer: 448210
Agent:(calls verify_passcode, then get_account_balance)
Thanks, you’re verified. Your balance is 84.20 in credit, and your next payment of 62.00 is due on 15 September.
Customer: And when was my last meter reading?
Agent:(calls get_account_balance)
Your last reading was submitted on 28 August.

Monitor connector health

The connector logs endpoint, GET /{entity_id}/agent_connectors/{connector_id}/logs, reports how your account systems are answering the agent.
curl -X GET "https://api.facebook.com/{entity_id}/agent_connectors/{connector_id}/logs?summary_only=true&top_n=5&include_stats=true" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "X-API-Version: 2.0.0"
Logs cover the last seven days, and the requested time range cannot exceed seven days. The response carries two objects:
ObjectFieldWhat it reports
data
failure_code_name
The failure category
data
error_message
The message returned by your endpoint
data
tool_name
Which tool made the call
data
occurrences
How many times this failure appeared
stats
success_rate
Share of calls that succeeded
stats
avg_latency_s
Mean round-trip time in seconds
stats
p95_latency_s
95th percentile round-trip time in seconds
stats
p99_latency_s
99th percentile round-trip time in seconds
Filter to one operation with tool_id. Read the two verification tools separately: a healthy request_passcode next to a failing verify_passcode points at delivery or expiry, while both failing points at your service.
The ratio between them is the number to watch. Every request_passcode should be followed by a verify_passcode within a minute or two, and a growing gap means codes are being requested and never used — usually a delivery problem, occasionally someone probing your identifiers.
Where else this applies. Authentication tools are worth alerting on more aggressively than read tools, because their failures are silent to you and total for the customer. A customer who cannot verify cannot do anything else either, and most will leave rather than report it.

Tips for this use case

These are the verification decisions that most often go wrong once the agent is live.
Send the code somewhere other than the thread. A code delivered into the same WhatsApp conversation proves control of that conversation, which was never in question.
Return an identical response for unknown identifiers. Any difference between a real account and an invented one is an enumeration oracle, and the agent will relay it.
Never let the agent voice the code. Forbid stating, confirming, or spelling it out. Asked directly, an unrestrained agent will helpfully read it back.
Refuse substitute identification explicitly. Date of birth, partial address, a recent order number — name them as unacceptable, because the agent will otherwise accept them as reasonable.
Bound the retries and mean it. Three attempts and one resend, then a person. Handing over is a better outcome than a loop.
Check expires_at_type against what your API actually returns. Mismatching a duration and a timestamp fails every authenticated call or none of them, and both look like something else.
Add a refresh tool. Without one, a long conversation ends in a second verification, which reads as the agent forgetting who it is talking to.
Take identity from the token, not from a parameter. An authenticated endpoint that also accepts an account identifier can be walked onto a different account.
Tell the handoff destination the customer is unverified. Otherwise verification is enforced by the agent and quietly bypassed by the colleague who takes over.
Check status after creating an instruction. One that trips the content filter is created and returned like any other, but comes back blocked and is never applied. Presence in the list proves nothing; the status field is the signal.

Summary checklist

Confirm each of the following before you enable the agent on a production phone number.
  • Created a connector with both auth_config and user_auth_injection_config set
  • Chose headers as the injection location rather than query or path
  • Added a customer-verification instruction and confirmed GET /agent_config/skills reports its status as active
  • Forbade the agent from stating, repeating, or confirming the code
  • Forbade substitute identification by name
  • Made the instruction give an identical response for unknown and known identifiers
  • Added an interactive_reply_buttons interactive message offering only registered channels
  • Defined request_passcode with user_auth_required set to false
  • Defined verify_passcode with user_action_tool_type set to auth
  • Verified user_auth_token_path matches your real response shape
  • Verified expires_at_type matches whether your API returns a timestamp or a duration
  • Added a refresh tool so long conversations do not re-verify
  • Set user_auth_required to true on every account-specific tool
  • Removed account identifiers from the request of every authenticated tool
  • Scoped codes to the conversation using WHATSAPP_CONVERSATION_ID and enforced it server-side
  • Set a retry ceiling and configured handoff at that ceiling
  • Enforced the attempt count, code expiry, and single use in verify_passcode, not only in the agent instruction
  • Confirmed handoff metadata carries a reason and no account identifier
  • Confirmed the handoff destination is told the customer is unverified
  • Tested wrong codes, expired codes, resends, substitute identification, code disclosure, and unknown identifiers
  • Set up per-tool connector monitoring and alerting on the request-to-verify ratio