Referencia de API
Integra enuchat en tus sistemas usando la Tenant API. Gestiona conversaciones, envía mensajes y accede a datos de facturación programáticamente.
Autenticación
Todas las solicitudes a la API se autentican usando una clave API enviada en el encabezado X-Api-Key.
Obtener tu clave API
- Ve a Configuración → Claves API en tu panel
- Haz clic en Crear clave API y dale un nombre
- Copia la clave inmediatamente — solo se muestra una vez
- Almacénala de forma segura (variable de entorno, gestor de secretos)
Realizar solicitudes
Incluye la clave en cada solicitud:
curl -H "X-Api-Key: tak_your_key_here" \
https://api.enuchat.com/api/v1/tenant-api/widgetsTodas las respuestas son JSON. Las respuestas exitosas tienen un campo data. Los errores tienen un campo error con code y message.
Seguridad: Las claves API se hashean (SHA-256) en nuestra base de datos. Nunca almacenamos la clave en texto plano. Trata tu clave como una contraseña — no la incluyas en el código ni la compartas públicamente.
URL base
https://api.enuchat.com/api/v1/tenant-apiTodos los endpoints a continuación son relativos a esta URL base.
Endpoints
POST /conversations/{'{'}id}/messages
Enviar un mensaje a una conversación. El mensaje se entregará al visitante en tiempo real a través del widget de chat.
Cuerpo de la solicitud
{'{'}
"content": "Thanks for reaching out! We'll process your request.",
"role": "system"
}| Campo | Tipo | Descripción |
|---|---|---|
content | string | Obligatorio. El texto del mensaje. |
role | string | system (por defecto) o operator |
Respuesta (201 Created)
{'{'}
"data": {'{'}
"id": "019d6725-abcd-...",
"role": "system",
"content": "Thanks for reaching out!",
"createdAt": "2026-04-11T14:35:00+00:00"
}
}PATCH /conversations/{'{'}id}
Actualizar el estado o la asignación de una conversación.
Cuerpo de la solicitud
{'{'}
"status": "closed"
}| Campo | Tipo | Descripción |
|---|---|---|
status | string | open, pending o closed |
assignedTo | string|null | UUID del operador a asignar, o null para desasignar |
GET /billing/balance
Obtener tu plan actual y el saldo de créditos.
Respuesta
{'{'}
"data": {'{'}
"plan": "pro",
"creditBalance": 4500000,
"totalCreditsAdded": 10000000
}
}Manejo de errores
Los errores devuelven un código de estado diferente de 2xx con un cuerpo JSON:
{'{'}
"error": {'{'}
"code": "NOT_FOUND",
"message": "Conversation not found."
}
}| Estado HTTP | Significado |
|---|---|
401 | Clave API inválida, expirada o ausente |
400 | Cuerpo de solicitud o parámetros inválidos |
404 | Recurso no encontrado (o pertenece a otro tenant) |
500 | Error del servidor |
Casos de uso comunes
Integración con CRM
Consulta nuevas conversaciones y sincroniza los datos del visitante (nombre, email, idioma) con tu CRM. Usa el ID de conversación como referencia externa.
Seguimientos automatizados
Después de que se cierre una conversación, envía un mensaje de seguimiento a través de la API: "¡Gracias por chatear! ¿Hay algo más en lo que podamos ayudarte?"
Alternativa a webhooks
Hasta que los webhooks salientes estén disponibles, consulta el endpoint de conversaciones periódicamente para detectar nuevos mensajes o cambios de estado.
Operaciones masivas
Cierra todas las conversaciones con más de 7 días de antigüedad, asigna conversaciones a operadores según lógica externa, o exporta el historial de conversaciones para análisis.
Límites de frecuencia
La API permite hasta 60 solicitudes por minuto por clave API. Si excedes este límite, recibirás una respuesta 429 Too Many Requests. Espera y reintenta con retroceso exponencial.