Webhook de resposta de mensagem (reply)#
O webhook de reply informa que o destinatário respondeu a uma mensagem. Quando uma resposta é recebida e relacionada a uma mensagem enviada pela API, a plataforma envia uma requisição HTTP POST para a URL de webhook de respostas cadastrada na conta.O mesmo formato de payload é utilizado para respostas de 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.reply | Identifica que a requisição é um callback de resposta 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#
{
"replySender": "5511999999999",
"replyContent": "SIM, confirmo o agendamento",
"replyTimestamp": "2026-07-16T14:35:22-03:00",
"messageId": "b72bd6c8-4489-4ff1-8e91-13c634ca24b0",
"messageStatus": "Delivered",
"messageStatusDetails": "A mensagem foi entregue com confirmação no aparelho.",
"messageReceiver": "5511999999999",
"messageTag": "agendamento-12345",
"messageCustom": "cliente-987",
"messageType": "Sms",
"webhookType": "Replies"
}
Campos do payload#
| Campo | Tipo | Pode ser nulo | Descrição |
|---|
replySender | string | Sim | Identificador ou número do remetente que enviou a resposta. Para telefone, normalmente é informado com código do país e DDD. |
replyContent | string | Sim | Conteúdo recebido do destinatário. |
replyTimestamp | string (data/hora ISO 8601) | Não | Data e hora associadas ao recebimento da resposta. |
messageId | string (UUID) | Não | Identificador único da mensagem original que recebeu a resposta. É o mesmo identificador retornado no envio. |
messageStatus | string | Não | Status da mensagem original no momento em que o reply foi processado. |
messageStatusDetails | string | Sim | Descrição legível do status da mensagem original. |
messageReceiver | string | Sim | Destinatário da mensagem original. Em mensagens telefônicas, corresponde normalmente ao mesmo contato indicado em replySender. |
messageTag | string | Sim | Tag informada pelo cliente no envio da mensagem original. |
messageCustom | string | Sim | Valor personalizado informado pelo cliente no envio da mensagem original. |
messageType | string | Não | Tipo/canal da mensagem original. |
webhookType | string | Não | Identifica este callback. Para respostas, o valor é sempre Replies. |
messageId identifica a mensagem enviada originalmente. Ele não é um identificador exclusivo do reply.
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 |
Os valores possíveis de messageStatus são Analysis, Created, Processing, Queued, Sending, Sent, Delivered, Read, Expired, Failed, Invalid, InvalidNumber, Rejected, Undeliverable, LowBalance, Blocked, Canceled e LimitExceeded.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 para localizar a mensagem original e replyTimestamp para registrar quando a resposta ocorreu.
Trate o evento de forma idempotente para evitar efeitos duplicados em caso de reprocessamento ou repetição do callback.
Preserve replyContent exatamente como recebido se o texto for usado em auditoria ou atendimento.
Não use messageReceiver como único identificador de cliente; normalize o telefone e relacione-o aos dados do seu sistema.
Considere novos campos ou valores de messageType 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:53:54
