Spec / Integrations

WhatsApp now supports both phone numbers and usernames (@handles). AI Identity binds your Passport to whichever you registered — verified via the 'About' field on your business profile. Once bound, the Passport is published in the public registry so verifiers can look you up by either identifier.

whatsapp.com

1Issue an AI Identity

If you haven't already, create an identity for this agent in the dashboard. Free for the first identity per account.

Issue identity

2Register your surface

On the identity's edit page, add the agent's endpoint to Surfaces using the whatsapp scheme:

Surface format

wa:+{e164-phone}  OR  wa:@{username}

Example

wa:+447700900123  or  wa:@acmesupport

3Carry the Passport in WhatsApp

Click Issue Passport on the identity detail page to generate a signed token. Then drop it into your WhatsApp agent using one of the snippets below. Replace <PASSPORT_TOKEN> and <IDENTITY_ID> with the values shown in the dashboard.

One-time install (phone-bound profile)

text

For Business Cloud API tenants and most existing WhatsApp Business accounts.

1. /dashboard/identities/<your-id>/website  → "Verify WhatsApp Business"
2. We give you a token like  AII-VERIFY-x4q7m
3. Paste it into your WhatsApp Business profile "About" field
   (Settings → Business tools → Profile → About)
4. We confirm via the WA Business Cloud API (read-only). Done.

Surface registered as:  wa:+447700900123

One-time install (username-bound profile)

text

WhatsApp's 2026 username feature — verify by @handle, no phone number disclosed publicly.

1. Claim your username in WhatsApp:
   Settings → Profile → Username → choose @yourhandle
2. /dashboard/identities/<your-id>/website  → "Verify WhatsApp username"
3. Paste the token into your "About" field exactly as for phone-bound.
4. We resolve @yourhandle via WhatsApp's public profile lookup and
   confirm the token. Done.

Surface registered as:  wa:@yourhandle

Note: phone number is never published. Verifiers see only the @handle.

How verifiers consume this

Verifiers can call /api/v1/whois?surface=wa:+44... or /api/v1/whois?surface=wa:@handle to look up the bound identity. Both resolve to the same Passport when the same operator owns both — useful when a business migrates from phone-bound to username-bound. The WHOIS response includes whichever surfaces are publicly bound; phone numbers behind username-only profiles are never disclosed.

← All integrations

Read the core spec Issue identity