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
APPROVEDpara 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: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 endpointsendDirectly 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/sendDirectlyquando 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
externalIde processe os Webhookswhatsapp.message.updatedantes de decidir se deve tentar novamente.
Solicitação
Para modelos de marketing com Max Price, qualquer um dos endpoints de envio aceitabidSpec.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
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.
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:
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
Mensagem de modelo
Mensagem de modelo
Mensagem de texto
Mensagem de texto
Mensagem de imagem
Mensagem de imagem
Mensagem de vídeo
Mensagem de vídeo
Mensagem de áudio
Mensagem de áudio
Mensagem de documento
Mensagem de documento
Mensagem de figurinha
Mensagem de figurinha
Mensagem de localização
Mensagem de localização
Mensagem interativa
Mensagem interativa
Mensagem para contatos
Mensagem para contatos
Mensagem de reação
Mensagem de reaçã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:Responder a uma mensagem específica
Definacontext.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
ParaPOST /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. Umstatus: 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 dowhatsapp.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.
Limites e solução de problemas
- Envios de modelo comuns exigem um modelo
APPROVED; modelosARCHIVEDnã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,externalIddo YCloud e o status do Webhook quando investigando a entrega. - Inspecione
whatsappApiErrorquando uma solicitação direta chega à Meta e a Meta rejeita isso.
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.

