Saltar para o conteúdo principal
Os recibos das suas mensagens podem esperar por você em uma fila durável por login HTTP até que você os confirme. Você lê essa fila via gRPC de um de dois jeitos — um stream do servidor (Subscribe) ou polling (Pull) — e remove cada recibo com Ack. Os dois leem a mesma fila. É a alternativa a manter um endpoint de webhook: nada para expor à internet, nada contra o que o gateway precise fazer retries, e recibos guardados até você pegá-los.

​
Quais recibos chegam ao feed

Um recibo é enfileirado para o seu login quando todas estas condições valem:
  • a mensagem foi enviada pelo seu login HTTP — via gRPC ou via REST;
  • ela pediu recibos — dlr: true no gRPC, "dlr": "yes" no REST — e este recibo é um dos que ela pediu (dlr_level: 1 progresso, 2 o desfecho, 3 os dois);
  • ela não traz dlr_url.
O webhook vence. Uma mensagem enviada com dlr_url tem seus recibos enviados para essa URL e nunca para o feed. Mensagens enviadas via SMPP nunca aparecem nele — elas recebem seus recibos no bind.
Envios REST também podem usar o feed. Numa plataforma com gRPC e o feed ligados, o REST aceita "dlr": "yes" sem dlr_url, e esses recibos chegam aqui. Onde o gRPC está desligado, essa requisição REST continua sendo recusada com 400, porque os recibos não teriam para onde ir. Veja POST /secure/send.
Uma mensagem que chega ao prazo de recibo — 24 horas por padrão — sem desfecho recebe um último recibo UNKNOWN no feed, como um webhook receberia.

​
A mensagem Receipt

O corpo JSON do webhook, um campo por chave, mais dois campos de entrega no final: Campos opcionais ficam ausentes, não vazios, quando não há nada a dizer. Tudo o que o guia de recibos de entrega diz sobre level, stat e err vale sem alteração.

​
A entrega é pelo menos uma vez

1

Um recibo só sai da fila quando você dá Ack nele

Ou quando a retenção o remove — veja Limites e retenção.
2

Um recibo entregue fica em lease com você por 120 segundos

Se não for confirmado até lá, ele é entregue de novo — a qualquer Subscribe ou Pull do seu login que peça em seguida — com delivery_count aumentado em um.
3

Um stream que termina devolve seus recibos na hora

Quando um stream Subscribe termina — você cancela, a conexão cai, o gateway reinicia — os recibos que ele havia entregado e você não havia confirmado são liberados imediatamente, não depois do lease.
Então, depois de uma reconexão, você recebe de novo tudo o que não tinha confirmado. Esse é o replay, e é o que torna o feed seguro diante de restarts de qualquer um dos lados.
Torne seu tratamento idempotente, e confirme depois, nunca antes.
  • Use como chave id mais level — um recibo de progresso e um desfecho para a mesma mensagem são dois recibos.
  • Trate um delivery_count acima de 1 como uma possível repetição.
  • Dê Ack só depois de ter guardado ou agido sobre um recibo. Confirmar primeiro e depois cair o perde para sempre.

​
Ack

already_gone não é um erro. Um Ack repetido depois de um timeout é seguro, e é exatamente nesse caso que você vai repetir um. Mais de 1000 tokens numa chamada é INVALID_ARGUMENT. Um token funciona em qualquer nó do gateway e através de restarts, mas só para o login ao qual foi entregue. Agrupe suas confirmações: um Ack de 500 tokens é muito mais barato que 500 de um.

​
Pull: polling

Retorna até max recibos (no máximo 1000), os mais antigos primeiro.
  • Sem nenhum esperando e com wait_seconds acima de 0, ele espera até esse tempo — 20 segundos no máximo — e retorna assim que um chega. Isso é um long poll, e é como você evita um busy loop.
  • Com wait_seconds: 0 ele retorna na hora, possivelmente vazio.
Um loop típico:
O Pull serve para um job em lote, um worker que acorda num timer, ou uma linguagem de cujo suporte a streaming você prefere não depender.

​
Subscribe: streaming

Faz stream da sua fila: primeiro o que já está esperando, depois os novos recibos à medida que chegam. window limita quantos recibos entregues mas não confirmados o stream segura. Ao atingir a janela, o stream pausa até você dar Ack — em qualquer canal. Não definido, ou acima do máximo do gateway (1000 por padrão), vale o máximo.
Um stream que parece parar depois de exatamente window recibos está esperando suas confirmações. Dê Ack conforme avança, ou em lotes pequenos — não no final.

​
Vários leitores compartilham a fila

Vários streams Subscribe — e Pulls — de um mesmo login compartilham a fila: cada recibo vai para exatamente um deles por vez. Use isso para distribuir o tratamento de recibos entre vários workers. Para dar feeds separados a aplicações separadas, dê a elas logins HTTP separados.

​
Ordenação

Melhor esforço, por ordem de chegada. Não há garantia de ordem entre nós do gateway, e um recibo reentregue chega depois de outros mais novos. Um desfecho pode chegar antes de um recibo de progresso da mesma mensagem. Ordene por level — 2 é final — e por done_date, nunca pela chegada. Quando você já tem um recibo level: 2 de uma mensagem, ignore qualquer level: 1 que venha depois.

​
Limites e retenção

Seu provedor pode alterar cada um desses.
Um login que pede recibos e nunca lê seu feed o enche. Ele chega ao limite e, daí em diante, novos recibos não são enfileirados — os antigos, não lidos, é que ficam. Se você liga os recibos sem dlr_url, rode algo que os leia. Se você nunca os quer, envie dlr: false.

​
Relacionados

Exemplos

Loops de Subscribe, Pull e Ack em Python, Java e Go.

O webhook de recibo de entrega

Os mesmos campos, enviados via POST para sua URL.