Canal API
Conecta Entagl a tu propia app o a Make: envía mensajes, recibe respuestas y gestiona tu workspace.
Descripción general
El canal API te permite usar el mismo agente de AI que impulsa tus DMs desde el chat de tu propio sitio web, app móvil o backend. Envías un mensaje, el agente piensa (con el mismo buffering y respuestas humanas de varios mensajes que un DM real), y la respuesta te llega un poco más tarde, mediante un callback webhook o por polling. Configúralo en Canales → API: genera una API key, activa el canal y luego elige callback o polling. La misma API también permite que tu desarrollador, o Make, trabaje con contactos, conversaciones, reservas, pedidos y más. Consulta la pestaña Workspace API.
Pestañas de esta página
La API no es solo para chat. Tu desarrollador, o una herramienta como Make, puede usarla para leer y actualizar gran parte de tu workspace.
Qué puedes hacer con ella
Además de enviar mensajes, la API cubre:
- Contacts: crear, actualizar, buscar, fusionar, añadir notas, marcar como do-not-contact
- Tags y lifecycle stages: añadir o quitar tags, mover un contacto a otra etapa
- Conversations: asignar a un compañero, cerrar con una nota de cierre, pausar o reanudar la AI, añadir comentarios del equipo, enviar un mensaje como tu empresa
- Bookings y reminders: ver horarios libres, reservar, reprogramar, cancelar, crear y cerrar reminders
- Orders y products: crear y actualizar pedidos y sus items, gestionar tu catálogo
- Calls: iniciar una llamada telefónica con AI o ponerla en cola, leer el resultado
- Campaigns: ver tus campañas y enviar una
Cuando algo cambia, Entagl puede avisar a tus herramientas al instante mediante webhooks.
Dos formas de iniciar sesión
Make. Cuando conectas Make, inicias sesión con tu propia cuenta de Entagl. Make actúa entonces como tú, con exactamente tus permisos: un owner o admin puede hacer todo, un team member solo lo que permitan sus privilegios. Si tu login tiene más de un workspace, eliges cuál usar.
API key. Para tu propio servidor, crea una key en Canales → API o Configuración → API keys y envíala como Authorization: Bearer <your key>. Una key pertenece a un solo workspace y tiene acceso completo de owner a él, así que trátala como una contraseña.
Seguro para reintentar: el header Idempotency-Key
A veces una solicitud se procesa, pero la respuesta se pierde en el camino de vuelta. Si tu sistema no está seguro de que una solicitud funcionó, puede enviarla otra vez con el mismo header Idempotency-Key. Durante 24 horas Entagl reconoce la key, omite el trabajo y devuelve la primera respuesta, para que no acabes con dos pedidos o dos contactos. Usar la misma key para una solicitud diferente se rechaza con un error.
Cuántas solicitudes puedes enviar
Hasta 120 solicitudes por minuto para cada workspace. Si superas eso, Entagl responde con error 429 (rate_limited). Espera un momento e inténtalo de nuevo. La mayoría de las automatizaciones ni se acercan.
La referencia completa de la API
Cada endpoint, campo y código de error está listado en la referencia de la API de Entagl. Ábrelo con el enlace Para desarrolladores: referencia de API cerca de la parte superior de esta página y compártelo con tu desarrollador.
Funciones
Configuración y autenticación
Abre Configuración → Integraciones, elige API y haz clic en Generar clave API. Activa el interruptor en la tarjeta del Canal API, luego llama a la API en https://api.entagl.com con el encabezado Authorization: Bearer <tu clave>. Cada clave funciona solo para un espacio de trabajo.
Enviar un mensaje
Haz POST a /api/v1/messages con { message, externalUserId }. Obtienes un 202 y un conversationId de inmediato. Reutiliza ese conversationId para continuar la conversación. La respuesta del agente llega después, no en esta respuesta.
Webhook (callback) (recomendado)
Pega una URL de callback en la tarjeta del Canal API y haz clic en Guardar. Entagl luego envía cada respuesta del agente a ella, firmada con el encabezado X-Entagl-Signature (HMAC-SHA256). Usa una dirección HTTPS pública y haz clic en Enviar entrega de prueba para verificar que funcione. Tu servidor debe verificar la firma y responder con un código 2xx en aproximadamente 5 segundos. Los callbacks fallidos no se reintentan.
Sondeo (Polling)
Si no puedes alojar una URL de callback, llama a GET /api/v1/conversations/:id/messages?since=<cursor> para obtener las respuestas nuevas. Pasa el cursor de cada respuesta como ?since= para recibir solo mensajes nuevos.
Seguridad y aislamiento
Las API keys se almacenan con hash y el secreto de firma se cifra (ambos se muestran solo una vez). Cada consulta está limitada al workspace: un ID de conversación de otro workspace devuelve 404, y no puedes pasar un user ID (se deriva de tu key).
Tareas comunes
Configurar el canal API
Acerca de 3 min- Abre Configuración → Integraciones, elige API y haz clic en Generar clave API. Dale un nombre si lo deseas, luego copia la clave ahora, porque solo se muestra una vez.
- Activa el interruptor en el encabezado de la tarjeta del Canal API. Hasta que esté activado, los mensajes enviados a la API son rechazados.
- Recomendado: abre la configuración de la tarjeta, pega tu URL de callback y haz clic en Guardar. Copia el secreto de firma que aparece, luego haz clic en Enviar entrega de prueba.
- Desde tu app, envía mensajes con POST a https://api.entagl.com/api/v1/messages y recibe las respuestas por callback o por sondeo.
Consejos
Preguntas frecuentes
¿Te fue útil esta página?