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

# Sessions hébergées

> Laissez vos propres clients connecter leur numéro WhatsApp ou leur boîte mail sur une page Shortext, depuis votre produit.

Une session hébergée est un lien signé et temporaire vers une page **hébergée par Shortext**, où votre utilisateur réalise une étape impossible dans votre propre produit : s'identifier auprès de Meta pour connecter un numéro WhatsApp Business, ou saisir et vérifier les paramètres d'une boîte mail. Une fois terminé, il revient dans votre application et vous recevez le résultat.

Cas typique : vous construisez un produit sur Shortext, et chacun de vos clients connecte son propre numéro WhatsApp à l'agent que vous avez configuré pour lui.

## Parcours

**1. Créez la session (votre serveur)**

`POST /hosted-sessions` avec un `purpose` (objectif). La réponse contient l'`url` de la page.

**2. Envoyez votre utilisateur sur la page**

Redirigez-le, ou ouvrez l'URL dans une nouvelle fenêtre. Ne l'intégrez pas dans une iframe : la connexion Meta la refuse.

**3. Votre utilisateur complète la page**

Sur `https://shortext.ny-corp.io/connect/{token}`, il s'identifie auprès de Meta ou saisit les paramètres de sa boîte mail.

**4. Retour dans votre application**

Shortext le renvoie vers votre `return_url` avec `?session_id={id}&status={statut}`.

**5. Récupérez le résultat (votre serveur)**

Recevez le webhook `hosted_session.completed` ou `hosted_session.failed`, ou appelez `GET /hosted-sessions/{id}`. Ne vous fiez pas au seul `status` de l'URL de retour : n'importe qui peut le saisir.

## Objectifs

`GET /hosted-sessions/purposes` les liste.

| Objectif | Page | `context` |
| - | - | - |
| `whatsapp` | Connecter des numéros WhatsApp Business avec l'inscription intégrée de Meta. | `agent_id` : l'agent qui répond sur les numéros (par défaut : votre premier agent). |
| `mail` | Connecter une boîte mail en IMAP / SMTP ; la connexion est vérifiée avant l'enregistrement. | `agent_id` : l'agent qui répond sur la boîte (par défaut : votre premier agent). |

## Créer une session

Demande la permission **Gérer les intégrations**.

**purpose** `string` *required*

`whatsapp` ou `mail`.

**context** `object`

Options de l'objectif, par exemple `{ "agent_id": "AGI-XXXXX" }`. L'agent doit appartenir à votre entreprise.

**return\_url** `string`

Votre page vers laquelle l'utilisateur revient. HTTPS uniquement.

**locale** `string`

La langue de la page, par exemple `fr` ou `en`.

**expires\_in** `integer` (default: 60)

Durée de validité du lien en minutes, de 5 à 1 440 (24 heures).

```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"])
```

```json Réponse theme={null}
{
  "success": true,
  "message": "Request success.",
  "code": 1000,
  "body": {
    "url": "https://shortext.ny-corp.io/connect/hs_...",
    "id": "9b1e4c3a-6f2d-4b8e-9a7c-2d5f8e1b0c4a",
    "purpose": "whatsapp",
    "status": "pending",
    "context": { "agent_id": "AGI-XXXXX" },
    "result": null,
    "error": null,
    "return_url": "https://app.example.com/settings/whatsapp",
    "locale": "fr",
    "expires_at": "2026-10-24T10:12:44+00:00",
    "opened_at": null,
    "finished_at": null,
    "created_at": "2026-10-24T09:12:44+00:00"
  }
}
```

> [!WARNING]
>
> L'`url` contient un secret et n'est renvoyée qu'à la création. Ne la journalisez jamais, ne la partagez qu'avec l'utilisateur à qui elle est destinée.

## Statuts

| Statut | Signification |
| - | - |
| `pending` | Créée, la page n'a pas encore été ouverte. |
| `opened` | L'utilisateur a ouvert la page. |
| `completed` | Terminée : `result` contient ce qu'elle a produit. |
| `failed` | L'étape a échoué : `error` dit pourquoi. |
| `cancelled` | Vous l'avez annulée avec `DELETE /hosted-sessions/{id}`. |
| `expired` | Non terminée avant `expires_at`. |

Une session ne sert qu'**une** issue : une fois terminée, échouée, annulée ou expirée, son lien cesse de fonctionner. Créez une nouvelle session pour réessayer.

## Résultat

Pour les deux objectifs, `result` liste les canaux connectés, au même format que `GET /channels` :

```json theme={null}
{
  "channels": [
    {
      "type": "whatsapp",
      "id": "532867649916076",
      "name": "+237 6 99 99 99 99 (Acme)",
      "enabled": true,
      "agent": { "id": "AGI-XXXXX", "name": "Support" },
      "settings": null,
      "created_at": "2026-10-24T09:20:02+00:00"
    }
  ]
}
```

Conservez l'`id` du canal : c'est le `channel_id` depuis lequel vous envoyez les messages. Un webhook `channel.connected` est aussi envoyé pour chaque nouveau canal.

## Autres endpoints

| Endpoint | Usage |
| - | - |
| `GET /hosted-sessions` | Vos sessions, les plus récentes d'abord, filtrables par `purpose`. |
| `GET /hosted-sessions/{id}` | Une session, avec son statut et son résultat. |
| `DELETE /hosted-sessions/{id}` | Annuler une session non terminée : le lien cesse de fonctionner. |

Voir le guide [Connecter le WhatsApp d'un client](https://docs.shortext.ny-corp.io/fr/api-reference/guides/connect-whatsapp.md).


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