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
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:
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 data | O que é |
|---|---|
instance_id | O número. |
conversation_key | A conversa: o telefone do contato, só dígitos. |
direction | in (recebida) ou out (enviada). |
message_id | O 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:
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
idrecebido, 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,
429too_many_streams, comRetry-After: 5. - Um fluxo que não acompanha (256 eventos sem ler) é fechado. Reconecte com o
Last-Event-IDe receba o resto (ou umreset). - Com a conta suspensa, o fluxo continua abrindo.
- Uma chave errada ou ausente responde
401.