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.Direct Send para conteúdo de utilidade
O Direct Send pode enviar conteúdo de utilidade qualificado ou converter um modelo de utilidade existente. Ele funciona com qualquer um dos endpoints de envio. O endpointsendDirectly controla o envio síncrono; ele não ativa o Direct Send por si só.
Siga as melhores práticas do Direct Send para elegibilidade, solicitações, conversão de modelos, limites e eventos de 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 de solicitação comuns
Forneça pelo menos um de
to ou recipient. Se você incluir ambos, a YCloud usará
to e ignorará recipient.
Modelos de autenticação de um toque, zero toque e cópia de código exigem um número
de telefone. Use
to para esses tipos de modelo.Exemplos de requisiçã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 de contatos
Mensagem de contatos
Mensagem de reação
Mensagem de reação
Adicionar variáveis de modelo
Faça a correspondência do nome do modelo, idioma e ordem dos parâmetros com o seu modelo aprovado. Para um corpo com parâmetros de nome do cliente e 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 citada. 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 da YCloud.
Ambos têm como padrão false e não se aplicam a sendDirectly.
Inspecione whatsappMessage.errorCode nos Webhooks de status para
RECIPIENT_UNSUBSCRIBED ou RECIPIENT_IN_BLOCK_LIST. Não espere um status
filtered separado. Aplique a supressão em sua aplicação antes de usar
sendDirectly.
Use externalId para associar mensagens a um pedido ou outro registro interno.
Trata-se de um campo de correlação, não de uma chave de idempotência do lado do servidor.
Resposta
Uma resposta bem-sucedida retorna o objeto de mensagem da YCloud. Um status inicial destatus: accepted significa que a YCloud aceitou a requisiçã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 de resposta
Status de entrega
Inscreva-se nos Webhooks dewhatsapp.message.updated para receber alterações de status posteriores,
como sent, failed, delivered ou read.
Use GET /whatsapp/messages/{id} quando precisar recuperar uma mensagem diretamente.
Limites e solução de problemas
- Envios comuns de modelo exigem um modelo
APPROVED; modelosARCHIVEDnão podem ser enviados como mensagens de modelo comuns. - Não tente novamente uma requisição aceita sem uma estratégia de idempotência. Uma requisição repetida pode enviar uma mensagem duplicada.
- Use
id,wamid,externalIde o status de Webhook da YCloud ao investigar a entrega. - Inspecione
whatsappApiErrorquando uma requisição direta alcançar a Meta e a Meta a rejeitar.
Melhores práticas de Direct Send
Envie conteúdo de utilidade, converta modelos e monitore eventos de categoria e restrição.
Melhores práticas de produção
Projete sincronização de status, tentativas limitadas, verificações de consentimento, reutilização de mídia
e controles de taxa de transferência (throughput) para uma integração de produção.
Use IDs de usuário no escopo da empresa
Envie mensagens e chamadas por BSUID, solicite números de telefone, gerencie entradas da lista de contatos
da Meta e processe campos de webhook de BSUID.

