Saltar para o conteúdo principal

O que é

A API de Mensagens do WhatsApp envia mensagens de modelo, texto, imagem, vídeo, áudio, documento, figurinha, localização, interativas, de contato e de reação a partir de um número de telefone comercial do WhatsApp conectado.

Antes de começar

  • Armazene sua chave de API da YCloud em YCLOUD_API_KEY.
  • Conecte uma conta do WhatsApp Business e um número de telefone à YCloud.
  • Colete o número de telefone do remetente no formato E.164 e o número de telefone do destinatário, BSUID ou BSUID pai.
  • Use um modelo APPROVED para envios comuns de modelos.
  • Carregue a mídia primeiro quando a mensagem fizer referência a um ID de mídia da YCloud.

Como funciona

Escolha o endpoint com base em quando a YCloud deve enviar a mensagem para a WhatsApp Business API. Ambos os endpoints retornam um objeto de mensagem da YCloud. A resposta inicial não confirma a entrega final. Alterações de status posteriores chegam por meio de Webhooks whatsapp.message.updated.

Envie sua primeira mensagem

Escolha um modelo aprovado pertencente à sua WABA conectada. Substitua o remetente, o destinatário, o nome do modelo e o idioma pelos seus próprios valores e, em seguida, envie:
Armazene o id retornado e acompanhe seus eventos whatsapp.message.updated. Uma resposta accepted significa que a solicitação entrou em processamento, não que o cliente a recebeu. Configure tanto whatsapp.message.updated quanto whatsapp.inbound_message.received quando precisar de rastreamento de entrega e respostas.

Escolha uma mensagem de modelo ou de sessão

Use um modelo aprovado para mensagens comuns iniciadas pela empresa fora da janela de atendimento ao cliente. Dentro de uma janela aberta, use tipos de mensagens livres suportados, como texto, mídia ou respostas interativas. Verifique as regras da janela de atendimento ao cliente no momento do envio. Uma janela de preços não substitui a qualificação de envio de mensagens. Consulte preços do WhatsApp para cobranças atuais e condições de ponto de entrada.

Envio direto para conteúdo de Utilidade e Autenticação

O Envio direto oferece suporte a mensagens de Utilidade e Autenticação iniciadas pela empresa sem criar modelos de mensagem antes. A YCloud também oferece suporte à conversão de modelos de Utilidade existentes. O Envio direto funciona com qualquer um dos endpoints de envio. O endpoint sendDirectly controla o envio síncrono; ele não habilita o Envio direto por si só. Para Autenticação, o Envio direto aceita texto ou um botão OTP interativo explícito. Um modelo de Autenticação não pode ser convertido em uma mensagem de Envio direto. Siga as práticas recomendadas de envio direto para elegibilidade, solicitações, conversão de modelo, limites e eventos da conta.

Escolha o melhor horário de envio

Faça coincidir o horário de envio com o objetivo da mensagem e o horário local do destinatário.
  • Envie OTPs e outras mensagens sensíveis ao tempo imediatamente. Use POST /whatsapp/messages/sendDirectly quando seu fluxo de trabalho precisar do resultado do envio antes de continuar.
  • Envie atualizações transacionais quando o evento relacionado ocorrer, como um pagamento, envio ou alteração de agendamento.
  • Agende mensagens de marketing para horários razoáveis no fuso horário do destinatário. Use seus próprios dados de entrega, leitura e conversão para testar diferentes intervalos de tempo para cada público em vez de presumir um único melhor horário universal.
  • Inicie uma campanha agendada com um grupo pequeno de destinatários. Verifique os resultados de entrega, resposta e cancelamento antes de enviar para o restante do público.
  • Evite envios repetidos quando uma mensagem estiver atrasada. Armazene externalId e processe os Webhooks whatsapp.message.updated antes de decidir se deve tentar novamente.

Solicitação

Para modelos de marketing com Max Price, qualquer um dos endpoints de envio aceita bidSpec.per_message_bid_multiplier. Omita todo o objeto bidSpec para usar um multiplicador de 1. Consulte o guia de integração do Max Price para multiplicadores por país, limites de lances e webhooks de cobrança final. Escolha um dos endpoints acima e, em seguida, use o corpo da solicitação correspondente ao tipo de mensagem. O valor de from é o seu número de telefone comercial do WhatsApp conectado. Enderece o destinatário com to no formato E.164 ou com recipient definido como um BSUID ou BSUID pai.

Campos comuns da requisição

filterUnsubscribed e filterBlocked se aplicam apenas a POST /whatsapp/messages; eles não se aplicam a sendDirectly. Um filtrado mensagem enfileirada falha com RECIPIENT_UNSUBSCRIBED ou RECIPIENT_IN_BLOCK_LIST em seu webhook de status. Para envios síncronos, implemente verificações de consentimento, descadastro e bloqueio em seu aplicativo.
Forneça pelo menos um de to ou recipient. Se você incluir ambos, o YCloud usa to e ignora recipient.
Modelos de autenticação com um toque, sem toque e com código para copiar exigem um telefone número. O OTP de envio direto explícito também exige um número de telefone: use to, não recipient isoladamente.

Envio direto com autenticação explícita para OTP

A Meta está lançando o Authentication Direct Send em alfa. A WABA do remetente precisa de acesso ao envio interativo de OTP pelo Authentication Direct Send. Uma requisição de Authentication Direct Send somente de texto que tenha sucesso não confirma o acesso aos botões de OTP.
Use o mesmo corpo de requisição com POST /v2/whatsapp/messages/sendDirectly para envio síncrono ou POST /v2/whatsapp/messages para envio em fila. Defina type como interactive, category como authentication, interactive.type como button e forneça exatamente um botão com type: "otp". Defina interactive.action.buttons[0].otp.code como uma string de 4–10 letras ou dígitos ASCII. Inclua o mesmo código como um valor independente em interactive.body.text. No iOS 26 e versões posteriores, mensagens de código para copiar e de um toque podem fornecer sugestões de teclado para códigos numéricos de 4–8 dígitos. As notificações do WhatsApp e o preenchimento automático do código de segurança devem estar habilitados no dispositivo do destinatário. Isso não exige integração adicional de app iOS; o zero-tap continua sendo exclusivo do Android. Consulte Experiências de OTP da Meta. Copiar código:
Preenchimento automático com um toque:
Preenchimento automático sem toque:
Para um toque e zero toque, forneça de 1 a 5 apps Android com nomes de pacote exclusivos e um hash de chave de assinatura de 11 caracteres para cada app. Substitua o nome de pacote e o hash de exemplo pelos valores do seu app. Os nomes de pacote podem conter no máximo 224 caracteres e devem ter pelo menos dois segmentos separados por ponto; cada segmento começa com uma letra e contém apenas letras, dígitos ou sublinhados. Configure o handshake de OTP do WhatsApp do seu app antes de solicitar um código. Para requisitos de configuração e de dispositivo, consulte Guia de experiências de OTP da Meta. Defina zero_tap_terms_accepted como true em cada solicitação de zero toque para confirmar os termos de zero toque da Meta em nome da sua empresa. Omita esse campo para um toque e para copiar código. Para copiar código, omita também supported_apps e autofill_text. Os campos opcionais do botão, text e autofill_text, são limitados a 25 caracteres e não devem ficar vazios nem conter variáveis, quebras de linha, formatação, URLs ou emojis. code_expiration_minutes especifica o tempo de expiração do código, de 1 a 90 minutos (o padrão da Meta é 10). Seu aplicativo ainda deve verificar o código e garantir que a expiração seja respeitada. O campo separado ttlSeconds controla o tempo de vida da entrega da mensagem: o Envio direto de autenticação aceita de 30 a 900 segundos e usa 600 segundos por padrão. Consulte Limites de TTL do envio direto. Verifique whatsapp.message.updated para obter o status de entrega e confirme o preenchimento automático em um dispositivo elegível. Uma mensagem entregue por si só não confirma que um handshake de preenchimento automático foi bem-sucedido.

Exemplos de solicitação

Adicionar variáveis do modelo

Faça com que o nome do modelo, o idioma e a ordem dos parâmetros correspondam ao modelo aprovado. Para um corpo com parâmetros de nome do cliente e de referência do pedido, envie:
Consulte exemplos de modelos de mensagem para componentes e tipos de mensagem adicionais.

Responder a uma mensagem específica

Defina context.message_id como o ID da mensagem original do WhatsApp (wamid) para criar uma resposta com citação. Continue verificando se a janela de atendimento ao cliente está aberta.

Aplicar filtros de cancelamento de inscrição e bloqueio

Para POST /whatsapp/messages, defina filterUnsubscribed: true e filterBlocked: true quando precisar aplicar suas listas de supressão do YCloud. Ambos têm false como padrão e não se aplicam a sendDirectly. Inspecione whatsappMessage.errorCode em webhooks de status para RECIPIENT_UNSUBSCRIBED ou RECIPIENT_IN_BLOCK_LIST. Não espere um status filtered separado. Garanta a supressão em seu aplicativo antes de usar sendDirectly. Use externalId para associar mensagens a um pedido ou a outro registro interno. É um campo de correlação, não uma chave de idempotência do lado do servidor.

Resposta

Uma resposta bem-sucedida retorna o objeto de mensagem do YCloud. Um status: accepted inicial significa que o YCloud aceitou a solicitação de envio. Isso não significa que a mensagem foi enviada pela Meta ou entregue ao usuário do WhatsApp.

Exemplo de resposta

Campos da resposta

Status de entrega

Inscreva-se nos Webhooks do whatsapp.message.updated para receber alterações posteriores de status, como sent, failed, delivered ou read. Use GET /whatsapp/messages/{id} quando precisar recuperar uma mensagem diretamente.
Para mensagens de mídia, primeiro faça o upload do arquivo com POST /whatsapp/media/{phoneNumber}/upload e, em seguida, use o ID de mídia retornado no payload da mensagem.

Limites e solução de problemas

  • Envios de modelo comuns exigem um modelo APPROVED; modelos ARCHIVED não podem ser enviados como modelos de mensagem comuns.
  • Não repita uma solicitação aceita sem uma estratégia de idempotência. Uma repetição a requisição pode enviar uma mensagem duplicada.
  • Use os id, wamid, externalId do YCloud e o status do Webhook quando investigando a entrega.
  • Inspecione whatsappApiError quando uma solicitação direta chega à Meta e a Meta rejeita isso.
Para limites de throughput, consulte Limites de taxa.

Práticas recomendadas de envio direto

Envie conteúdo de utilitário, converta modelos e monitore eventos de categoria e restrição.

Práticas recomendadas para produção

Projete a sincronização de status, tentativas limitadas, verificações de consentimento, reutilização de mídia, e controles de taxa de transferência para uma integração de produção.

Use IDs de usuário com escopo de empresa

Enviar mensagens e chamadas por BSUID, solicitar números de telefone, gerenciar contato da Meta entradas de livro e processe campos de Webhook do BSUID.

Exemplos completos de integração

Para o fluxo completo de criação de modelos e vinculação de variáveis, consulte Exemplos de criação de modelos e Exemplos de mensagens. Use Tratamento de erros do WhatsApp para distinguir a rejeição da solicitação de falhas de entrega posteriores e Implementação do receptor de Webhook para verificar assinaturas e aceitar atualizações de status de forma durável.