Referencia de la API de Chat

Autenticación

Cada solicitud se autentica con la clave de API de tu espacio de trabajo, enviada en la cabecera X-API-Key (o como un parámetro api_key). Las claves tienen el aspecto ck_live_.... Trata la clave como una contraseña - cualquiera que la tenga puede enviar mensajes facturados a tu espacio de trabajo. Rótala en cualquier momento desde Configuración -> Acceso a la API; la clave anterior deja de funcionar de inmediato.

Enviar un mensaje

POST https://chatixy.com/api/v1/chat

curl https://chatixy.com/api/v1/chat \
  -H "X-API-Key: ck_live_YOUR_KEY" \
  -F "message=How do I reset my password?"

Parámetros:

• message (cadena) - el mensaje del visitante. Obligatorio a menos que se adjunten files.
• ticket_id (cadena, opcional) - continúa una conversación existente. Omítelo para iniciar una nueva.
• visitor_email / visitor_name (cadena, opcional) - adjunta datos de contacto al ticket.
• files (multipart, opcional) - archivos adjuntos del visitante. Requiere un plan con subida de archivos.

Respuesta

La llamada devuelve 202 Accepted en cuanto se almacena el mensaje; la respuesta de la IA se genera de forma asíncrona.

{
  "status": { "code": 202, "message": "Message received and being processed" },
  "data": {
    "ticket_id": 1234,
    "ticket_number": "T-1234",
    "id": "<visitor_hash>",
    "processing": true
  }
}

Vuelve a pasar data.ticket_id como ticket_id en la siguiente llamada para mantener la conversación. Para recibir la respuesta de la IA, suscríbete por WebSocket (ActionCable) al canal identificado por data.id - el mismo hash de visitante que usa el widget integrado.

Leer conversaciones

Obtén los tickets y sus mensajes con la misma X-API-Key. Cada endpoint de lectura está limitado a tu espacio de trabajo y disponible en el plan Business.

• GET /api/v1/chat/tickets - lista los tickets, del más reciente al más antiguo. Parámetros de consulta: status, limit (máx. 100), offset. Devuelve tickets y pagination.
• GET /api/v1/chat/tickets/:id - un único ticket.
• GET /api/v1/chat/tickets/:id/messages - los mensajes de un ticket en orden, cada uno con role, content y attachments.

curl https://chatixy.com/api/v1/chat/tickets \
  -H "X-API-Key: ck_live_YOUR_KEY"

Límites de tasa y cuota

Las solicitudes se limitan a aproximadamente 20 por minuto por clave (y por IP). Cada respuesta generada también consume la asignación mensual de mensajes de tu plan; una vez agotada, el endpoint devuelve un 200 con data.limit_reached: true en lugar de generar una respuesta.

Errores

• 401 - no se proporcionó ninguna clave de API.
• 404 - la clave no coincide con ningún espacio de trabajo (por ejemplo, tras una rotación).
• 403 plan_upgrade_required - el espacio de trabajo no está en el plan Business.
• 403 - la suscripción está inactiva, o la solicitud provino de un dominio no permitido por la configuración del widget.
• 422 - falta el mensaje (y no se adjuntaron archivos).