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

# Connect a client's WhatsApp

> Let each of your clients connect their own WhatsApp Business number from your product, with a hosted session.

This guide walks through the [hosted session](https://docs.shortext.ny-corp.io/api-reference/hosted-sessions.md) flow for the `whatsapp` purpose. Your key needs **Manage integrations**.

## 1. Prepare the agent

Create or choose the agent that will answer on the client's number (`POST /agents` or `GET /agents`). Keep its id, `AGI-XXXXX`.

## 2. Create the session when the client clicks "Connect WhatsApp"

```bash cURL theme={null}
curl -X POST https://shortext.ny-corp.io/api/v2.0/hosted-sessions \
  -H "Authorization: Bearer $SHORTEXT_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "whatsapp",
    "context": { "agent_id": "AGI-XXXXX" },
    "return_url": "https://app.example.com/settings/whatsapp",
    "locale": "fr",
    "expires_in": 60
  }'
```

```php PHP theme={null}
<?php
$response = (new GuzzleHttp\Client())->post('https://shortext.ny-corp.io/api/v2.0/hosted-sessions', [
    'headers' => ['Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json'],
    'json'    => [
        'purpose'    => 'whatsapp',
        'context'    => ['agent_id' => 'AGI-XXXXX'],
        'return_url' => 'https://app.example.com/settings/whatsapp',
        'locale'     => 'fr',
        'expires_in' => 60,
    ],
]);
$session = json_decode((string) $response->getBody(), true)['body'];

// Store $session['id'], then send the user to the page (never log the URL: it holds a secret)
header('Location: ' . $session['url']);
```

```javascript Node.js theme={null}
const response = await fetch("https://shortext.ny-corp.io/api/v2.0/hosted-sessions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`,
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    purpose: "whatsapp",
    context: { agent_id: "AGI-XXXXX" },
    return_url: "https://app.example.com/settings/whatsapp",
    locale: "fr",
    expires_in: 60,
  }),
});
const { body: session } = await response.json();

// Store session.id, then redirect the user (never log the URL: it holds a secret)
res.redirect(session.url);
```

```python Python theme={null}
response = requests.post(
    "https://shortext.ny-corp.io/api/v2.0/hosted-sessions",
    headers={"Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json"},
    json={
        "purpose": "whatsapp",
        "context": {"agent_id": "AGI-XXXXX"},
        "return_url": "https://app.example.com/settings/whatsapp",
        "locale": "fr",
        "expires_in": 60,
    },
)
session = response.json()["body"]

# Store session["id"], then redirect the user (never log the URL: it holds a secret)
return redirect(session["url"])
```

Store `body.id` with the client it belongs to, then redirect the client to `body.url`. The link is valid for `expires_in` minutes (60 by default, 24 hours at most).

## 3. The client connects their number

On the Shortext page, the client logs in to Facebook, chooses or creates their Meta business portfolio and WhatsApp Business account, then adds and verifies their number. Shortext then sends them to:

```text theme={null}
https://app.example.com/settings/whatsapp?session_id=9b1e4c3a-...&status=completed
```

## 4. Confirm on your server

Show a waiting state on your return page, and confirm with your server:

* listen to `hosted_session.completed` / `hosted_session.failed` on your [webhook](https://docs.shortext.ny-corp.io/api-reference/webhooks.md) (filter on `purpose` if needed), or
* call `GET /hosted-sessions/{session_id}`.

On success, `result.channels` lists the connected numbers:

```json theme={null}
{
  "id": "9b1e4c3a-6f2d-4b8e-9a7c-2d5f8e1b0c4a",
  "purpose": "whatsapp",
  "status": "completed",
  "result": {
    "channels": [
      { "type": "whatsapp", "id": "532867649916076", "name": "+237 6 99 99 99 99 (Acme)", "enabled": true, "agent": { "id": "AGI-XXXXX", "name": "Support" } }
    ]
  },
  "error": null
}
```

Save each channel `id` for the client: it is the `channel_id` to send messages from. On `failed`, show `error` and offer to try again with a new session.

## 5. Go further

* Send the client's first messages with [templates](https://docs.shortext.ny-corp.io/api-reference/guides/send-a-template.md).
* Move the number to another agent with `PUT /channels/whatsapp/{id}/agent`.
* Connect a mailbox the same way with the `mail` purpose.


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