Ir para o conteúdo

Tempo real

O fluxo de eventos (SSE) para saber na hora quando chega uma mensagem, como retomar depois de cair e os limites.

Além dos webhooks, a API tem um fluxo de eventos: uma conexão HTTP que fica aberta e recebe um aviso pequeno a cada mudança. Use-o quando o seu sistema quer saber na hora, sem expor um endereço para a API chamar.

Cada evento leva só o tipo e os ids. Os detalhes você busca pelas rotas de sempre: por exemplo, as mensagens do número.

Abrir o fluxo

bash
curl -N -H "Authorization: Bearer $API_KEY" \
  "$API_URL/api/v1/events/stream"

A resposta é text/event-stream (Server-Sent Events). Cada evento tem um id, o tipo em event e um JSON em data:

text
id: 42
event: inbox.message
data: {"type":"inbox.message","instance_id":"<id do número>","data":{"instance_id":"<id do número>","conversation_key":"5511999990001","direction":"in","message_id":"<id da mensagem>"}}

Um comentário : ping sai a cada 25 segundos, para a conexão não cair por inatividade.

Quem recebe o quê

Uma chave de API (wck_...) com o escopo Números recebe o evento inbox.message dos números da lista dela: toda mensagem gravada, recebida ou enviada, por qualquer caminho.

Campo de dataO que é
instance_idO número.
conversation_keyA conversa: o telefone do contato, só dígitos.
directionin (recebida) ou out (enviada).
message_idO id da mensagem.

A API também tem eventos da caixa de entrada (inbox.conversation) e do CRM (crm.deal, crm.task). Eles vão só para a chave da plataforma, porque as rotas da caixa e do CRM não abrem com uma chave de API.

Retomar depois de cair

Se a conexão cair, abra de novo com o cabeçalho Last-Event-ID e o id do último evento que você recebeu:

bash
curl -N -H "Authorization: Bearer $API_KEY" \
  -H "Last-Event-ID: 42" \
  "$API_URL/api/v1/events/stream"
  • O fluxo continua pelos eventos que chegaram depois daquele: a API guarda os últimos 500, ou os dos últimos 5 minutos.
  • Os ids podem chegar fora de ordem. A retomada vale pela ordem de chegada, então guarde o último id recebido, não o maior.
  • Se o id já não está guardado, vem event: reset: recarregue pelas rotas o que o seu sistema mostra, e siga com os eventos novos.

Um EventSource do navegador já reconecta sozinho com o Last-Event-ID; num servidor, a sua biblioteca de SSE costuma fazer o mesmo. Lembre que a chave não deve ir para o navegador: abra o fluxo no seu servidor.

Limites

  • No máximo 10 fluxos abertos por chave de API. Acima disso, 429 too_many_streams, com Retry-After: 5.
  • Um fluxo que não acompanha (256 eventos sem ler) é fechado. Reconecte com o Last-Event-ID e receba o resto (ou um reset).
  • Com a conta suspensa, o fluxo continua abrindo.
  • Uma chave errada ou ausente responde 401.