Messagerie

Lisez les messages privés reçus par vos Pages Facebook (Messenger) et vos comptes Instagram, et répondez-y au nom du compte. Les mêmes conversations que dans Messages, du tableau de bord : une réponse envoyée ici y apparaît aussitôt.

Principe

GET

/v1/conversations

Lister les conversations, celles à traiter d’abord

GET

/v1/conversations/:id

Lire l’échange

POST

/v1/conversations/:id/messages

Répondre au nom du compte

Lire demande le scope accounts:read ou publish:posts ; répondre demande publish:posts et une formule payante. Lire ne marque rien comme lu. Une réponse envoyée marque la conversation comme lue et met l'agent IA en pause dans cette conversation, comme une réponse écrite dans Messages.

Meta n'accepte une réponse que dans les 24 heures qui suivent le dernier message du client. Chaque conversation donne cette heure limite (replyBefore) ; passé ce délai, rien ne part (reply_window_closed) jusqu'à ce que le client écrive de nouveau.

Lister les conversations

Paramètre	Description
`filter`	to_handle (par défaut) : celles qui attendent une réponse, la limite la plus proche en tête. unread : celles qui ont des messages non lus. all : toutes, la plus récente en tête
`platform`	facebook ou instagram : un seul réseau
`limit`	Nombre de conversations : 20 par défaut, 50 au plus

curl "https://api.kreatoai.com/v1/conversations?filter=to_handle" \
  -H "x-api-key: sk-kre-v1-votre_cle"

// 200 OK
{
  "filter": "to_handle",
  "total": 3,
  "conversations": [
    {
      "id": "5b0e2f61-8c3a-4d7e-9a12-3f4c6d8e1b20",
      "contact": "Awa Diallo",
      "platform": "instagram",
      "unread": 2,
      "needsReply": true,
      "canReply": true,
      "replyBefore": "2026-11-04T09:12:40.000Z",
      "escalated": false,
      "agent": "off",
      "lastMessage": { "from": "customer", "text": "Il reste des places samedi ?", "at": "2026-11-03T09:12:40.000Z" }
    }
  ]
}

Champ	Description
`needsReply`	Le client a eu le dernier mot, ou l'agent IA a passé la main
`replyBefore`	Heure limite de réponse fixée par Meta, 24 h après le dernier message du client ; null quand elle est passée
`canReply`	Une réponse peut encore partir
`escalated`	L'agent IA a passé la main à l'équipe
`agent`	off (l'agent IA est éteint sur ce réseau et ne répond à personne), active, paused (une personne a répondu récemment) ou excluded (l'agent ne répond jamais à ce contact)
`from`	customer (le client), team (le compte, depuis Kreatoai, Facebook ou une IA reliée) ou agent (l'agent IA de Kreatoai)
`workspace`	Présent quand la connexion voit plusieurs espaces : celui de la conversation

Lire une conversation

GET /v1/conversations/5b0e2f61-8c3a-4d7e-9a12-3f4c6d8e1b20?limit=30

// 200 OK
{
  "conversation": { "id": "5b0e2f61-…", "contact": "Awa Diallo", "platform": "instagram", "canReply": true, "…": "…" },
  "messages": [
    { "from": "customer", "text": "Bonjour, vous faites des cours le samedi ?", "at": "2026-11-03T09:10:02.000Z" },
    { "from": "customer", "text": "Il reste des places samedi ?", "at": "2026-11-03T09:12:40.000Z" }
  ]
}

Les derniers messages, du plus ancien au plus récent : 30 par défaut, 100 au plus. Une image, une vidéo ou un fichier reçu porte son type, sans son adresse.

Répondre

curl -X POST https://api.kreatoai.com/v1/conversations/5b0e2f61-8c3a-4d7e-9a12-3f4c6d8e1b20/messages \
  -H "x-api-key: sk-kre-v1-votre_cle" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Bonjour ! Oui, il reste des places samedi à 10 h." }'

// 201 Created
{
  "id": "e41c9a07-2d5b-4f8e-b3a6-91c0d7e2f458",
  "conversationId": "5b0e2f61-8c3a-4d7e-9a12-3f4c6d8e1b20",
  "sentAt": "2026-11-03T09:20:11.000Z",
  "agentPausedUntil": "2026-11-03T21:20:11.000Z"
}

Le message part tout de suite, au nom du compte à qui le client a écrit. Du texte seul : 2 000 caractères au plus sur Messenger, 1 000 sur Instagram. Un message par appel.

Erreurs

Code	Signification
`reply_window_closed`	Le dernier message du client a plus de 24 heures : Meta refuse la réponse. Rien n'est envoyé
`conversation_not_found`	La conversation n'existe pas, ou n'est pas dans un espace de cette connexion
`message_too_long`	Message au delà de la limite du réseau
`message_send_failed`	Facebook ou Instagram a refusé le message ; message dit pourquoi. Rien n'est envoyé
`channel_needs_reauth`	L'accès au compte a expiré : renouvelez-le
`subscription_required`	Répondre demande une formule payante