Saltar para o conteúdo principal
Para conferir o catálogo completo derivado do esquema, consulte todos os exemplos.

O que é

Processe mensagens de entrada do WhatsApp, Messenger e SMS, além das 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 requisiçã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.

Requisição

Os cenários abaixo mostram requisições entregues na sua URL de webhook. Trate o id do evento como o identificador de entrega e utilize type para rotear o payload.

Resposta

Retorne um status 2xx após aceitar o evento.
Para saber mais sobre configuração de endpoint, validação de assinatura e comportamento de repetição, consulte Configurar webhooks.

Mensagem de entrada não suportada

Neste caso, seu endpoint de webhook recebeu uma mensagem de entrada 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.

Requisição

Resposta

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

Explicação

  • O erro 131051 com Message type unknown indica que a WhatsApp Cloud API não suporta esse tipo de mensagem.
  • O erro 131060 com This message is currently unavailable. indica que o WhatsApp não conseguiu fornecer o conteúdo da mensagem.
  • unsupported.type identifica a categoria geral. Ele não contém o conteúdo da mensagem original.
  • Consulte Mensagens não suportadas no Inbox para obter uma lista clara dos tipos de mensagem. Consulte a referência de webhook de mensagens não suportadas da Meta para verificar o contrato de payload atual.

Mensagem de texto de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de texto de entrada:
  • Contém texto simples enviado pelo usuário.
  • Contém as informações da mensagem mencionada em context.

Requisição

Resposta

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

Explicação

  • Mensagens de entrada 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 utilizado 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 de entrada disparada por clique em anúncios do WhatsApp

Neste caso, seu endpoint de webhook recebeu uma mensagem de texto de entrada disparada por clique em anúncios do WhatsApp:
  • Contém texto simples.
  • Contém informações sobre o anúncio.

Requisição

Resposta

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

Explicação

Mensagem de imagem de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de imagem de entrada:
  • Contém a URL de uma imagem.
  • Contém legenda que descreve esta imagem.

Requisição

Resposta

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

Explicação

  • A image.link pode ser acessada 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 de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de vídeo de entrada:
  • Contém a URL de um vídeo.
  • Contém legenda que descreve este vídeo.

Requisição

Resposta

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

Explicação

  • A video.link pode ser acessada 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 de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de áudio de entrada:
  • Contém a URL de um áudio.

Requisição

Resposta

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

Explicação

  • A audio.link pode ser acessada 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 de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de documento de entrada:
  • Contém a URL de um documento.
  • Contém legenda que descreve este documento.

Requisição

Resposta

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

Explicação

  • A document.link pode ser acessada 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 de entrada

Neste caso, seu endpoint de webhook recebeu uma mensagem de figurinha de entrada:
  • Contém a URL de uma figurinha.

Solicitação

Resposta

Confirme o recebimento 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 a latitude e a longitude do local.
  • Contém o nome, o endereço e a URL do local.

Solicitação

Resposta

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

Explicação

Encaminhe o evento por type, desduplique-o por id e mova tarefas lentas ou propensas 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.

Solicitação

Resposta

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

Explicação

Encaminhe o evento por type, desduplique-o por id e mova tarefas lentas ou propensas 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.

Solicitação

Resposta

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

Explicação

  • O campo 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 botão text do modelo que você usou ao enviar uma mensagem de modelo.
  • Contém o botão payload que você forneceu ao enviar uma mensagem de modelo.
  • Contém o wamid (context.wamid) da mensagem de modelo que você enviou.

Solicitação

Resposta

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

Explicação

Encaminhe o evento por type, desduplique-o por id e mova tarefas lentas ou propensas a falhas para um processador assíncrono.

Mensagem de resposta de lista interativa recebida

Neste caso, seu endpoint de webhook recebeu uma mensagem de resposta de lista interativa recebida:
  • O campo interactive contém a resposta de lista que o usuário clicou em uma mensagem interativa enviada anteriormente por você.
  • O campo context contém informações sobre a mensagem interativa que você enviou anteriormente para o usuário.
Clique no botão para selecionar um item. O destinatário responde à sua mensagem selecionando um dos itens na mensagem interativa que você enviou anteriormente.

Solicitação

Resposta

Confirme o recebimento 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 de resposta de botão interativo recebida

Neste caso, seu endpoint de webhook recebeu uma mensagem de resposta de botão interativo recebida:
  • O campo interactive contém a resposta de botão que o usuário clicou em uma mensagem interativa enviada anteriormente por você.
  • O campo context contém informações sobre a mensagem interativa que você enviou anteriormente para o usuário.
example-inboundmessage-buttonreply.png

Solicitação

Resposta

Confirme o recebimento 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 de resposta de Flow interativo 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 mensagem. O campo response_json conterá dados específicos do fluxo.

Solicitação

Resposta

Confirme o recebimento 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 Complete action) ou, se o fluxo estiver usando um endpoint, controlada pelo endpoint (consulte Final Response Payload em Data Exchange Request). Faça o parse da string JSON interactive.response_json para um objeto JSON, onde o tipo de dados de seus valores pode variar. Normalmente, os valores são texto simples, exceto:
    • Quando se originar de um componente CheckboxGroup, o valor será uma lista de strings.
    • Quando tem origem em um componente OptIn, o valor é um booleano, ou seja, true ou false. Atualmente, se presente, o valor deve ser true, já que nenhuma chave desse tipo será incluída no response_json se o usuário não tiver escolhido aceitar (opt-in).
    • Quando tem origem em 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 da versão 5.0 do Flow JSON, 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 interativa de Flow.

Mensagem de sistema recebida

Neste caso, seu endpoint de webhook recebeu uma mensagem de sistema recebida:
  • O type está definido como system, e o 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. parent_user_id só é incluído quando os BSUIDs pai estão habilitados.

Requisição

Resposta

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

Explicação

Roteie o evento por type, deduplique-o por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Mensagem de pedido recebida

Neste caso, seu endpoint de webhook recebeu uma mensagem de pedido recebida 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 a entrega após aceitar o evento de forma duradoura.

Explicação

Roteie o evento por type, deduplique-o por id e transfira tarefas lentas ou sujeitas a falhas para um processador assíncrono.

Mensagem de consulta de produto recebida

Neste caso, seu endpoint de webhook recebeu uma mensagem de texto recebida quando um cliente consulta um produto:
  • Contém informações sobre o produto.

Requisição

Resposta

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

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 Conversar com a empresa sobre este produto.

Mensagem de solicitação de boas-vindas recebida

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 de boas-vindas especial personalizada 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 já existe uma conversa entre o usuário e o número de telefone da sua empresa. Se não houver, 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 a entrega após aceitar o evento de forma duradoura.

Explicação

  • Para ativar esse recurso para um número de telefone, navegue até Meta WhatsApp Manager > 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, deverá primeiro excluir a conversa.
  • Esse recurso apenas aciona uma mensagem request_welcome recebida e não responde nenhuma mensagem automaticamente. Cabe a você decidir se deseja enviar uma mensagem de boas-vindas.

SMS recebido

Use sms.inbound.received quando um usuário responder ao seu SMS.

Requisição

Resposta

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

Explicação

Leia a resposta em 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 da empresa e os identificadores do cliente fornecidos para corresponder à preferência. parentUserId é omitido quando os BSUIDs pai não estão habilitados. Mantenha detail como texto explicativo e preserve o timestamp fornecido. Este é um evento de preferência dedicado, não uma mensagem de chat recebida ou um payload contact.unsubscribe.created.

Texto recebido do Messenger

Assine messenger.inbound_message.received para mensagens de texto individuais comuns. 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 produzir 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, incluindo espaços. sendTime é o horário do evento de origem salvo; createTime é o horário de persistência local. Este evento transporta apenas mensagens de texto comuns. A entrega de origem repetida pode 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 os mesmos id e metaMessageId da mensagem ao atualizar seu registro. O novo text.body, o cumulativo editCount e o editTime descrevem a edição salva. O sendTime e o createTime da mensagem mantê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.