La API de Entagl permite que tu propio software trabaje con un workspace de Entagl: contactos, conversaciones, mensajes, reservas, recordatorios, pedidos, productos, llamadas de AI y campañas. Los webhooks avisan a tus sistemas en cuanto ocurre algo. Es la misma API que usa la app de Entagl para Make.

Las solicitudes y las respuestas son JSON sobre HTTPS. Los nombres de campo van en snake_case. Los ID son enteros, salvo que un endpoint indique otra cosa. Las fechas y horas son cadenas ISO 8601; las respuestas usan UTC.

Envía un token con cada solicitud en el encabezado Authorization: Authorization: Bearer <token>. Funcionan dos tipos de token:

Si falta el encabezado, la respuesta es 401 unauthenticated. Una clave incorrecta o revocada responde 401 invalid_api_key. Un token OAuth caducado responde 401 invalid_token: renuévalo y vuelve a intentarlo.

Cada solicitud trabaja con exactamente un workspace. Una clave API siempre usa su propio workspace. Un inicio de sesión OAuth puede pertenecer a varios workspaces (propios, o a los que te uniste como miembro del equipo): envía el encabezado X-Entagl-Workspace con el ID del workspace para elegir uno. Con un solo workspace el encabezado es opcional. GET /me funciona sin el encabezado y lista todos los workspaces que puede usar el inicio de sesión.

Sin el encabezado, un inicio de sesión con varios workspaces recibe 400 workspace_required; un workspace al que el inicio de sesión no tiene acceso responde 403 workspace_forbidden. Un ID que pertenece a otro workspace siempre responde 404 not_found, nunca 403.

Cada endpoint de abajo muestra el permiso que necesita. Los propietarios, los admins y las claves API pasan todas las comprobaciones. Los miembros del equipo pasan cuando su rol tiene ese permiso marcado en los ajustes del equipo: contacts, inbox, calendar, orders, business_pages, call_agent, campaigns o integrations. Sin él, la API responde 403 insufficient_permissions.

Envía los cuerpos como JSON con Content-Type: application/json. La mayoría de los endpoints rechazan con 422 los campos desconocidos del cuerpo, así que un error de escritura nunca pasa en silencio. Todos los errores tienen la misma forma: un code estable para ramificar la lógica, un message legible y, en los errores de validación, una lista details que señala cada campo incorrecto.

Las rutas marcadas como Formato de respuesta heredado son anteriores a estas convenciones: devuelven objetos o arrays JSON simples y responden la mayoría de los errores como { "message": "…" }.

Los endpoints marcados como Paginado devuelven primero los elementos más recientes, dentro de un envoltorio de lista. Pide hasta 100 elementos con limit (25 por defecto). Cuando has_more es true, pasa next_cursor como starting_after para obtener la página siguiente. Las demás listas devuelven todo de una vez con has_more: false.

Todo endpoint POST con el formato estándar acepta la cabecera Idempotency-Key (hasta 200 caracteres). Usa un valor único por operación, como un UUID. Entagl guarda la primera respuesta durante 24 horas: un reintento con la misma clave y el mismo cuerpo devuelve esa respuesta con Idempotent-Replayed: true, y nada se ejecuta dos veces. Las rutas marcadas como Formato de respuesta heredado funcionan de otra forma, mira abajo.

• La misma clave con un cuerpo distinto responde 409 idempotency_key_reused.
• Mientras la primera solicitud sigue en curso, o si nunca terminó, un reintento responde 409 request_in_progress. Comprueba el resultado y reintenta con una clave nueva.
• Se guarda todo resultado, también los errores. Para repetir una solicitud fallida, usa una clave nueva.
• Las claves son propias del workspace y de la credencial.

Rutas heredadas. POST /messages también acepta Idempotency-Key (o un message_id en el cuerpo): reintentar un mensaje que ya aceptó responde 202 con el mismo conversationId y no se procesa dos veces, y la misma clave con otro cuerpo responde 409. POST /chat no tiene protección contra reintentos: un reintento vuelve a ejecutar la IA, así que revisa el resultado antes de reintentar.

Cada workspace puede hacer 120 solicitudes por minuto, compartidas entre todas sus claves API y conexiones. Las respuestas incluyen RateLimit-Limit, RateLimit-Remaining y RateLimit-Reset (segundos hasta que se reinicia la ventana). Si superas el límite recibes 429 rate_limited con un encabezado Retry-After: espera esos segundos y reintenta. Las rutas heredadas del canal API no cuentan para este límite.