Webhook de status de mensagem#
O webhook de status informa as mudanças ocorridas durante o processamento e a entrega de uma mensagem. A cada atualização recebida, a plataforma envia uma requisição HTTP POST para a URL de webhook de status cadastrada na conta.O mesmo formato de payload é utilizado para mensagens SMS e RCS.Requisição enviada#
Nos callbacks de SMS e RCS, os headers abaixo permitem identificar que a requisição foi produzida pela plataforma Comtele e qual evento originou o callback:| Header | Valores possíveis | Descrição |
|---|
X-Comtele-Source | gateway-v4 | Identificador técnico da aplicação Comtele que enviou o callback. |
X-Comtele-Platform | Comtele Gateway V4 | Nome da plataforma Comtele responsável pelo envio. |
X-Comtele-Event | message.status | Identifica que a requisição é um callback de status de mensagem. |
Exemplo de validação dos headers:Esses headers identificam a origem lógica da requisição, mas não são uma assinatura criptográfica e podem ser reproduzidos por terceiros. Não os utilize como único mecanismo de autenticação. Aplique também os controles de segurança adotados pela sua aplicação.
Exemplo de payload#
{
"messageId": "b72bd6c8-4489-4ff1-8e91-13c634ca24b0",
"messageStatus": "Delivered",
"messageStatusDetails": "A mensagem foi entregue com confirmação no aparelho.",
"messageTag": "pedido-12345",
"messageCustom": "cliente-987",
"messageType": "Sms",
"webhookType": "Status"
}
Campos do payload#
| Campo | Tipo | Pode ser nulo | Descrição |
|---|
messageId | string (UUID) | Não | Identificador único da mensagem. É o mesmo identificador retornado no envio e deve ser usado para relacionar o callback à mensagem original. |
messageStatus | string | Não | Status atual da mensagem. Consulte a tabela de status abaixo. |
messageStatusDetails | string | Sim | Descrição legível com mais detalhes sobre o status. O tratamento automático deve utilizar messageStatus, e não este texto. |
messageTag | string | Sim | Tag informada pelo cliente no envio da mensagem. |
messageCustom | string | Sim | Valor personalizado informado pelo cliente no envio da mensagem. Pode ser usado para correlação com um identificador do seu sistema. |
messageType | string | Não | Tipo/canal da mensagem. Consulte os valores possíveis abaixo. |
webhookType | string | Não | Identifica este callback. Para atualizações de status, o valor é sempre Status. |
Status possíveis#
| Valor | Significado |
|---|
Analysis | A mensagem está em análise antes de seguir o fluxo de envio. |
Created | A mensagem foi criada e aguarda processamento. |
Processing | A mensagem está sendo processada. |
Queued | A mensagem foi adicionada à fila de envio. |
Sending | A mensagem está em processo de envio para a operadora/provedor. |
Sent | A mensagem foi enviada para a operadora/provedor. Este status não confirma a entrega no aparelho. |
Delivered | A entrega no aparelho foi confirmada. |
Read | A mensagem foi entregue e aberta/lida pelo destinatário, quando o canal oferece essa confirmação. |
Expired | O prazo de entrega expirou. |
Failed | Não foi possível concluir a entrega. |
Invalid | A mensagem é inválida e não pode ser enviada. |
InvalidNumber | O número do destinatário é inválido. |
Rejected | O conteúdo da mensagem foi rejeitado. |
Undeliverable | A operadora/provedor não conseguiu entregar a mensagem no aparelho. |
LowBalance | Não havia saldo suficiente para realizar o envio. |
Blocked | O destinatário está na lista de bloqueio da conta. |
Canceled | A mensagem foi cancelada pelo usuário. |
LimitExceeded | O limite de tentativas de entrega foi atingido. |
Nem todos os canais passam por todos os status. Uma mensagem pode, por exemplo, evoluir de Sent para Delivered e depois para Read, enquanto outra pode encerrar o fluxo em Failed ou Undeliverable.Tipos de mensagem#
O campo messageType pode conter:| Valor | Tipo de mensagem |
|---|
Sms | SMS |
RcsBasic | RCS básico |
RcsCard | Card RCS |
RcsFile | Arquivo RCS |
RcsCarousel | Carrossel RCS |
RcsSingleText | Texto simples RCS |
Resposta esperada do seu endpoint#
Depois de receber e armazenar o evento, responda rapidamente com qualquer código HTTP de sucesso da família 2xx. O corpo da resposta pode ser vazio.O endpoint deve estar acessível pela internet. Recomenda-se utilizar HTTPS e não realizar processamentos demorados antes de responder; se necessário, coloque o evento em uma fila interna e processe-o de forma assíncrona.Boas práticas de integração#
Use messageId como chave de correla ção com a mensagem enviada.
Trate o callback de forma idempotente. O recebimento repetido do mesmo status não deve gerar efeitos duplicados.
Não presuma que todos os status intermediários serão recebidos.
Guarde o valor original de messageStatus; messageStatusDetails é apenas descritivo e pode mudar sem alterar o significado do evento.
Considere novos valores de status ou tipo de mensagem desconhecidos, sem rejeitar todo o payload.
Restrinja o acesso ao endpoint conforme a política de segurança da sua aplicação. O payload atual não possui assinatura criptográfica.
Exemplo de tratamento#
Modified at 2026-07-16 16:54:04
