Skip to main content
Enviar uma solicitação e entregar uma mensagem são eventos diferentes. Uma resposta de API bem-sucedida confirma o resultado da solicitação nessa etapa; ela não garante que o cliente recebeu ou leu a mensagem. Use o status da mensagem da YCloud e quaisquer detalhes de erro disponíveis para entender o que aconteceu.

​
Status de mensagens de saída

O recurso de mensagens de saída do WhatsApp da YCloud usa estes status: Uma progressão típica de sucesso é accepted → sent → delivered → read. Não presuma que seu aplicativo receberá todas as atualizações intermediárias ou que as atualizações chegarão exatamente nessa ordem.

​
Por que uma solicitação bem-sucedida não é a entrega final

Com o endpoint enfileirado, a YCloud aceita a solicitação e a envia de forma assíncrona. Com o endpoint direto, o envio para a WhatsApp Business API ocorre de forma síncrona. A entrega final ainda é assíncrona em ambos os casos. Para detalhes de implementação, consulte Enviar uma mensagem do WhatsApp. Se o status atual ainda for accepted ou sent, não envie repetidamente o mesmo conteúdo. Uma solicitação adicional pode resultar em mensagem duplicada.

​
Confirmações de entrega e leitura

Entregue significa que a mensagem chegou ao dispositivo do cliente. Não significa que o cliente abriu a conversa. As confirmações de leitura não estão disponíveis em todas as situações. Por exemplo, as configurações de confirmação de leitura do cliente podem afetar se uma atualização de leitura é reportada. A ausência de uma atualização de leitura não é prova de que o cliente ignorou a mensagem. Para obter as definições de status upstream, consulte a referência de webhooks de status de mensagem da Meta.

​
Rastrear a mesma mensagem em diferentes sistemas

Ao solucionar problemas, mantenha as seguintes informações reunidas: Não inclua chaves de API nem informações desnecessárias de clientes ao compartilhar registros para solução de problemas. Integrações via API podem receber Webhooks de whatsapp.message.updated e recuperar o recurso da mensagem. Consulte as práticas recomendadas para mensagens no WhatsApp para sincronização e tratamento de novas tentativas.

​
Investigar uma mensagem com falha

Comece pelo erro retornado, não apenas pelo nome do status.
  • Problema no modelo: confirme se o modelo de mensagem está disponível e se o idioma e os parâmetros estão corretos.
  • Problema na janela: verifique se a mensagem requer uma janela de atendimento ao cliente aberta.
  • Problema na conta ou número: inspecione o ativo afetado e suas restrições atuais.
  • Problema de conteúdo ou mídia: verifique os requisitos do tipo de mensagem selecionado.
  • Controle de entrega: siga a orientação de erro específica. Novas tentativas imediatas e repetidas podem não resolver uma restrição da plataforma.
Uma mensagem com falha não comprova que um cliente bloqueou seu número. Use os detalhes reais do erro e evite inferir comportamentos do cliente que a plataforma não relatou. Para controles de entrega da plataforma, consulte Controles de qualidade e entrega. Para notificações de aplicação de medidas, consulte Restrições de conta e recursos.

​
Decidir se tentar novamente é seguro

Um bom registro de mensagem vincula uma ação de negócios pretendida às suas solicitações e resultados. Sua referência externa ajuda na correlação, mas não presuma que ela forneça idempotência de API, a menos que o endpoint garanta explicitamente esse comportamento.

​
Exemplo de atualizações de status atrasadas

Seu sistema recebe delivered e, em seguida, um evento sent atrasado para a mesma mensagem. Não altere o status do cliente de volta para “não entregue”. Armazene os carimbos de data/hora dos eventos e aplique um modelo de estado que tolere atualizações duplicadas e fora de ordem. Da mesma forma, a ausência de um evento read não significa que a mensagem falhou. Separe estas métricas:
  • Alcance de entrega: mensagens com comprovação de entrega.
  • Alcance de leitura: mensagens com confirmação de leitura reportada.
  • Resposta do cliente: uma resposta ou interação real recebida.
  • Conversão de negócios: uma reserva confirmada, compra ou verificação bem-sucedida no sistema responsável por ela.

​
Próximos passos

​
Perguntas frequentes

Você não pode concluir isso. As confirmações de leitura podem estar indisponíveis, inclusive quando o destinatário as desativa. Mantenha entregue e lido como medições separadas. Nem a ausência de uma confirmação de leitura nem um erro geral de não entrega identifica o motivo do cliente ou comprova bloqueio.
Não imediatamente. A plataforma já pode ter aceitado a solicitação. Verifique o identificador da mensagem, os logs disponíveis e os eventos de webhook posteriores antes de emitir outro envio. Correlacione as tentativas à mesma ação de negócios e crie proteção contra duplicatas; uma referência externa não garante automaticamente a idempotência do endpoint.
Uma limitação de exibição e uma falha de entrega são coisas diferentes. Inspecione a direção real, o status, o tipo de mensagem e qualquer erro. Para conteúdo recebido, siga o guia de mensagem não compatível da Caixa de Entrada; não tente adivinhar o conteúdo nem considere um espaço reservado como uma falha de envio de saída.