Para o catálogo completo derivado do esquema, consulte todos os exemplos.
O que é
Processe mensagens recebidas do WhatsApp, Messenger e SMS, além de preferências de marketing do WhatsApp.Antes de começar
- Crie um endpoint HTTPS público em sua aplicação.
- Configure um endpoint de webhook da YCloud para os tipos de evento necessários.
- Armazene o segredo de assinatura do endpoint com segurança.
- Torne o processamento de eventos idempotente.
Como funciona
A YCloud envia uma solicitação HTTPPOST quando o evento ocorre. Verifique a assinatura, registre o evento de forma durável, retorne uma resposta 2xx e processe tarefas lentas de forma assíncrona.
Solicitação
Os cenários abaixo mostram solicitações enviadas para a sua URL de webhook. Trate oid do evento como o identificador de entrega e use type para rotear o payload.
Resposta
Retorne um status2xx após aceitar o evento.
Para configuração do endpoint, validação de assinatura e comportamento de novas tentativas, consulte Configurar webhooks.
Mensagem recebida não suportada
Neste caso, seu endpoint de webhook recebeu uma mensagem recebida não suportada:typeestá definido comounsupported.errorsexplica por que a mensagem não é suportada ou está indisponível.unsupported.typeidentifica a categoria da mensagem, comopoll_creation,poll_update,editoupin.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O erro
131051comMessage type unknownsignifica que a Cloud API do WhatsApp não oferece suporte ao tipo de mensagem. - O erro
131060comThis message is currently unavailable.significa que o WhatsApp não pôde fornecer o conteúdo da mensagem. unsupported.typeidentifica a categoria geral. Não contém o conteúdo original da mensagem.- Consulte Mensagens não suportadas na Caixa de Entrada para obter uma lista legível dos tipos de mensagem. Consulte a referência de webhook para mensagens não suportadas da Meta para ver o contrato de payload atual.
Mensagem de texto recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de texto recebida:- Contém texto sem formatação enviado pelo usuário.
- Contém as informações da mensagem mencionada em
context.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- Mensagens recebidas são aquelas enviadas por clientes para os números de telefone da sua empresa.
- O
context(opcional) contém as informações da mensagem mencionada, normalmente usado para responder a uma mensagem anterior enviada pelo usuário ou pela sua empresa.context.fromé o ID do WhatsApp (número de telefone sem o prefixo ’+’) do usuário que enviou a mensagem mencionada.context.idé o ID original da mensagem mencionada na plataforma do WhatsApp, começando comwamid..
Mensagem de texto recebida acionada por anúncios de clique para o WhatsApp
Neste caso, seu endpoint de webhook recebeu uma mensagem de texto recebida acionada por anúncios de clique para o WhatsApp:- Contém texto sem formatação.
- Contém informações sobre o anúncio.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O
referralcontém informações sobre o anúncio. Consulte também Anúncios com clique para o WhatsApp.
Mensagem de imagem recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de imagem recebida:- Contém a URL de uma imagem.
- Contém uma legenda descrevendo esta imagem.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O
image.linkpode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalhoX-API-Keypara baixar este arquivo dentro de 30 dias.
Mensagem de vídeo recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de vídeo recebida:- Contém a URL de um vídeo.
- Contém uma legenda descrevendo este vídeo.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O
video.linkpode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalhoX-API-Keypara baixar este arquivo dentro de 30 dias.
Mensagem de áudio recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de áudio recebida:- Contém a URL de um áudio.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O
audio.linkpode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalhoX-API-Keypara baixar este arquivo dentro de 30 dias.
Mensagem de documento recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de documento recebida:- Contém a URL de um documento.
- Contém uma legenda descrevendo este documento.
Solicitação
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- O
document.linkpode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalhoX-API-Keypara baixar este arquivo dentro de 30 dias.
Mensagem de figurinha recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de figurinha recebida:- Contém a URL de uma figurinha.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
- O
sticker.linkpode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalhoX-API-Keypara baixar este arquivo dentro de 30 dias.
Mensagem de localização recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de localização recebida:- Contém latitude e longitude do local.
- Contém nome, endereço e URL do local.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
Encaminhe o evento portype, desduplique-o por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.
Mensagem de contatos recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de contatos recebida:- Contém um contato com endereços, data de nascimento, e-mails, nome, telefones e outros campos de contato.
- Contém
origin: contact_requestquando o usuário compartilhou o contato em resposta a uma mensagem de solicitação de informações de contato.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
Encaminhe o evento portype, desduplique-o por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.
Mensagem de reação recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de reação recebida:- Contém o ID da mensagem à qual o usuário reagiu.
- Contém o emoji.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
- O
emojiestá presente quando o usuário reage a uma mensagem com um emoji. Caso contrário, indica que o usuário removeu o emoji de uma mensagem.
Mensagem de botão de modelo recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem de botão de modelo recebida:- Contém o
textdo botão do modelo usado ao enviar uma mensagem de modelo. - Contém o
payloaddo botão fornecido ao enviar uma mensagem de modelo. - Contém o wamid (
context.wamid) da mensagem de modelo que você enviou.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
Encaminhe o evento portype, desduplique-o por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.
Mensagem interativa de resposta de lista recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem interativa de resposta de lista recebida:- O campo
interactivecontém a resposta da lista na qual o usuário clicou em uma mensagem interativa que você enviou anteriormente. - O campo
contextcontém informações sobre a mensagem interativa enviada anteriormente ao usuário.
Clique no botão para selecionar um item.
O destinatário responde à sua mensagem selecionando um dos itens na mensagem interativa enviada anteriormente.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
- O
contextcontém informações sobre a mensagem interativa que você enviou anteriormente.context.fromé o WhatsApp ID (número de telefone sem o prefixo ’+’) de quem enviou a mensagem interativa.context.idé o ID da mensagem original na plataforma do WhatsApp, começando comwamid..
Mensagem interativa de resposta de botão recebida
Neste caso, seu endpoint de webhook recebeu uma mensagem interativa de resposta de botão recebida:- O campo
interactivecontém a resposta de botão na qual o usuário clicou em uma mensagem interativa que você enviou anteriormente. - O campo
contextcontém informações sobre a mensagem interativa enviada anteriormente ao usuário.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
- O
contextcontém informações sobre a mensagem interativa que você enviou anteriormente.context.fromé o WhatsApp ID (número de telefone sem o prefixo ’+’) de quem enviou a mensagem interativa.context.idé o ID da mensagem original na plataforma do WhatsApp, começando comwamid..
Mensagem interativa de resposta de fluxo recebida
Após a conclusão do fluxo, uma mensagem de resposta será enviada para o chat do WhatsApp. Você a receberá da mesma forma que recebe todas as outras mensagens do usuário: via webhook de mensagens. O camporesponse_json conterá dados específicos do fluxo.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
interactive.typeé semprenfm_reply.interactive.nameé sempreflow.interactive.bodyé sempreSent.interactive.response_jsonsão dados específicos do fluxo. A estrutura é definida no JSON do fluxo (consulte Ação Complete) ou, se o fluxo estiver usando um endpoint, controlada pelo endpoint (consulte Final Response Payload em Data Exchange Request). Analise a string JSON deinteractive.response_jsonpara um objeto JSON, cujos tipos de dados dos valores podem variar. Normalmente, os valores são texto sem formatação, exceto:- Quando se origina de um componente CheckboxGroup, o valor é uma lista de strings.
- Quando ele se origina de um componente OptIn, o valor é um booleano, ou seja,
trueoufalse. Atualmente, se estiver presente, o valor deve sertrue, já que não haverá essa chave incluída noresponse_jsonse o usuário não optou pelo opt-in. - Quando ele se origina de um componente DatePicker, o valor é uma string que representa o timestamp Unix em milissegundos, como
"1725936737548"(ou seja, 2024-09-10T02:52:17.548Z). A partir do Flow JSON versão 5.0, as datas serão definidas no formato “yyyy-MM-dd”, o que torna os valores independentes de fusos horários.
- Para enviar uma mensagem com um Flow, consulte Mensagem de modelo de Flow e Mensagem de Flow interativa.
Mensagem de entrada do sistema
Neste caso, seu endpoint de webhook recebeu uma mensagem de entrada do sistema:- O
typeestá definido comosystem, esystem.typeestá definido comouser_changed_number. - Um usuário altera seu número de telefone no WhatsApp, e
wa_idé o novo ID do WhatsApp (número de telefone sem o prefixo+). user_idé o novo BSUID.previous_user_ididentifica o BSUID anterior quando a Meta o fornece.parent_user_ideprevious_parent_user_idsão BSUIDs principais opcionais, incluídos apenas quando habilitados e fornecidos pela Meta. Mantenha os nomes de campo originais em snake_case dentro desystem.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
Encaminhe o evento portype, faça a deduplicação por id e mova trabalhos lentos ou sujeitos a falhas para um processador assíncrono.
Mensagem de entrada de alteração de BSUID
Você também pode receber uma mensagem de entrada do sistema comsystem.type definido como
user_changed_user_id. O número de telefone do usuário pode permanecer inalterado ou estar
indisponível. Use system.previous_user_id e system.user_id para associar os
BSUIDs anterior e novo quando ambos forem fornecidos. Os campos de BSUID principal são opcionais.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
Este exemplo omitefrom e system.wa_id porque o número de telefone está
indisponível. Se wa_id for fornecido, ele conterá um número de telefone sem o
+ inicial; não presuma que ele seja diferente do número de telefone anterior. Mantenha
seu número de telefone existente quando o evento não fornecer uma substituição.
Mensagem de entrada de pedido
Neste caso, seu endpoint de webhook recebeu uma mensagem de entrada de pedido quando um cliente adiciona um ou mais produtos ao carrinho e envia um pedido:- Contém informações sobre o produto encomendado.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
Encaminhe o evento portype, faça a deduplicação por id e mova trabalhos lentos ou sujeitos a falhas para um processador assíncrono.
Mensagem de entrada de consulta de produto
Neste caso, seu endpoint de webhook recebeu uma mensagem de texto de entrada quando um cliente faz uma consulta sobre um produto:- Contém informações sobre o produto.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- Uma mensagem de consulta de produto é recebida quando um usuário solicita mais informações sobre um produto específico. Ela pode ser recebida em dois cenários:
- Quando um cliente responde a Mensagens de produto único ou de múltiplos produtos.
- Quando um cliente acessa o catálogo de uma empresa por meio de outro ponto de entrada, navega até uma Página de detalhes do produto e clica em Enviar mensagem para a empresa sobre este produto.
Mensagem de entrada de solicitação de boas-vindas
Você pode ser notificado por webhook sempre que um usuário do WhatsApp abrir uma conversa com você pela primeira vez. Isso pode ser útil se você quiser responder a esses usuários com uma mensagem especial de boas-vindas criada por você. Se você habilitar esse recurso e um usuário abrir uma conversa, normalmente quando ele toca em um link universal (links wa.me ou api.whatsapp.com ), o cliente do WhatsApp verifica se existe um histórico de mensagens entre o usuário e o número de telefone da sua empresa. Se não houver nenhum, o cliente aciona um webhookrequest_welcome. Você pode, então, responder ao usuário com sua própria mensagem de boas-vindas.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
- Para ativar esse recurso para um número de telefone, navegue até o Meta Gerenciador do WhatsApp > Números de telefone > Configurações > Automações.
- Para testar a mensagem
request_welcome, se você já tiver uma conversa em andamento com o número de telefone da empresa, primeiro será necessário excluir a conversa. - Esse recurso apenas aciona uma mensagem de entrada
request_welcomee não responde a nenhuma mensagem automaticamente. Cabe a você decidir se deseja enviar uma mensagem de boas-vindas como resposta.
SMS de entrada
Usesms.inbound.received quando um usuário responder ao seu SMS.
Requisição
Resposta
Confirme o recebimento após aceitar o evento de forma durável.Explicação
Leia a resposta desmsInbound.text. from é o número de telefone do usuário, to é o seu Sender ID registrado e sendTime é o horário de envio da mensagem. Não analise este evento como whatsappInboundMessage.
Preferência de marketing do WhatsApp
Usewhatsapp.user.preferences quando um usuário do WhatsApp interromper ou retomar mensagens de marketing.
Requisição
Resposta
Confirme a entrega após aceitar o evento de forma duradoura.Explicação
Leiacategory e value de whatsappUserPreference; este exemplo registra uma solicitação para interromper mensagens de marketing. Use os identificadores comerciais e os identificadores de cliente fornecidos para corresponder à preferência. parentUserId é omitido quando os BSUIDs pais não estão ativados. Mantenha detail como texto explicativo e preserve o timestamp fornecido. Este é um evento dedicado de preferência, não uma mensagem de chat recebida ou uma carga útil de contact.unsubscribe.created.
Texto recebido do Messenger
Assinemessenger.inbound_message.received para mensagens de texto comuns individuais. Verifique o cabeçalho YCloud-Signature antes de aceitar o evento. 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 mensagens recebidas repetidas por messengerInboundMessage.id.
Requisição
Resposta
Explicação
O PSID do cliente éfrom e o ID da Página do Facebook é to. Preserve o texto exatamente como está, incluindo espaços. sendTime é o horário salvo do evento de origem; createTime é o horário de persistência local. Este evento transporta apenas mensagens de texto comuns. Entregas repetidas da origem podem criar outro evento para o mesmo ID de mensagem salvo.
Edição de texto recebido do Messenger
Assinemessenger.inbound_message.updated para receber o texto mais recente de uma mensagem recebida existente. Verifique YCloud-Signature antes de processar a carga útil.
Requisição
Resposta
Explicação
Mantenha o mesmoid e metaMessageId da mensagem ao atualizar seu registro. O novo text.body, o editCount cumulativo e editTime descrevem a edição salva. O sendTime e createTime da mensagem retêm seus valores originais; o createTime do evento é o horário da edição. Mensagens não editadas omitem os campos de edição. Apenas mensagens recebidas existentes são atualizadas; originais ausentes e versões de edição substituídas não são reconstruídos. Novas tentativas de entrega mantêm o ID do evento, mas o reprocessamento de origem pode criar um novo ID de evento. Use o ID da mensagem e a contagem de edições para lidar com duplicatas e ordenação.
