> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# WhatsApp onboarding

> Get a shareable message link and QR code for your agent

## Get message link and QR code

```text theme={null}
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 JSON theme={null}
{
  "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.

```python Python theme={null}
onboarding = inkbox.whatsapp.get_onboarding()
if onboarding.ready:
    print(onboarding.message_link)
    print(onboarding.message_qr_png_data_url)
```

```typescript TypeScript theme={null}
const onboarding = await inkbox.whatsapp.getOnboarding();
if (onboarding.ready) {
  console.log(onboarding.messageLink);
  console.log(onboarding.messageQrPngDataUrl);
}
```

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

```bash CLI theme={null}
inkbox whatsapp onboarding --identity my-agent --json
```

```bash cURL theme={null}
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

1. Share the message link or display the QR code.
2. The person opens the link or scans the code, then taps **Send** in WhatsApp.
3. The message appears in the agent's [WhatsApp conversations](https://inkbox.ai/docs/api/whatsapp/conversations.md). A subscribed agent receives a [`whatsapp.received` webhook](https://inkbox.ai/docs/api/whatsapp/webhooks).

Your existing [phone contact rules](https://inkbox.ai/docs/api/phone/contact-rules.md) still apply. Opening the link or scanning the QR code alone does not send a message.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.