Autenticacion

La API de Zelta Chat utiliza autenticacion basada en tokens Bearer (OAuth 2.0) para proteger el acceso a los recursos. Todas las peticiones a la API deben incluir un token valido.

URL base

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

Todas las URLs de la API en esta documentacion son relativas a esta URL base.

Obtener un token de acceso

Paso 1: Crear una aplicacion API

1. Inicia sesion en .
2. Ve a Ajustes > API > Aplicaciones.
3. Haz clic en + Nueva aplicacion.
4. Completa los datos:
   • Nombre de la aplicacion
   • URL de redireccion (para flujo OAuth)
   • Scopes requeridos
5. Guarda y copia tu client_id y client_secret.

Seguridad

El client_secret solo se muestra una vez al momento de crearlo. Guardalo en un lugar seguro. Si lo pierdes, deberas generar uno nuevo.

Paso 2: Solicitar un token

Realiza una peticion POST al endpoint de autenticacion:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "tu_client_id",
    "client_secret": "tu_client_secret",
    "scope": "chat:read chat:write"
  }'

Respuesta exitosa

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
  "scope": "chat:read chat:write"
}

Paso 3: Usar el token

Incluye el token en el header Authorization de cada peticion:

curl -X GET https://api.zelta.dev/chat/v1/conversations \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Scopes disponibles

Los scopes controlan que operaciones puede realizar tu aplicacion sobre los recursos de Zelta Chat.

Scope	Descripcion	Permisos
chat:read	Lectura de datos	Consultar conversaciones, mensajes, contactos y canales.
chat:write	Escritura de datos	Enviar mensajes, crear conversaciones, actualizar contactos.
chat:agents	Gestion de agentes	Asignar conversaciones, cambiar estados, gestionar equipos.
chat:channels	Configuracion de canales	Crear, modificar y eliminar canales de comunicacion.
chat:bots	Gestion de bots	Crear y configurar chatbots, gestionar flujos automatizados.
chat:admin	Administracion completa	Todos los permisos anteriores mas configuracion global, eliminacion de registros y gestion de usuarios.

Principio de minimo privilegio

Solicita unicamente los scopes que tu aplicacion necesita. Por ejemplo, si solo necesitas leer conversaciones, usa chat:read en lugar de chat:admin.

Renovacion de tokens

Los tokens tienen una vigencia de 1 hora (3600 segundos). Para renovar:

curl -X POST https://api.zelta.dev/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "refresh_token",
    "refresh_token": "tu_refresh_token",
    "client_id": "tu_client_id"
  }'

Respuesta

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9_nuevo...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "nuevo_refresh_token...",
  "scope": "chat:read chat:write"
}

Consejo

Implementa la renovacion automatica de tokens en tu aplicacion. Renueva el token cuando queden menos de 5 minutos de vigencia para evitar interrupciones.

Errores de autenticacion

Codigo HTTP	Error	Descripcion
401	unauthorized	Token ausente, expirado o invalido.
403	forbidden	El token no tiene los scopes necesarios para esta operacion.
429	rate_limited	Se excedio el limite de peticiones. Espera antes de reintentar.

Ejemplo de error

{
  "error": "unauthorized",
  "message": "El token de acceso ha expirado.",
  "hint": "Solicita un nuevo token usando tu refresh_token o genera uno nuevo con client_credentials."
}

Limites de tasa (Rate Limiting)

Plan	Limite
Starter	100 peticiones/minuto
Business	500 peticiones/minuto
Enterprise	2,000 peticiones/minuto

Los headers de respuesta incluyen informacion sobre tu limite actual:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1709145600

Limite excedido

Si recibes un error 429, espera hasta el tiempo indicado en X-RateLimit-Reset antes de reintentar. Implementa un mecanismo de reintento exponencial (exponential backoff) para manejar estos errores de manera elegante.

Seguridad recomendada

• Nunca expongas tu client_secret o tokens en codigo del lado del cliente (frontend)
• Almacena las credenciales en variables de entorno o un gestor de secretos
• Rota tus tokens periodicamente
• Usa HTTPS exclusivamente para todas las comunicaciones con la API
• Verifica las firmas HMAC de los webhooks entrantes