Autenticación

La API de Zelta Chat utiliza autenticación basada en tokens de acceso. Cada petición debe incluir un token válido en el header HTTP api_access_token.

URL base

https://chat.zelta.dev/api/v1

Todas las URLs de la API en esta documentación son relativas a esta URL base. Las rutas incluyen el account_id de tu cuenta:

https://chat.zelta.dev/api/v1/accounts/{account_id}/...

Obtener tu Account ID

El account_id es un identificador numérico que forma parte de todas las rutas de la API. Puedes encontrarlo de dos formas:

1. En la URL: Inicia sesión en y observa la URL del navegador. El número que aparece después de /app/accounts/ es tu account_id.
2. En Ajustes: Ve a Ajustes > Cuenta y busca el identificador de cuenta.

Obtener un token de acceso

Paso 1: Iniciar sesión

Inicia sesión en con tus credenciales.

Paso 2: Ir a tu perfil

Haz clic en tu avatar (esquina inferior izquierda) y selecciona Perfil, o navega a Ajustes > Perfil.

Paso 3: Copiar el token

En la sección Token de acceso, encontrarás tu token. Cópialo con el botón correspondiente.

Seguridad

Tu token de acceso otorga los mismos permisos que tu cuenta de usuario. Trátalo como una contraseña: no lo compartas ni lo expongas en código del lado del cliente.

Regenerar el token

Si necesitas invalidar tu token actual, haz clic en Restablecer en la misma sección. Se generará un nuevo token y el anterior dejará de funcionar de inmediato.

Usar el token en peticiones

Incluye el token en el header api_access_token de cada petición:

curl -X GET "https://chat.zelta.dev/api/v1/accounts/{account_id}/conversations" \
  -H "api_access_token: {tu_token}" \
  -H "Content-Type: application/json"

Nota

El header se llama api_access_token (no Authorization ni Bearer). Asegúrate de usar exactamente este nombre.

Ejemplo: obtener el perfil del usuario autenticado

curl -X GET "https://chat.zelta.dev/api/v1/profile" \
  -H "api_access_token: {tu_token}"

Ejemplo: listar conversaciones

curl -X GET "https://chat.zelta.dev/api/v1/accounts/{account_id}/conversations" \
  -H "api_access_token: {tu_token}" \
  -H "Content-Type: application/json"

Ejemplo: enviar un mensaje

curl -X POST "https://chat.zelta.dev/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages" \
  -H "api_access_token: {tu_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hola, ¿en qué puedo ayudarte?",
    "message_type": "outgoing"
  }'

Tipos de token

Existen dos tipos de tokens de acceso, cada uno con diferentes niveles de permisos:

Tokens de usuario

Son los tokens que se generan desde el perfil del usuario. Los permisos dependen del rol asignado:

Rol	Acceso
Administrador	Acceso completo a todos los endpoints de la API: conversaciones, contactos, canales, agentes, equipos, reportes, configuración y más.
Agente	Acceso limitado a las conversaciones asignadas, sus contactos asociados y las acciones propias de su rol (responder mensajes, cambiar estado, etc.).

Tokens de Agent Bot

Los Agent Bots son integraciones automatizadas que pueden interactuar con las conversaciones. Sus tokens se generan al crear un Agent Bot desde la API o la interfaz de administración, y tienen permisos limitados a:

• Consultar y gestionar conversaciones
• Enviar y recibir mensajes
• Actualizar el estado de conversaciones
• Asignar conversaciones a agentes o equipos

Roles y permisos

En lugar de scopes estilo OAuth, la API respeta los permisos del rol asignado al usuario propietario del token:

Capacidad	Administrador	Agente
Listar todas las conversaciones	Sí	Solo las asignadas
Gestionar contactos	Sí	Solo los propios
Crear y configurar canales	Sí	No
Administrar agentes y equipos	Sí	No
Acceder a reportes	Sí	No
Enviar mensajes en conversaciones asignadas	Sí	Sí
Cambiar estado de conversaciones	Sí	Sí (las asignadas)
Configuración de la cuenta	Sí	No

Principio de mínimo privilegio

Si tu integración solo necesita enviar y recibir mensajes, considera usar un token de Agent Bot o un usuario con rol de agente, en lugar de un token de administrador.

Límites de tasa (Rate Limiting)

La API implementa límites de tasa para garantizar la estabilidad del servicio.

Límites generales

Tipo de límite	Valor
Peticiones generales	3,000 por minuto por IP
Búsqueda de contactos	100 por minuto por IP
Reportes	100 por minuto por usuario

Respuesta al exceder el límite

Cuando se excede el límite, la API retorna un código HTTP 429 (Too Many Requests).

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Límite excedido

Si recibes un error 429, espera el tiempo indicado antes de reintentar. Implementa un mecanismo de reintento con retroceso exponencial (exponential backoff) para manejar estos errores de manera elegante.

Errores de autenticación

Código HTTP	Significado	Causa habitual
401	No autorizado	El token es inválido, fue regenerado o no se incluyó en la petición.
403	Prohibido	El usuario no tiene permisos suficientes para la operación solicitada (por ejemplo, un agente intentando acceder a endpoints de administrador).
429	Demasiadas peticiones	Se excedió el límite de tasa. Espera antes de reintentar.

Ejemplo de error 401

{
  "errors": [
    "Token inválido o no proporcionado. Verifica tu header api_access_token."
  ]
}

Ejemplo de error 403

{
  "error": "Acceso denegado. Tu rol no tiene permisos para esta operación."
}

Buenas prácticas de seguridad

• Nunca expongas tu token de acceso en código del lado del cliente (frontend, apps móviles, repositorios públicos).
• Almacena los tokens en variables de entorno o un gestor de secretos.
• Regenera tus tokens periódicamente, especialmente si sospechas que pudieron haber sido comprometidos.
• Usa HTTPS exclusivamente; todas las peticiones a la API deben realizarse sobre conexiones seguras.
• Asigna el rol mínimo necesario al usuario cuyo token utilizarás en tu integración.
• Para integraciones automatizadas, prefiere tokens de Agent Bot sobre tokens de administrador.