WhatsApp onboarding

Get message link and QR code

GET /api/v1/whatsapp/onboarding

Returns a tappable WhatsApp link and an inline PNG QR code for your agent’s approved WhatsApp number. Both open a chat with Hello! prefilled. The person must tap Send to send the message to your agent. Unlike shared iMessage onboarding, WhatsApp does not require a connect message. This endpoint does not send a message, provision a number, or enable WhatsApp access.

Query parameters

Parameter	Type	Required	Description
`agent_identity_id`	UUID	Conditional	Required with an organization-wide API key. An identity-scoped key defaults to its own agent and may only request that identity.

Response (200)

JSON

{
  "agent_identity_id": "00000000-0000-4000-8000-000000000001",
  "number": "+15555550123",
  "message_text": "Hello!",
  "message_link": "https://wa.me/15555550123?text=Hello%21",
  "message_qr_png_data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEU…",
  "ready": true
}

Field	Type	Description
`agent_identity_id`	UUID	The requested agent identity
`number`	string or null	The agent’s approved WhatsApp number in E.164 format
`message_text`	string	The prefilled message, `Hello!`
`message_link`	string or null	A `https://wa.me/` link that drafts the message to the agent
`message_qr_png_data_url`	string or null	An inline PNG data URL encoding `message_link`; render it with `<img src={…} />`
`ready`	boolean	Whether the agent’s WhatsApp channel is currently ready

When the agent does not have enabled WhatsApp access, number, message_link, and message_qr_png_data_url are null, and ready is false. An enabled but temporarily unavailable channel retains its number, link, and QR code with ready: false. A link or QR code is not proof of current availability; check ready before presenting the agent as available.

Error responses

Status	Description
403	An identity-scoped API key requested another agent identity
404	The agent identity was not found in your organization
422	An organization-wide API key omitted `agent_identity_id`, or the parameter is not a valid UUID

Code examples

These SDK and CLI helpers require version 0.7.29 or later.

onboarding = inkbox.whatsapp.get_onboarding()
if onboarding.ready:
    print(onboarding.message_link)
    print(onboarding.message_qr_png_data_url)

const onboarding = await inkbox.whatsapp.getOnboarding();
if (onboarding.ready) {
  console.log(onboarding.messageLink);
  console.log(onboarding.messageQrPngDataUrl);
}

let onboarding = inkbox.whatsapp().get_onboarding(None)?;
if onboarding.ready {
    println!("{}", onboarding.message_link.as_deref().unwrap_or_default());
}

inkbox whatsapp onboarding --identity my-agent --json

curl "https://inkbox.ai/api/v1/whatsapp/onboarding" \
  -H "X-API-Key: YOUR_IDENTITY_API_KEY"

The SDK examples use an identity-scoped API key. With an organization-wide key, pass agent_identity_id in Python, agentIdentityId in TypeScript, or Some(&identity_id) in Rust. You can also call identity.get_whatsapp_onboarding() in Python or Rust, or identity.getWhatsAppOnboarding() in TypeScript, after retrieving your agent identity.

Receive the first message

Share the message link or display the QR code.
The person opens the link or scans the code, then taps Send in WhatsApp.
The message appears in the agent’s WhatsApp conversations. A subscribed agent receives a whatsapp.received webhook.

Your existing phone contact rules still apply. Opening the link or scanning the QR code alone does not send a message.

Agent signup API

Agent identity API

Agent2Agent API

Message retries

Mail API

Phone API

iMessage API

WhatsApp API

Slack API

Webhooks API

Tunnels API

Contacts API

Notes API

Vault API

Billing API

WhatsApp onboarding

Get message link and QR code

Query parameters

Response (200)

Error responses

Code examples

Receive the first message

​Get message link and QR code

​Query parameters

​Response (200)

​Error responses

​Code examples

​Receive the first message

Get message link and QR code

Query parameters

Response (200)

Error responses

Code examples

Receive the first message