Skip to main content
Use estas práticas para enviar mensagens do WhatsApp com confiabilidade em escala de produção. Você escolherá o endpoint correto, correlacionará cada tentativa, convergirá o estado de entrega, fará novas tentativas com segurança, aplicará o consentimento e controlará a taxa de transferência.

​
Antes de começar

  • Conecte e registre os números de telefone comerciais do WhatsApp que enviarão mensagens.
  • Armazene sua chave de API da YCloud no servidor.
  • Configure um endpoint de webhook assinado para whatsapp.message.updated.
  • Defina como seu sistema registra consentimento, cancelamentos de inscrição (opt-outs), finalidade da mensagem e retenção.
  • Atribua responsáveis pelo envio, processamento de webhooks e resposta a incidentes.

​
Escolha o endpoint de envio

Use o endpoint enfileirado por padrão. Use o envio direto apenas quando o aplicativo precisar saber se o WhatsApp aceitou o envio antes de continuar. Uma resposta bem-sucedida de qualquer um dos endpoints não é prova de entrega. Armazene o id da mensagem retornado e use eventos de whatsapp.message.updated para saber se a mensagem foi sent, failed, delivered ou read.
Não mude toda uma carga de trabalho de alto volume para sendDirectly para reduzir a latência de fila. Chamadas síncronas retêm recursos do aplicativo e ainda exigem tratamento de status assíncrono.

​
Crie um registro de envio interno

Crie um registro durável antes de chamar a API. Forneça ao registro uma chave de negócios exclusiva, como o ID do evento do pedido mais a finalidade da mensagem. Imponha essa exclusividade em seu banco de dados para que workers concorrentes não possam enviar o mesmo evento de negócios duas vezes. Registre pelo menos: Use um externalId opaco que não contenha o conteúdo da mensagem nem dados pessoais. A API recomenda um valor exclusivo, mas externalId é um campo de referência. Ele não é uma chave de idempotência do lado do servidor e não torna seguras solicitações POST repetidas.

​
Conecte a resposta a webhooks de status

O exemplo a seguir usa os mesmos identificadores em todo o fluxo de trabalho de envio.

​
1. Enviar a mensagem

​
2. Armazenar a resposta aceita

Grave MESSAGE_ID, accepted e o tempo de resposta no registro interno existente. Não marque a notificação de negócios como entregue.

​
3. Aplicar eventos de status posteriores

Faça a correspondência do evento por whatsappMessage.id. Use externalId para reconciliação de negócios e wamid para investigação no lado do provedor.

​
Construa um modelo de status convergente

A progressão comum é accepted → sent → delivered → read. failed pode ocorrer antes ou depois de uma atualização de sent. Os webhooks podem ser duplicados, atrasados ou entregues fora de ordem. Uma atualização de read também pode chegar sem um evento delivered separado. Processe cada evento da seguinte forma:
  1. Verifique a assinatura do webhook em relação ao corpo bruto da solicitação (raw body).
  2. Armazene o evento de forma durável, usando o id do evento como a chave de desduplicação.
  3. Retorne uma resposta 2xx imediatamente e, em seguida, processe o evento de forma assíncrona.
  4. Faça a correspondência do whatsappMessage.id com o registro de envio interno.
  5. Armazene o status do evento e os carimbos de data/hora disponíveis da mensagem. Mantenha os metadados brutos do evento necessários para auditoria, mas remova o conteúdo desnecessário da mensagem.
  6. Atualize a visão de negócios atual sem descartar evidências conflitantes ou posteriores. Trate read como evidência de que a entrega ocorreu, mesmo quando o evento separado delivered estiver ausente.
  7. Recupere GET /whatsapp/messages/{id} quando os eventos entrarem em conflito, um status terminal estiver ausente além do seu objetivo de serviço ou o pipeline de webhook estiver indisponível.
Não implemente o modelo de status como uma regra que só aceita um status de maior prioridade. As atualizações reais de entrega nem sempre chegam nessa ordem. Mantenha um histórico de eventos e garanta que a reconciliação consiga corrigir a visualização atual.

​
Tentar novamente sem criar envios duplicados

Classifique a falha antes de tentar novamente. Uma política segura de aplicação pode começar com um número reduzido de tentativas, intervalos exponenciais, variação completa (full jitter) e um tempo total máximo decorrido. Esses são controles da aplicação, não garantias da API. Envie tentativas esgotadas para uma fila de análise em vez de tentar indefinidamente. Antes de cada nova tentativa:
  • Bloqueie ou reivindique atomicamente a chave de negócio interna.
  • Verifique se o registro já possui um id da YCloud ou um evento de status.
  • Não use um novo externalId para ocultar uma tentativa ambígua anterior.
  • Interrompa após atingir o limite configurado de tentativas ou de tempo de espera.
  • Exija uma ação deliberada do operador antes de reenviar um envio ambíguo.

​
Escolher modelos e mensagens de sessão

Use um modelo aprovado ao iniciar uma mensagem de negócios ou enviar fora da janela de atendimento ao cliente de 24 horas. Selecione a categoria do modelo a partir do motivo do usuário para receber a mensagem e mantenha seu nome, idioma e contrato de variáveis na configuração da aplicação. Use mensagens de texto, mídia, interativas, de localização, de contato ou de reação apenas quando a janela de atendimento ao cliente estiver aberta e esse tipo de conteúdo for permitido. Determine a janela a partir da mensagem mais recente do cliente. Não deduza uma janela aberta a partir da sua última mensagem enviada. Consulte Gerenciar modelos do WhatsApp para controle de versão de modelos, critérios de aprovação, localidades e reversão.

​
Gerenciar mídia com eficiência

  • Valide o tipo MIME suportado e o tamanho do arquivo antes de fazer o upload. Não tente novamente um arquivo muito grande ou não suportado sem alterações.
  • Faça o upload com o número de telefone comercial que enviará a mensagem.
  • Reutilize o ID de mídia retornado para envios repetidos do mesmo recurso aprovado enquanto ele permanecer válido. As mídias enviadas permanecem armazenadas por 30 dias.
  • Armazene a soma de verificação (checksum) do recurso, o tipo MIME, o ID de mídia, o remetente e o horário de expiração para que os workers não façam o upload do mesmo arquivo para cada destinatário.
  • Faça o upload novamente após a expiração ou quando o contexto do remetente mudar.
  • Use uma URL pública quando o esquema da mensagem exigir um link, incluindo mídias em cabeçalhos de mensagens interativas.
  • Faça o streaming de uploads grandes diretamente do armazenamento, defina tempos limite para requisições e exclua arquivos locais temporários após o uso.

​
Garantir o consentimento e minimizar dados

Registre a origem do consentimento, a finalidade, o horário e o canal permitido antes de enviar. Aplique a opção de cancelamento (opt-out) válida mais recente em campanhas, fluxos transacionais onde a política exigir, novas tentativas e reenvios manuais. Para POST /whatsapp/messages, defina filterUnsubscribed: true e filterBlocked: true quando o fluxo de trabalho precisar aplicar as listas de supressão da YCloud. O padrão desses campos é false. Eles não se aplicam a sendDirectly, portanto, um fluxo de envio direto deve verificar a supressão antes da chamada de API. Os filtros de supressão são uma verificação final de segurança, não um substituto para o consentimento. Armazene apenas os identificadores e metadados de entrega necessários para a finalidade declarada. Exclua chaves de API, variáveis de modelo, corpos de mensagens e números de telefone dos logs gerais da aplicação. Aplique controles de retenção e de acesso aos registros de mensagens e Webhooks.

​
Controlar o throughput de lotes

Coloque o trabalho em lote em uma fila limitada e envie por meio de um pool fixo de workers. Monitore a simultaneidade separadamente por conta e número de telefone comercial para que um único remetente ou tenant não consuma todos os workers. Aplique contrapressão (backpressure) quando qualquer um destes sinais aumentar:
  • respostas 429
  • latência e tempos limites de requisição
  • respostas 5xx
  • tempo na fila ou acúmulo de tentativas
  • atraso no Webhook e mensagens accepted não resolvidas
Reduza a simultaneidade quando a YCloud ou a entrega posterior ficarem lentas. Retome gradualmente após a normalização. Não tente reenviar mensagens com falha em uma taxa superior à do envio original. Monitore pelo menos o volume de requisições, a taxa de aceitação, a taxa de erros por status HTTP e código de erro, a taxa de status de entrega, o tempo de accepted para cada status posterior, o tamanho da fila, a idade do item mais antigo na fila, a contagem de tentativas, o atraso no Webhook, a contagem de deduplicações e o desvio de reconciliação. Crie alertas para alterações contínuas em relação à sua linha de base normal, não para uma única mensagem que falhou.

​
Antipadrões comuns

  • Marcar uma mensagem como entregue quando a API retorna accepted.
  • Tratar externalId como uma chave de idempotência da YCloud.
  • Tentar novamente cada resposta que não seja 2xx ou timeout sem limite de tentativas.
  • Usar sendDirectly para todo o tráfego.
  • Presumir que os webhooks são únicos, ordenados ou completos.
  • Enviar mensagens de formato livre fora da janela de atendimento ao cliente.
  • Fazer upload do mesmo arquivo de mídia para cada destinatário.
  • Depender de filtros de supressão sem registrar o consentimento.
  • Registrar em log chaves de API, payloads completos ou dados pessoais desnecessários.
  • Iniciar um lote com concorrência ilimitada e sem backpressure.

​
Checklist para entrada em produção

  • A escolha do endpoint corresponde à carga de trabalho e ao requisito de latência.
  • Uma regra de unicidade no banco de dados protege a chave de negócios interna.
  • externalId, id da YCloud e wamid têm funções documentadas distintas.
  • As respostas iniciais permanecem não finais até que a evidência de status chegue.
  • Assinaturas de Webhook, desduplicação de eventos, confirmação rápida e repetição são testadas.
  • Um job agendado de recuperação reconcilia eventos atrasados ou ausentes.
  • Falhas que permitem nova tentativa e falhas que não permitem têm fluxos de tratamento limitados.
  • As regras de modelo e janela de sessão são aplicadas antes do envio.
  • Os uploads de mídia são validados, reutilizados, expirados e limpos com segurança.
  • Os controles de consentimento, cancelamento de inscrição, lista de bloqueio, retenção e logs são verificados.
  • As filas de lote têm limites de concorrência, backpressure, dashboards e alertas.
  • Os operadores podem pausar envios e revisar tentativas ambíguas sem repeti-las automaticamente.

Enviar uma mensagem do WhatsApp

Revise tipos de solicitação, campos, exemplos e dados de resposta.

Configurar webhooks

Verifique assinaturas e processe entregas repetidas de eventos com segurança.

Fazer upload de mídia do WhatsApp

Faça upload de mídia compatível e reutilize o ID de mídia retornado.

Tratar erros da API

Analise respostas de erro e aplique novas tentativas limitadas.