API REST · EasyLiveChat

§ 00Ce qu'est l'API REST

EasyLiveChat expose une API REST sur /api/v1/* pour que du code externe — votre propre backend, une intégration CRM, un flux Zapier ou n8n, un script de migration — puisse lire et écrire dans votre espace sans qu'un agent humain soit connecté. Chaque appel est authentifié par une clé API générée dans le tableau de bord et à portée de tenant.

Si vous avez déjà appelé l'API de Stripe, Slack ou GitHub, cela fonctionne pareil : un jeton secret de longue durée dans un en-tête Authorization, des corps de requête et de réponse JSON, des codes de statut HTTP prévisibles.

Une clé API ne porte jamais de 2FA ni de mot de passe — c'est tout l'intérêt. C'est un identifiant que vous intégrez dans un autre logiciel pour qu'il agisse au nom de votre tenant, uniquement avec les portées que vous lui accordez.

§ 01Disponibilité par plan

L'API REST est disponible sur tous les plans payants et débloquée pendant l'essai de 14 jours. Pas de facturation à l'appel.

À l'expiration de l'essai, l'API passe en lecture seule — les écritures renvoient 402 jusqu'à la mise à niveau de l'espace. Les lectures continuent de fonctionner pour ne jamais casser vos exports historiques.

§ 02Authentification

Créez une clé depuis https://app.livechattools.com/settings/api-keys. Choisissez le plus petit ensemble de portées dont l'intégration a vraiment besoin. Vous pouvez révoquer une clé depuis la même page à tout moment — elle cesse de fonctionner instantanément, sans aucun effet sur le tableau de bord ou les connexions mobiles de vos agents.

Transmettez la clé à chaque requête, soit en tant que jeton Bearer, soit via x-api-key :

Authorization: Bearer plk_<your-key>
# — or, equivalently —
x-api-key: plk_<your-key>

Vérifiez que la clé fonctionne avant de la câbler quelque part — /me renvoie vos portées et votre tenant :

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<your-key>"

La clé brute n'est affichée qu'une seule fois à la création. Perdue ? Révoquez-la et créez-en une nouvelle — il n'y a aucun moyen de récupérer la valeur d'origine.

§ 03Portées (scopes)

Les portées sont vérifiées à chaque requête. Une clé avec uniquement des portées :read ne peut jamais muter les données par accident — utile pour des dashboards en lecture seule, des exports BI ou des pipelines analytiques.

Portée	Permet
conversations:read	Lister et lire les conversations et leurs messages.
conversations:write	Fermer, rouvrir ou réaffecter des conversations.
messages:read	Lire l'historique des messages d'une conversation.
messages:write	Envoyer un nouveau message en tant qu'agent.
contacts:read	Lister et rechercher des contacts.

Principe du moindre privilège — une clé par intégration. Une clé en lecture seule fuitée sur votre pipeline de reporting fait beaucoup moins de dégâts qu'une seule clé "tout-puissante" partagée dans toute votre stack.

§ 04Endpoints

Tous les chemins partent de /api/v1. Les réponses sont en JSON. Les heures sont en ISO 8601 UTC.

`GET /api/v1/me`

Renvoie l'identité de la clé et le tenant. Aucune portée requise — utile pour tester la connexion.

curl https://api.livechattools.com/api/v1/me \
  -H "Authorization: Bearer plk_<key>"

{
  "apiKeyId": "ck...",
  "scopes": ["conversations:read","messages:write"],
  "tenant": { "id": "...", "name": "Acme", "slug": "acme", "planTier": "GROWTH" }
}

`GET /api/v1/conversations`

Liste les conversations, plus récentes d'abord. Tous les filtres sont optionnels.

?status= OPEN · SNOOZED · CLOSED
?channel= WIDGET · WHATSAPP · TELEGRAM · MESSENGER · INSTAGRAM
?limit= 1–200, défaut 50
?cursor= id de la dernière ligne de la page précédente

curl "https://api.livechattools.com/api/v1/conversations?status=OPEN&limit=50" \
  -H "Authorization: Bearer plk_<key>"

{
  "data": [
    { "id":"...", "sourceChannel":"WHATSAPP", "status":"OPEN",
      "lastMessagePreview":"hi there", "lastMessageAt":"..." }
  ],
  "nextCursor": "..."
}

`GET /api/v1/conversations/:id`

Récupère une conversation avec son contact attaché.

`GET /api/v1/conversations/:id/messages`

Historique de messages paginé pour une conversation, plus récents d'abord.

curl "https://api.livechattools.com/api/v1/conversations/<id>/messages?limit=50" \
  -H "Authorization: Bearer plk_<key>"

`POST /api/v1/conversations/:id/messages`

Envoyez un message sortant sur une conversation. Il est distribué au canal correspondant (widget, WhatsApp, Telegram, Messenger, Instagram) exactement comme le ferait la réponse d'un agent humain.

curl -X POST "https://api.livechattools.com/api/v1/conversations/<id>/messages" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "body": "Your order has shipped." }'

# → 201 Created
{ "message": { "id":"...", "senderType":"AGENT", "body":"Your order has shipped.", "createdAt":"..." } }

senderAgentId est optionnel — s'il est omis, le message est attribué au premier OWNER ou ADMIN actif de l'espace. Passez un id explicite lorsque vous souhaitez qu'un compte bot spécifique apparaisse dans la conversation.

`PATCH /api/v1/conversations/:id`

Met à jour le statut d'une conversation (OPEN · SNOOZED · CLOSED) ou son agent assigné. Passez assignedAgentId: null pour désassigner.

curl -X PATCH "https://api.livechattools.com/api/v1/conversations/<id>" \
  -H "Authorization: Bearer plk_<key>" \
  -H "Content-Type: application/json" \
  -d '{ "status": "CLOSED" }'

`GET /api/v1/contacts`

Liste les contacts de l'espace. ?q= cherche dans nom, e-mail ou téléphone.

curl "https://api.livechattools.com/api/v1/contacts?q=acme" \
  -H "Authorization: Bearer plk_<key>"

§ 05Pagination

Tous les endpoints de liste utilisent la pagination par curseur. La forme de la réponse est :

{
  "data": [ /* up to ?limit= rows */ ],
  "nextCursor": "<id of last row>"   // or null when there are no more
}

Pour récupérer la page suivante, passez nextCursor en tant que ?cursor= dans la requête suivante. Quand nextCursor vaut null, vous êtes à la fin.

§ 06Erreurs

Les erreurs renvoient toujours un corps JSON avec un code d'erreur et (si utile) un message lisible. Le statut HTTP reflète la signification :

Statut	Code	Signification
401	UNAUTHENTICATED	Clé manquante, mal formée ou révoquée.
402	TRIAL_EXPIRED	Essai expiré — les écritures sont bloquées, les lectures fonctionnent encore.
403	FORBIDDEN	La clé est valide mais il manque la portée nécessaire pour cet endpoint.
404	NOT_FOUND	La conversation, le contact ou une autre ressource n'existe pas dans votre tenant.
400	INVALID_BODY	Le corps de la requête manque de champs requis ou a les mauvais types.
429	RATE_LIMITED	Trop de requêtes — patientez et réessayez dans quelques secondes.

§ 07Webhooks (compagnon)

L'API REST est parfaite pour tirer et pousser selon votre planning. Pour les notifications push lorsqu'il se passe quelque chose côté EasyLiveChat — nouveau message client, conversation fermée, agent rejoignant — configurez des webhooks sortants dans Paramètres → Webhooks.

Les messages envoyés via POST /api/v1/conversations/:id/messages déclenchent aussi le webhook message.created, donc si vous avez à la fois une intégration qui envoie et une autre qui écoute, vous verrez vos propres écritures vous revenir par le canal webhook.

§ 08Limites de débit

Chaque tenant dispose de jusqu'à 240 requêtes par minute par chemin, partagées entre toutes les clés de ce tenant. Atteindre la limite renvoie 429 avec un en-tête Retry-After.

Si votre intégration a légitimement besoin d'un plafond plus élevé (import en masse, envoi de masse), écrivez au support — nous l'augmenterons pour votre tenant.

Suggérer une modification