> ## 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. # Démarrer une conversation et répondre > Écrivez en premier à un contact, répondez dans une conversation existante et respectez la règle des 24 heures de WhatsApp. Demande une clé avec **Envoyer des messages**. ## Écrire en premier à un contact `POST /conversations` envoie un premier message depuis l'un de vos canaux et ouvre la conversation (ou poursuit celle qui existe avec ce contact). | Champ | Description | | - | - | | `channel` | `whatsapp`, `mail` ou `shortext`. | | `channel_id` | Votre canal, issu de `GET /channels`. | | `contact` | La personne à qui vous écrivez, voir [Format des contacts](https://docs.shortext.ny-corp.io/fr/api-reference/contact-format.md). | | `message` | Ce que vous envoyez, voir [Format des messages](https://docs.shortext.ny-corp.io/fr/api-reference/message-format.md). | | `handover` | `true` si une personne suit la conversation : l'agent IA ne répondra pas au contact. Par défaut `false` : l'agent répond aux réponses. | ```bash cURL theme={null} curl -X POST https://shortext.ny-corp.io/api/v2.0/conversations \ -H "Authorization: Bearer $SHORTEXT_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "channel": "whatsapp", "channel_id": "532867649916076", "contact": { "identifier": "237699999999", "profile": { "firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr" } }, "message": { "type": "template", "content": { "template_name": "order_update", "language": "fr", "body": { "name": "Brice", "order": "A-1042" } } } }' ``` ```php PHP theme={null} post('https://shortext.ny-corp.io/api/v2.0/conversations', [ 'headers' => [ 'Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json', ], 'json' => [ 'channel' => 'whatsapp', 'channel_id' => '532867649916076', 'contact' => [ 'identifier' => '237699999999', 'profile' => ['firstname' => 'Brice', 'lastname' => 'Mbarga', 'preferred_language' => 'fr'], ], 'message' => [ 'type' => 'template', 'content' => [ 'template_name' => 'order_update', 'language' => 'fr', 'body' => ['name' => 'Brice', 'order' => 'A-1042'], ], ], ], ]); $result = json_decode((string) $response->getBody(), true); if (!$result['success']) { throw new RuntimeException("Shortext error {$result['code']}: {$result['message']}"); } $conversationId = $result['body']['conversation']['id']; ``` ```javascript Node.js theme={null} const response = await fetch("https://shortext.ny-corp.io/api/v2.0/conversations", { method: "POST", headers: { Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", }, body: JSON.stringify({ channel: "whatsapp", channel_id: "532867649916076", contact: { identifier: "237699999999", profile: { firstname: "Brice", lastname: "Mbarga", preferred_language: "fr" }, }, message: { type: "template", content: { template_name: "order_update", language: "fr", body: { name: "Brice", order: "A-1042" }, }, }, }), }); const result = await response.json(); if (!result.success) { throw new Error(`Shortext error ${result.code}: ${result.message}`); } const conversationId = result.body.conversation.id; ``` ```python Python theme={null} import os import requests response = requests.post( "https://shortext.ny-corp.io/api/v2.0/conversations", headers={ "Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json", }, json={ "channel": "whatsapp", "channel_id": "532867649916076", "contact": { "identifier": "237699999999", "profile": {"firstname": "Brice", "lastname": "Mbarga", "preferred_language": "fr"}, }, "message": { "type": "template", "content": { "template_name": "order_update", "language": "fr", "body": {"name": "Brice", "order": "A-1042"}, }, }, }, ) result = response.json() if not result["success"]: raise RuntimeError(f"Shortext error {result['code']}: {result['message']}") conversation_id = result["body"]["conversation"]["id"] ``` Le `body` de la réponse contient `conversation` et `message`. ## La règle des 24 heures de WhatsApp WhatsApp n'accepte les messages libres (texte, média, interactif) que dans les **24 heures qui suivent le dernier message du contact**. En dehors de cette fenêtre, et pour écrire en premier, vous devez envoyer un **modèle** approuvé. | Endpoint | Hors de la fenêtre de 24 heures | | - | - | | `POST /conversations` avec un message qui n'est pas un modèle | Refusé avec `1002` : « Outside the 24h window opened by the contact, WhatsApp only accepts an approved template ». | | `POST /conversations` avec un modèle | Envoyé. | | `POST /conversations/{id}/messages` (réponse) | Une réponse libre est envoyée sous forme de modèle de notification, pour qu'elle atteigne le contact. | Les boîtes mail et les endpoints Shortext n'ont pas de fenêtre de ce type. > [!TIP] > > Pour décider à l'avance, regardez le dernier message entrant de la conversation (`GET /conversations/{id}/messages`) ou gardez l'heure du dernier webhook `message.received`. ## Répondre dans une conversation `POST /conversations/{id}/messages` avec un `message` : ```bash cURL theme={null} curl -X POST https://shortext.ny-corp.io/api/v2.0/conversations/$CONVERSATION_ID/messages \ -H "Authorization: Bearer $SHORTEXT_API_KEY" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "message": { "type": "text", "content": { "text": "Your order A-1042 has left our warehouse." } }, "handover": false }' ``` ```php PHP theme={null} post("https://shortext.ny-corp.io/api/v2.0/conversations/{$conversationId}/messages", [ 'headers' => ['Authorization' => 'Bearer ' . getenv('SHORTEXT_API_KEY'), 'Accept' => 'application/json'], 'json' => [ 'message' => ['type' => 'text', 'content' => ['text' => 'Your order A-1042 has left our warehouse.']], 'handover' => false, ], ]); $result = json_decode((string) $response->getBody(), true); ``` ```javascript Node.js theme={null} const response = await fetch(`https://shortext.ny-corp.io/api/v2.0/conversations/${conversationId}/messages`, { method: "POST", headers: { Authorization: `Bearer ${process.env.SHORTEXT_API_KEY}`, Accept: "application/json", "Content-Type": "application/json", }, body: JSON.stringify({ message: { type: "text", content: { text: "Your order A-1042 has left our warehouse." } }, handover: false, }), }); const result = await response.json(); ``` ```python Python theme={null} response = requests.post( f"https://shortext.ny-corp.io/api/v2.0/conversations/{conversation_id}/messages", headers={"Authorization": f"Bearer {os.environ['SHORTEXT_API_KEY']}", "Accept": "application/json"}, json={ "message": {"type": "text", "content": {"text": "Your order A-1042 has left our warehouse."}}, "handover": False, }, ) result = response.json() ``` Par défaut, une réponse **prend la conversation en main** (`handover: true`), comme quand une personne répond depuis la boîte de réception : l'agent IA cesse de répondre. Envoyez `"handover": false` pour les notifications automatiques qui ne doivent pas arrêter l'agent. ## Retrouver une conversation `GET /conversations` filtre par `contact` (téléphone, e-mail ou votre propre identifiant), `channel` et `channel_id`, `agent_id`, `status` (`active`, `archived`), `assignee`, `ticket_id` et `updated_since`. Par exemple : ```bash theme={null} curl "https://shortext.ny-corp.io/api/v2.0/conversations?channel=whatsapp&contact=237699999999" \ -H "Authorization: Bearer $SHORTEXT_API_KEY" -H "Accept: application/json" ``` La lecture des conversations demande **Voir les messages**. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.