O que é o Envio Direto
O Direct Send permite que você envie mensagens de utilidade e de autenticação iniciadas pela empresa sem criar modelos primeiro. Envie o conteúdo completo ecategory pela API YCloud WhatsApp Messages; a Meta associa ou gera o modelo.
Use Utilidade para mensagens vinculadas a uma ação ou solicitação do cliente, como atualizações de pedidos e lembretes de compromissos. Use Autenticação para verificação de identidade com senhas de uso único (OTPs). As mensagens de marketing usam modelos regulares.
Antes de começar
- Obtenha uma chave de API do YCloud e conecte um número de telefone comercial do WhatsApp.
- Verifique se sua conta do WhatsApp Business (WABA) tem acesso ao Direct Send para a categoria selecionada. Consulte os requisitos de elegibilidade.
- Obtenha a permissão do cliente e siga as diretrizes de categoria da Meta.
Enviar mensagens
DefinaYCLOUD_API_KEY como sua chave de API e substitua os placeholders de número de telefone por números no formato E.164. O exemplo abaixo usa envio síncrono; você também pode enviar de forma assíncrona.
Exemplos de mensagens utilitárias
Cada aba contém uma solicitação cURL completa. Substitua a chave de API, os números de telefone e as URLs de exemplo antes de enviar.- Texto
- Botões de resposta
- Botão de URL
- Cabeçalho de mídia
X-API-Key e defina Content-Type: application/json.
sendDirectly controla o momento do envio; ele não habilita o Direct Send por si só. Acompanhe o resultado da entrega por meio de status da mensagem e callbacks.
Parâmetros da solicitação
category e useDirectSend envia uma mensagem comum de formato livre, o que exige uma janela de atendimento ao cliente de 24 horas aberta.
Exemplos de OTP de autenticação
Escolha uma das três experiências de OTP abaixo. Cada exemplo é um corpo de solicitação YCloud completo para qualquer um dos endpoints em APIs síncronas e assíncronas. Sua WABA precisa ter acesso ao OTP de envio direto de autenticação. Use um número de telefone emto; a autenticação não oferece suporte a um destinatário com ID de usuário com escopo empresarial (BSUID).
123456 em ambos otp.code e interactive.body.text. Use de 4 a 10 letras ou dígitos ASCII e inclua o código como um valor independente no corpo.
- copiar_código
- um_toque
- zero_toque
copy_code para um botão de copiar código. Omita supported_apps, autofill_text e zero_tap_terms_accepted.supported_apps aceita de 1 a 5 apps Android com nomes de pacote exclusivos. Cada signature_hash deve conter exatamente 11 caracteres. O nome de pacote e o hash de exemplo acima são apenas exemplos; eles não ativarão o preenchimento automático do seu app. Consulte configuração do app e regras completas dos parâmetros.
code_expiration_minutes descreve a validade do código em minutos; seu aplicativo deve verificar o código e garantir que a expiração seja respeitada. ttlSeconds controla por quanto tempo o WhatsApp tenta realizar a entrega. O Envio direto de autenticação aceita de 30 a 900 segundos e usa 600 segundos por padrão.
No iOS 26 e versões posteriores, mensagens de cópia de código e de um toque podem fornecer sugestões de teclado para códigos numéricos de 4 a 8 dígitos quando as notificações do WhatsApp e o preenchimento automático do código de segurança estiverem habilitados. O zero-tap é exclusivo do Android. Consulte as experiências de OTP da Meta.
O envio direto de autenticação somente com texto também continua com suporte. Uma mensagem entregue confirma a entrega, não que o handshake de preenchimento automático do Android tenha sido bem-sucedido.
Tempo de vida da entrega (TTL)
DefinattlSeconds para interromper as tentativas de entrega depois que a mensagem não for mais útil.
ttlSeconds: 1800 define uma validade de entrega de 30 minutos para uma atualização de Utilidade. A Autenticação tem um máximo de 15 minutos. O TTL não exclui mensagens entregues nem substitui as verificações de expiração de OTP do seu aplicativo. Referência de TTL da Meta.
Nomes personalizados de modelos
Opcionalmente, definatemplateName para nomear um modelo de Direct Send do tipo Utility. Para habilitar o Direct Send, defina também category: "utility" ou useDirectSend: true.
Solicitar com um nome de modelo personalizado
Solicitar com um nome de modelo personalizado
templateName antes de aceitar uma solicitação de envio. Se o nome for inválido ou já estiver em uso por um modelo comum, atualize-o e tente novamente.
Use de 1 a 512 letras minúsculas, dígitos ou sublinhados. O YCloud rejeita letras maiúsculas, espaços e outros caracteres.
A mesma WABA não pode usar um nome que pertença a um modelo de mensagem regular existente do WhatsApp, incluindo um modelo rejeitado. Modelos excluídos não reservam o nome, e você pode reutilizar um nome que a Meta gerou anteriormente para o Direct Send.
Se um modelo comum já usar o nome, a API retorna HTTP 400 com
target templateName e a mensagem A template with the same name already exists.
Monitore o status das mensagens mesmo depois que o YCloud aceitar a solicitação. Para conflitos de nome ou falhas na criação de modelos, consulte erros comuns. As regras de nova tentativa da Meta são descritas em sua referência de modelos nomeados pela empresa.
templateName não é compatível com o Envio direto de autenticação. O YCloud o ignora para mensagens que não usam o Envio direto.
Status da mensagem e callbacks
Status de entrega O YCloud informa a entrega por meio dewhatsapp.message.updated. Salve o id retornado do YCloud e o ID da mensagem do WhatsApp (wamid) para correlacionar as atualizações.
accepted significa que a YCloud aceitou a solicitação; sent significa que ela está em trânsito no WhatsApp. Use delivered, read ou failed para acompanhar o resultado subsequente. Você também pode consultar GET /v2/whatsapp/messages/{id} usando a id da YCloud.
Defina externalId com sua própria referência quando precisar conciliar uma mensagem com seu sistema. Isso não impede envios duplicados. Se uma solicitação atingir o tempo limite, verifique a mensagem original antes de tentar novamente. Configure Webhooks de status.
Callbacks de botão de resposta
Quando um cliente toca em um botão de resposta do Direct Send, a mensagem de entrada contém type: button. Leia a seleção do cliente em button.payload e button.text.
Campos relevantes em um evento de mensagem recebida do YCloud:
Exemplo de webhook de botão de resposta
Exemplo de webhook de botão de resposta
button.payload para identificar a ação e context.id para correlacionar a resposta com o wamid da mensagem original. Não leia esta resposta de interactive.button_reply, que é o formato comum de botão de resposta de formato livre.
Extensões do YCloud
A YCloud oferece visualização e análise de modelos no console, além de uma extensão de API que converte modelos de utilidade existentes em mensagens de envio direto. A Meta é responsável pela correspondência e pela geração de modelos.Ver modelos gerados
Os modelos gerados aparecem no YCloud após a sincronização, que pode ser concluída depois do envio da mensagem. Para encontrá-los:- Abra WhatsApp Manager → Modelos no console do YCloud.
- Selecione o WABA usado para enviar a mensagem.
- Defina Creator → Auto generated. Use Category → Utility para restringir a lista aos modelos Utility.
- Verifique o nome, a categoria, o idioma, o status e o horário da última atualização do modelo. Clique no nome do modelo ou em Insights para abrir a prévia e os detalhes de desempenho.

Set Creator to Auto generated. This test WABA has no matching generated templates.
auto_generated; nomes personalizados correspondem ao nome que você forneceu. Use Creator → Gerado automaticamente para encontrar ambos os tipos. Consulte referência de modelos gerados da Meta.
A página de insights mostra a prévia da mensagem e as estatísticas disponíveis de entrega, falha, leitura e interação para o período selecionado. Use o status e o conteúdo do modelo em conjunto ao investigar um aviso ou um modelo pausado.
Modelos gerados não podem ser editados ou excluídos manualmente. Para alterar uma mensagem de utilitário, atualize o conteúdo na sua requisição de envio. A Meta então faz a correspondência ou gera um modelo para esse conteúdo.
A Meta exclui, após 24 horas, os modelos gerados que nunca foram usados. Os modelos usados anteriormente podem ser arquivados após um período de inatividade.
Converter Modelos para Envio Direto
Esta é uma extensão do YCloud para Modelos Utility existentes. DefinauseDirectSend: true; o YCloud preenche os parâmetros do modelo e envia o conteúdo pelo Direct Send.
template.name seleciona o modelo existente a ser convertido. Use templateName para nomear o modelo que a Meta associa ou gera para o Direct Send de utilitário.
Use um modelo Utilitário do seu WABA. Defina type: "template" e useDirectSend: true e informe o nome, o idioma e todos os parâmetros obrigatórios. O modelo deve atender aos limites de conversão abaixo; ele não precisa ter o status APPROVED.
Modelos de autenticação não podem ser convertidos. Para enviar um OTP por meio do Direct Send, use uma solicitação de autenticação.
Para este exemplo, use um modelo de utilidade existente chamado order_update com o corpo Your order {{1}} has been updated. e sem cabeçalho, rodapé ou botões.
Envie-o de forma assíncrona com a seguinte requisição:
type: "text":
accepted não significa que a mensagem foi entregue. Salve o id retornado e acompanhe whatsapp.message.updated, ou consulte GET /v2/whatsapp/messages/{id}.
Se o YCloud retornar WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT, verifique o cabeçalho, os botões e as variáveis não resolvidas do modelo em relação aos limites abaixo. Se a WABA não puder usar o Direct Send, verifique a elegibilidade dela antes de tentar novamente ou envie um modelo Utility aprovado pelo fluxo de trabalho comum de modelos.
Tempo de vida da mensagem
Para a conversão de modelos, determine a duração da entrega nesta ordem:
- Valor da requisição: Se você fornecer
ttlSeconds, ele terá precedência e deverá ser de 30–43.200 segundos. - Valor do modelo: Caso contrário, use o TTL do modelo quando ele for de 30 a 43.200 segundos. Um TTL de modelo positivo inferior a 30 segundos falha na validação; forneça um
ttlSecondsválido para substituí-lo. - Valor padrão: Se o TTL do modelo não estiver definido, não for positivo ou for superior a 43.200 segundos, use o TTL padrão da Meta.
400 com código WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT.
Antes de converter um modelo com cabeçalho de imagem, confirme se sua WABA pode usar cabeçalhos de mídia. Consulte recursos e limites compatíveis e os requisitos de cabeçalho de mídia da Meta.
Verificações de amostras de mensagem (opcional)
POST /v2/whatsapp/messages/{wabaId}/messageSamples envia um exemplo para a Meta e retorna a categoria detectada sem enviar uma mensagem a um cliente. Este endpoint do YCloud é opcional. Verifique conteúdo representativo ao introduzir um novo caso de uso; um resultado de amostra não isenta as mensagens subsequentes das verificações de categoria e qualidade da Meta.
Substitua WABA_ID pelo seu ID da WABA e defina YCLOUD_API_KEY como sua chave de API. Use dados fictícios de cliente no exemplo:
category antes de usar o conteúdo em uma solicitação de envio direto Utility. Se a Meta detectar MARKETING ou AUTHENTICATION, revise o conteúdo ou use o fluxo de mensagens apropriado. Para uma amostra de botão, envie os campos type e interactive de um exemplo de botão Utility acima; omita os campos de destinatário e de envio.
Recursos e limites compatíveis
Acesso ao WABA Verifique a disponibilidade em Meta WhatsApp Manager → Modelos de mensagem. Portfólios empresariais com limite de mensagens de 100.000 ou ilimitado geralmente são elegíveis para Utilidade; Autenticação está em alfa. Consulte os requisitos de elegibilidade da Meta. Formatos, idiomas e preços de mensagens Os limites a seguir aplicam-se aos formatos de mensagem usados nos exemplos deste guia. Consulte os tipos de mensagem compatíveis da Meta para conhecer os requisitos da plataforma.Diretrizes de integridade e conteúdo
O conteúdo da categoria Utilidade deve ser não promocional e estar vinculado a uma ação ou solicitação do cliente, ou a informações essenciais que atendam aos critérios aplicáveis. Identifique o pedido, agendamento, conta ou transação relevante para que o cliente entenda por que você está entrando em contato. Siga as diretrizes de categoria de modelo da Meta.category: "utility" não substitui a avaliação de conteúdo da Meta.
Para um novo caso de uso, você pode executar uma verificação de amostra de mensagem antes de enviar. Se a Meta sinalizar o conteúdo, examine o aviso de categoria e siga status da conta e solução de problemas, incluindo o processo de revisão quando você não concordar com a decisão.
Status da conta e solução de problemas
Avisos, restrições e revisões Um modelo pode ser pausado devido à baixa qualidade. As mensagens que correspondem a ele, ou que sejam muito semelhantes, podem então falhar com o erro132015 da Meta. Encontre o modelo afetado no YCloud, inspecione o conteúdo e o status dele e resolva a causa antes de retomar as mensagens que o utilizam.
O uso incorreto repetido de categoria pode restringir o Direct Send para toda a WABA:
whatsapp.template.correct_category_detection por meio do seu endpoint de webhook. Compare whatsappTemplate.previousCategory com whatsappTemplate.category; se forem UTILITY e MARKETING, respectivamente, revise a mensagem em busca de conteúdo de marketing. Consulte o exemplo de webhook de detecção de categoria.
Essas notificações referem-se a categorias de modelo e não são disparadas para todas as mensagens. Os resultados da verificação por amostragem vêm da resposta messageSamples; os resultados de entrega chegam por meio de whatsapp.message.updated.
Campos relevantes de um evento de restrição de conta do YCloud:
Exemplo de Webhook de restrição de conta
Exemplo de Webhook de restrição de conta
violationType para saber o motivo e restrictions[].expiration para a expiração, quando fornecida.
Para tipos de violação específicos do Direct Send e os payloads de aviso, restrição e recuperação, consulte o Webhook para restrição de conta da Meta.
Erros comuns
Para erros síncronos, inspecione error.whatsappApiError quando presente. Para mensagens na fila, inspecione os detalhes da falha em whatsapp.message.updated.
Alterações e compatibilidade
Você pode continuar usando o mesmo endpoint síncrono ou assíncrono do YCloud e a autenticaçãoX-API-Key. As solicitações existentes de texto e botão do Utility e as solicitações de texto do Authentication continuam com suporte. A tabela compara o uso existente com as opções disponíveis agora.
Perguntas frequentes sobre envio direto
Preciso de um nome de modelo antes de enviar?
Preciso de um nome de modelo antes de enviar?
category: "utility" ou category: "authentication", e a Meta faz a correspondência ou gera um modelo. Para mensagens de utilidade, você pode opcionalmente definir templateName para nomear o modelo do Direct Send.Para converter um modelo de utilidade existente, forneça template.name e useDirectSend: true. Esses campos têm uma finalidade diferente de templateName. Modelos de autenticação não podem ser convertidos para Direct Send.Por que o Direct Send ainda gera modelos?
Por que o Direct Send ainda gera modelos?
Posso enviar fora da janela de atendimento ao cliente de 24 horas?
Posso enviar fora da janela de atendimento ao cliente de 24 horas?
Por que uma mensagem pode ser enviada com sucesso antes de o modelo gerado aparecer?
Por que uma mensagem pode ser enviada com sucesso antes de o modelo gerado aparecer?
Como é feita a limpeza dos modelos gerados não utilizados?
Como é feita a limpeza dos modelos gerados não utilizados?
Definir a categoria como utility garante que a Meta aceitará a categoria?
Definir a categoria como utility garante que a Meta aceitará a categoria?
Como o Direct Send é cobrado?
Como o Direct Send é cobrado?

