Démarrer une conversation et répondre

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.
`message`	Ce que vous envoyez, voir Format des messages.
`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.

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
$response = (new GuzzleHttp\Client())->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'];

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;

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.

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 :

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
$response = (new GuzzleHttp\Client())->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);

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();

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 :

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.

Démarrer

Formats

Intégrations

Guides

Endpoints

Démarrer une conversation et répondre

Écrire en premier à un contact

La règle des 24 heures de WhatsApp

Répondre dans une conversation

Retrouver une conversation

​Écrire en premier à un contact

​La règle des 24 heures de WhatsApp

​Répondre dans une conversation

​Retrouver une conversation

Écrire en premier à un contact

La règle des 24 heures de WhatsApp

Répondre dans une conversation

Retrouver une conversation