L’API Entagl permet à votre propre logiciel de travailler avec un workspace Entagl : contacts, conversations, messages, réservations, rappels, commandes, produits, appels AI et campagnes. Les webhooks avertissent vos systèmes dès que quelque chose se passe. C’est la même API que celle de l’application Entagl pour Make.

Les requêtes et les réponses sont en JSON sur HTTPS. Les noms de champ sont en snake_case. Les ID sont des entiers, sauf indication contraire d’un endpoint. Les dates et heures sont des chaînes ISO 8601 ; les réponses utilisent UTC.

Envoyez un jeton avec chaque requête dans l’en-tête Authorization : Authorization: Bearer <token>. Deux types de jeton fonctionnent :

Un en-tête manquant renvoie 401 unauthenticated. Une clé incorrecte ou révoquée renvoie 401 invalid_api_key. Un jeton OAuth expiré renvoie 401 invalid_token : renouvelez-le et réessayez.

Chaque requête agit sur un seul workspace. Une clé API utilise toujours son propre workspace. Une connexion OAuth peut appartenir à plusieurs workspaces (dont vous êtes propriétaire, ou que vous avez rejoints comme membre de l’équipe) : envoyez l’en-tête X-Entagl-Workspace avec l’ID du workspace pour en choisir un. Avec un seul workspace, l’en-tête est facultatif. GET /me fonctionne sans l’en-tête et liste tous les workspaces que la connexion peut utiliser.

Sans l’en-tête, une connexion à plusieurs workspaces reçoit 400 workspace_required ; un workspace auquel la connexion n’a pas accès renvoie 403 workspace_forbidden. Un ID qui appartient à un autre workspace renvoie toujours 404 not_found, jamais 403.

Chaque endpoint ci-dessous indique la permission requise. Les propriétaires, les admins et les clés API passent toutes les vérifications. Les membres de l’équipe passent quand leur rôle a cette permission cochée dans les paramètres de l’équipe : contacts, inbox, calendar, orders, business_pages, call_agent, campaigns ou integrations. Sans elle, l’API renvoie 403 insufficient_permissions.

Envoyez les corps en JSON avec Content-Type: application/json. La plupart des endpoints rejettent avec 422 les champs inconnus du corps : une faute de frappe ne passe donc jamais inaperçue. Chaque erreur a la même forme : un code stable sur lequel brancher votre logique, un message lisible et, pour les erreurs de validation, une liste details qui désigne chaque champ incorrect.

Les routes marquées Ancien format de réponse sont antérieures à ces conventions : elles renvoient de simples objets ou tableaux JSON et répondent à la plupart des erreurs sous la forme { "message": "…" }.

Les endpoints marqués Paginé renvoient d’abord les éléments les plus récents, dans une enveloppe de liste. Demandez jusqu’à 100 éléments avec limit (25 par défaut). Quand has_more vaut true, passez next_cursor comme starting_after pour obtenir la page suivante. Les autres listes renvoient tout d’un coup avec has_more: false.

Chaque endpoint POST au format standard accepte l'en-tête Idempotency-Key (200 caractères maximum). Utilisez une valeur unique par opération, par exemple un UUID. Entagl conserve la première réponse pendant 24 heures : une nouvelle tentative avec la même clé et le même corps renvoie cette réponse avec Idempotent-Replayed: true, et rien ne s'exécute deux fois. Les routes marquées Ancien format de réponse fonctionnent autrement, voir ci-dessous.

• La même clé avec un corps différent renvoie 409 idempotency_key_reused.
• Tant que la première requête est en cours, ou si elle ne s’est jamais terminée, une nouvelle tentative renvoie 409 request_in_progress. Vérifiez le résultat, puis réessayez avec une nouvelle clé.
• Chaque résultat est conservé, erreurs comprises. Pour relancer une requête échouée, utilisez une nouvelle clé.
• Les clés sont propres au workspace et à l’identifiant d’accès.

Anciennes routes. POST /messages accepte aussi Idempotency-Key (ou un message_id dans le corps) : une nouvelle tentative pour un message déjà accepté répond 202 avec le même conversationId et n'est pas traitée deux fois, et la même clé avec un autre corps répond 409. POST /chat n'a aucune protection contre les doublons : une nouvelle tentative relance l'IA, vérifiez donc le résultat avant de réessayer.

Chaque workspace peut faire 120 requêtes par minute, partagées entre toutes ses clés API et connexions. Les réponses contiennent RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes avant la réinitialisation de la fenêtre). Au-delà de la limite, vous recevez 429 rate_limited avec un en-tête Retry-After : attendez ce nombre de secondes, puis réessayez. Les anciennes routes du canal API ne comptent pas dans cette limite.