Skip to main content
Para o catálogo completo derivado do schema, consulte todos os exemplos.

O que é

Processe atualizações de status para mensagens de WhatsApp, Messenger, E-mail, SMS e Voz.

Antes de começar

  • Crie um endpoint HTTPS público na sua aplicação.
  • Configure um endpoint de webhook da YCloud para os tipos de evento de que você precisa.
  • Armazene o segredo de assinatura do endpoint com segurança.
  • Torne o processamento de eventos idempotente.

Como funciona

A YCloud envia uma solicitação HTTP POST quando o evento ocorre. Valide a assinatura, registre o evento de forma duradoura, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.

Solicitação

Os cenários abaixo mostram solicitações entregues à sua URL de webhook. Trate o evento id como o identificador de entrega e use type para rotear o payload.

Resposta

Retorne um status 2xx após aceitar o evento.
Para saber mais sobre configuração de endpoints, validação de assinatura e comportamento de repetição, consulte Configurar webhooks.
No WhatsApp, após solicitar o envio de mensagens com sucesso à API, as mensagens ficam com o status accepted. As atualizações de status de mensagem acionarão o webhook whatsapp.message.updated. Normalmente, o status da mensagem:
  • Muda para failed se não conseguirmos entregar esta mensagem.
  • Muda para sent se for possível entregar esta mensagem e, mais tarde, pode mudar para failed, delivered ou read.
  • Muda para delivered ou read se esta mensagem foi entregue no dispositivo do destinatário.
No entanto, a situação real é complexa. Primeiro, não garantimos a ordem das notificações de webhook, principalmente quando os eventos ocorrem quase simultaneamente. Segundo, eventos delivered podem acontecer após failed e vice-versa, especialmente quando o usuário final está usando vários dispositivos.

Mensagem Max Price entregue

Use a atualização de mensagem entregue para reconciliar a cobrança final de uma mensagem de marketing Max Price.

Solicitação

Resposta

Retorne uma resposta 2xx após aceitar o evento de forma duradoura.

Explicação

bidPricingFlag: true e pricingCategory: marketing_lite_bidding identificam o modo de lance. Em delivered ou read, use totalPrice e currency para a cobrança final. O maxBid configurado é um teto de preço; o valor informado em accepted ou sent é uma estimativa. Consulte o guia de integração do Max Price para obter exemplos de configuração e multiplicadores.

Mensagem enviada

Neste caso, seu endpoint de webhook recebeu um evento de mensagem sent:
  • O status da mensagem é sent, o que significa que a mensagem está em trânsito dentro dos sistemas do WhatsApp.
  • Contém informações sobre a conversa, incluindo o horário em que a conversa expira e o tipo de origem.
  • Contém o pricingCategory e a totalPrice estimados que podemos cobrar de você.
  • Contém wamid, que é o ID original da mensagem na plataforma do WhatsApp, começando com wamid..

Solicitação

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma duradoura.

Explicação

  • totalPrice é apenas um preço estimado antes da entrega da primeira mensagem e se torna o preço final quando o status for delivered ou read. O saldo retido por essas mensagens que foram enviadas, mas ainda não foram entregues, não estará disponível até que as mensagens sejam descartadas (mensagens enviadas que não são entregues durante 30 dias são descartadas).
  • Geralmente, uma mensagem com status sent muda para delivered ou read em breve, exceto quando:
    • A conta do WhatsApp do destinatário estiver offline; suas mensagens de WhatsApp enviadas não serão entregues até que o destinatário tenha conexão com a internet ativa ou funcionando.
    • Qualquer mensagem enviada para um contato que bloqueou você sempre exibirá a mensagem sent e nunca mudará para delivered.
    • O destinatário desativou as confirmações de leitura, e você não receberá as confirmações de read da mensagem.
    • A mensagem mudar para failed posteriormente com o código de erro 131026, o que significa “Message Undeliverable” (Mensagem não entregável) ou “Receiver is incapable of receiving this message” (O destinatário é incapaz de receber esta mensagem). O motivo mais provável é que o destinatário não esteja cadastrado ou esteja usando uma versão antiga do WhatsApp.
    • A mensagem não foi entregue para preservar uma experiência de usuário de alta qualidade. Consulte Limites de modelos de mensagem de marketing por usuário.

Mensagem entregue

Neste caso, seu endpoint de webhook recebeu um evento de mensagem delivered:
  • O status da mensagem é delivered, o que significa que a mensagem foi entregue no dispositivo do destinatário.

Solicitação

Resposta

Confirme o recebimento da entrega após aceitar o evento de forma duradoura.

Explicação

  • Este evento indica que a mensagem enviada pela sua empresa foi entregue no dispositivo do usuário.
  • Para que um status seja read, ele deve ter sido delivered. Em alguns cenários, como quando um usuário está na tela de conversa e uma mensagem chega, ela é delivered e read quase simultaneamente. Nesse ou em outros cenários semelhantes, a notificação de delivered não será enviada de volta, pois subentende-se que uma mensagem foi entregue se ela foi lida. O motivo desse comportamento é uma otimização interna.
  • É possível que geremos mais de 1 evento de webhook delivered para a mesma mensagem, principalmente se o usuário final estiver usando vários dispositivos.
  • pricingModel: “PMP” — indica que o preço por mensagem é aplicável. Consulte também whatsapp-message-pricing-updates
  • pricingType
    • regular — indica que a mensagem é faturável.
    • free_customer_service — indica que a mensagem é gratuita porque foi um modelo de mensagem de utilidade ou uma mensagem sem modelo enviada dentro de uma janela de atendimento ao cliente.
    • free_entry_point — indica que a mensagem é gratuita porque faz parte de uma conversa de ponto de entrada gratuito.

Mensagem lida

Neste caso, seu endpoint de webhook recebeu um evento de mensagem read:
  • O status da mensagem é read, o que significa que a mensagem foi lida pelo destinatário.

Requisição

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

Explicação

  • Se o destinatário desativou as confirmações de leitura, você não receberá as confirmações de read da mensagem.

Mensagem com falha

Neste caso, seu endpoint de webhook recebeu um evento de mensagem failed:
  • O status da mensagem é failed.
  • Contém errroCode, errorMessage e whatsappApiError.

Requisição

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

Explicação

  • Esses eventos têm a finalidade de notificar você sobre alterações de status de mensagens de saída enviadas anteriormente para os clientes.
  • O motivo da falha no envio da mensagem normalmente são parâmetros de requisição inválidos, número de telefone do cliente não cadastrado, etc. Consulte também WhatsApp Errors para o tratamento de erros.
  • O campo whatsappApiError é fornecido caso tenhamos tentado enviar essa mensagem para a plataforma WhatsApp da Meta para ajudar você a entender os detalhes do erro. Consulte também Cloud API Error Codes.
  • Não cobramos por mensagens que falharam.

Atualização de entrega de e-mail

Use email.delivery.updated quando o status de entrega de um e-mail mudar para delivered ou failed.

Requisição

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

Explicação

Correlacione a entrega com emailId e recipientAddress: o status se aplica a este destinatário. Use externalId quando fornecido para corresponder ao seu próprio registro. Inspecione errorCode e errorMessage em caso de entrega com falha. A propriedade do payload é emailDelivery, e não whatsappMessage.

Atualização de entrega de SMS

Use sms.message.updated quando o status de entrega de um SMS mudar para delivered ou undelivered.

Requisição

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

Explicação

Identifique o SMS com sms.id e leia sms.status. Inspecione errorCode quando a entrega falhar. O SMS usa undelivered para uma confirmação de entrega negativa; não aplique o modelo de status read do WhatsApp a este evento.

Atualização de entrega de voz

Use voice.message.updated quando o status de uma mensagem de voz mudar para delivered ou undelivered.

Requisição

Resposta

Confirme a entrega após aceitar o evento de forma duradoura.

Explicação

Identifique a mensagem de voz com voice.id e leia voice.status. Inspecione errorCode quando fornecido. Este evento de entrega pertence à API de mensagens de voz; ele é separado dos eventos do ciclo de vida de chamadas do WhatsApp.

Messenger outbound read snapshot

Inscreva-se em messenger.message.updated para snapshots de saída individuais comuns salvos. Uma nova tentativa de entrega mantém Event.id; recriar um evento a partir do mesmo fato de origem pode gerar um novo Event.id. Correlacione as atualizações por messengerMessage.id.

Estados de envio e confirmação

accepted significa que a Meta aceitou o envio, não que a mensagem foi sent ou delivered. rejected é uma rejeição definitiva do envio; unknown é um resultado não confirmado e não deve ser tratado como falha. Não reenvie uma mensagem automaticamente após um tempo limite ou um resultado unknown. Verifique o status salvo usando o ID da mensagem retornado, quando disponível, ou entre em contato com o suporte. Um snapshot preserva os fatos salvos atuais, com read tendo precedência sobre delivered, sent e o resultado do envio. Confirmações tardias não rebaixam esse estado. Você pode receber snapshots repetidos ou perder estados intermediários. Use GET /v2/messenger/messages/{id} com from, ou consulte pelo ID de mensagem confirmado da Meta, para reconciliar seu estado salvo atual. As notificações de resultado do envio são no modelo de melhor esforço (best effort). Não dependa do recebimento de um webhook para cada resultado de envio síncrono. IDs opcionais, errorCode e horários de recebimento são omitidos quando indisponíveis. Um erro de envio armazenado pode permanecer presente mesmo após dados de recebimento posteriores estabelecerem um status mais definitivo.

Requisição

Resposta

Explicação

O Page ID do Facebook é from e o PSID do cliente é to. Este exemplo expõe o estado read salvo sem inventar sendTime ou deliverTime ausentes. id é o ID da mensagem da YCloud, enquanto metaMessageId é a identidade do provedor.

Reação a mensagem do Messenger

Requisição

Resposta

Explicação

Use pageId e psid para identificar a conversa, e metaMessageId para identificar a mensagem de destino. Uma reação é uma interação e não altera o status de entrega. O destino pode não ter um registro local de mensagem na YCloud. Preserve o createTime de origem; entregas repetidas podem ocorrer. Verifique YCloud-Signature em relação ao corpo bruto antes de retornar uma resposta de sucesso.

Reação a mensagem do Messenger removida

Requisição

Resposta

Explicação

Remova a reação associada a esta Página, ao PSID do cliente e à mensagem de destino da Meta. unreact pode omitir reaction e emoji. Não exija um ID de mensagem local nem deduza uma alteração de status da mensagem. Tentativas de reenvio de entrega HTTP mantêm o mesmo ID de evento e corpo; callbacks repetidos de origem podem criar um novo ID de evento. Verifique YCloud-Signature em relação ao corpo bruto antes de retornar uma resposta de sucesso.