> ## 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.

# Connecter le WhatsApp d'un client

> Laissez chacun de vos clients connecter son propre numéro WhatsApp Business depuis votre produit, avec une session hébergée.

Ce guide détaille le parcours de [session hébergée](https://docs.shortext.ny-corp.io/fr/api-reference/hosted-sessions.md) avec l'objectif `whatsapp`. Votre clé doit avoir **Gérer les intégrations**.

## 1. Préparer l'agent

Créez ou choisissez l'agent qui répondra sur le numéro du client (`POST /agents` ou `GET /agents`). Gardez son identifiant, `AGI-XXXXX`.

## 2. Créer la session quand le client clique sur « Connecter 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"])
```

Enregistrez `body.id` avec le client concerné, puis redirigez le client vers `body.url`. Le lien est valable `expires_in` minutes (60 par défaut, 24 heures au maximum).

## 3. Le client connecte son numéro

Sur la page Shortext, le client se connecte à Facebook, choisit ou crée son portefeuille Meta Business et son compte WhatsApp Business, puis ajoute et vérifie son numéro. Shortext le renvoie ensuite vers :

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

## 4. Confirmer sur votre serveur

Affichez un état d'attente sur votre page de retour, et confirmez côté serveur :

* écoutez `hosted_session.completed` / `hosted_session.failed` sur votre [webhook](https://docs.shortext.ny-corp.io/fr/api-reference/webhooks.md) (filtrez sur `purpose` si besoin), ou
* appelez `GET /hosted-sessions/{session_id}`.

En cas de succès, `result.channels` liste les numéros connectés :

```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
}
```

Enregistrez l'`id` de chaque canal pour le client : c'est le `channel_id` depuis lequel envoyer les messages. En cas de `failed`, affichez `error` et proposez de réessayer avec une nouvelle session.

## 5. Aller plus loin

* Envoyez les premiers messages du client avec des [modèles](https://docs.shortext.ny-corp.io/fr/api-reference/guides/send-a-template.md).
* Déplacez le numéro vers un autre agent avec `PUT /channels/whatsapp/{id}/agent`.
* Connectez une boîte mail de la même façon avec l'objectif `mail`.


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