Skip to main content
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 HTTP POST 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 o id do evento como o identificador de entrega e use type para rotear o payload.

Resposta

Retorne um status 2xx 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:
  • type está definido como unsupported.
  • errors explica por que a mensagem não é suportada ou está indisponível.
  • unsupported.type identifica a categoria da mensagem, como poll_creation, poll_update, edit ou pin.

Solicitação

Resposta

Confirme o recebimento após aceitar o evento de forma durável.

Explicação

  • O erro 131051 com Message type unknown significa que a Cloud API do WhatsApp não oferece suporte ao tipo de mensagem.
  • O erro 131060 com This message is currently unavailable. significa que o WhatsApp não pôde fornecer o conteúdo da mensagem.
  • unsupported.type identifica 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 com wamid..

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

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.link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho X-API-Key para 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.link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho X-API-Key para 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.link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho X-API-Key para 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.link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho X-API-Key para 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.link pode ser acessado diretamente em poucos minutos para conveniência do consumidor, mas você deve sempre incluir um cabeçalho X-API-Key para 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 por type, 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_request quando 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 por type, 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 emoji está 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 text do botão do modelo usado ao enviar uma mensagem de modelo.
  • Contém o payload do 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 por type, 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 interactive contém a resposta da lista na qual o usuário clicou em uma mensagem interativa que você enviou anteriormente.
  • O campo context conté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 context conté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 com wamid..

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 interactive contém a resposta de botão na qual o usuário clicou em uma mensagem interativa que você enviou anteriormente.
  • O campo context contém informações sobre a mensagem interativa enviada anteriormente ao usuário.
example-inboundmessage-buttonreply.png

Requisição

Resposta

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

Explicação

  • O context conté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 com wamid..

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 campo response_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 é sempre nfm_reply. interactive.name é sempre flow. interactive.body é sempre Sent.
  • interactive.response_json sã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 de interactive.response_json para 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, true ou false. Atualmente, se estiver presente, o valor deve ser true, já que não haverá essa chave incluída no response_json se 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 type está definido como system, e system.type está definido como user_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_id identifica o BSUID anterior quando a Meta o fornece.
  • parent_user_id e previous_parent_user_id são BSUIDs principais opcionais, incluídos apenas quando habilitados e fornecidos pela Meta. Mantenha os nomes de campo originais em snake_case dentro de system.

Requisição

Resposta

Confirme o recebimento após aceitar o evento de forma durável.

Explicação

Encaminhe o evento por type, 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 com system.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 omite from 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 por type, 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 webhook request_welcome. Você pode, então, responder ao usuário com sua própria mensagem de boas-vindas. example-inboundmessage-welcomemessage

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_welcome e não responde a nenhuma mensagem automaticamente. Cabe a você decidir se deseja enviar uma mensagem de boas-vindas como resposta.

SMS de entrada

Use sms.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 de smsInbound.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

Use whatsapp.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

Leia category 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

Assine messenger.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

Assine messenger.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 mesmo id 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.