Referência da Chat API

Autenticação

Cada pedido é autenticado com a chave API do seu espaço de trabalho, enviada no cabeçalho X-API-Key (ou como parâmetro api_key). As chaves têm o aspeto ck_live_.... Trate a chave como uma palavra-passe - qualquer pessoa que a possua pode enviar mensagens debitadas ao seu espaço de trabalho. Rode-a a qualquer momento em Definições -> Acesso à API; a chave anterior deixa de funcionar imediatamente.

Enviar uma mensagem

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 (string) - a mensagem do visitante. Obrigatório a menos que sejam anexados files.
• ticket_id (string, opcional) - continua uma conversa existente. Omita para iniciar uma nova.
• visitor_email / visitor_name (string, opcional) - anexa os dados de contacto ao ticket.
• files (multipart, opcional) - anexos do visitante. Requer um plano com carregamento de ficheiros.

Resposta

A chamada devolve 202 Accepted assim que a mensagem é guardada; a resposta da IA é gerada de forma assíncrona.

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

Devolva data.ticket_id como ticket_id na chamada seguinte para manter a conversa a decorrer. Para receber a resposta da IA, subscreva por WebSocket (ActionCable) o canal identificado por data.id - o mesmo hash do visitante que o widget incorporado utiliza.

Ler conversas

Obtenha os tickets e as respetivas mensagens com a mesma X-API-Key. Cada endpoint de leitura está limitado ao seu espaço de trabalho e disponível no plano Business.

• GET /api/v1/chat/tickets - lista os tickets, do mais recente para o mais antigo. Parâmetros de consulta: status, limit (máx. 100), offset. Devolve tickets e pagination.
• GET /api/v1/chat/tickets/:id - um único ticket.
• GET /api/v1/chat/tickets/:id/messages - as mensagens de um ticket por ordem, cada uma com role, content e attachments.

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

Limites de taxa e quota

Os pedidos são limitados a cerca de 20 por minuto por chave (e por IP). Cada resposta gerada também consome da mensalidade de mensagens do seu plano; assim que se esgotar, o endpoint devolve um 200 com data.limit_reached: true em vez de gerar uma resposta.

Erros

• 401 - nenhuma chave API fornecida.
• 404 - a chave não corresponde a nenhum espaço de trabalho (por ex. após rotação).
• 403 plan_upgrade_required - o espaço de trabalho não está no plano Business.
• 403 - a subscrição está inativa, ou o pedido veio de um domínio não permitido pelas definições do widget.
• 422 - a mensagem está em falta (e não foram anexados ficheiros).