Saltar para o conteúdo principal

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 e category 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.
Para integrações existentes, consulte alterações e compatibilidade.

Enviar mensagens

Defina YCLOUD_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.
APIs síncronas e assíncronas Os dois endpoints aceitam o mesmo corpo da requisição do Direct Send. Autentique com o cabeçalho X-API-Key e defina Content-Type: application/json. O endpoint 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 Omitir ambos 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 em to; a autenticação não oferece suporte a um destinatário com ID de usuário com escopo empresarial (BSUID). Substitua 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.
Use copy_code para um botão de copiar código. Omita supported_apps, autofill_text e zero_tap_terms_accepted.
Para one-tap e zero-tap, 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)

Defina ttlSeconds para interromper as tentativas de entrega depois que a mensagem não for mais útil. Por exemplo, 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, defina templateName para nomear um modelo de Direct Send do tipo Utility. Para habilitar o Direct Send, defina também category: "utility" ou useDirectSend: true.
O YCloud valida 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 de whatsapp.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:
Use 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:
  1. Abra WhatsApp Manager → Modelos no console do YCloud.
  2. Selecione o WABA usado para enviar a mensagem.
  3. Defina Creator → Auto generated. Use Category → Utility para restringir a lista aos modelos Utility.
  4. 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.
Filtro Creator definido como Gerado automaticamente em Modelos

Set Creator to Auto generated. This test WABA has no matching generated templates.

Nomes atribuídos automaticamente começam com 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. Defina useDirectSend: 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:
Exemplo de resposta após o YCloud aceitar a mensagem na fila. O conteúdo já foi convertido para 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:
  1. Valor da requisição: Se você fornecer ttlSeconds, ele terá precedência e deverá ser de 30–43.200 segundos.
  2. 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 ttlSeconds válido para substituí-lo.
  3. 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.
Limites de conversão Os limites a seguir se aplicam à conversão, pelo YCloud, de um modelo Utility existente em conteúdo do Direct Send: Não combine CTA URL com botões de resposta rápida. Outros tipos de cabeçalho e botão não podem ser convertidos. Componentes não suportados ou variáveis do modelo não resolvidas retornam HTTP 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:
Resposta de exemplo:
Verifique 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. Todos os idiomas de modelos do WhatsApp são suportados. Aplicam-se os limites e a taxa de transferência de mensagens padrão. O preço segue a categoria Utilidade ou Autenticação correspondente.

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. Não adicione promoções, descontos ou ofertas de venda cruzada a uma atualização de Utilidade. Use Autenticação para OTPs e modelos de Marketing para conteúdo promocional. Definir 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 erro 132015 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: Siga o aviso da conta para a restrição ativa e o vencimento. Uma revisão bem-sucedida de um modelo não remove automaticamente uma restrição no nível da conta. Solicitar uma revisão de categoria Se você acredita que o conteúdo foi sinalizado incorretamente, abra Central de Suporte do Meta Business → conta do WhatsApp → Atualizações de modelos do Direct Send → Disponível para revisão. Selecione os modelos afetados e escolha Solicitar revisão. Envie a solicitação em até 60 dias após a notificação. Cada modelo sinalizado pode ser revisado uma vez. Acompanhe o resultado como Em análise, Revertido ou Inalterado. Se a opção de revisão não estiver disponível, entre em contato com o YCloud informando o ID da WABA, o nome ou ID do modelo, o idioma e os detalhes da notificação. Notificações de status Inscreva-se em 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:
Use o WABA ID para pausar o fluxo de trabalho afetado. Leia 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ção X-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.
Os novos recursos ainda exigem o relevante acesso à WABA. O Direct Send de autenticação permanece em alfa. A disponibilidade e os formatos da plataforma seguem os requisitos de elegibilidade e os recursos compatíveis da Meta.

Perguntas frequentes sobre envio direto

Não. Envie o conteúdo completo com 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.
A Meta usa modelos para verificações de categoria e qualidade, relatórios de desempenho e solução de problemas. O Direct Send cuida da correspondência e da geração de modelos para você, então você não precisa criar um modelo manualmente antes de enviar. Consulte como o Direct Send funciona.
Sim. O Direct Send oferece suporte a mensagens de utilidade e autenticação iniciadas pela empresa fora da janela de atendimento ao cliente, desde que sua WABA tenha acesso à categoria selecionada e a mensagem atenda aos requisitos de consentimento e conteúdo da Meta. Mensagens comuns de formato livre ainda exigem uma janela de atendimento ao cliente aberta. Consulte elegibilidade e escopo de envio.
O envio direto padrão pode usar um modelo de onboarding enquanto a Meta gera um modelo correspondente de forma assíncrona. A sincronização com o YCloud pode ser concluída depois que a mensagem for enviada. Selecione a WABA correta e use Criador → Gerado automaticamente para encontrar o modelo gerado.Durante a geração de modelos, a Meta oculta informações pessoais e detecta o idioma.Modelos de utilidade nomeados pela empresa não usam este fallback de modelo de onboarding.
A Meta exclui os modelos gerados que nunca foram usados para envio 24 horas após a criação. Os modelos usados anteriormente são arquivados periodicamente após um período de inatividade. A Meta gerencia essa limpeza; os modelos do Direct Send não podem ser editados nem excluídos manualmente. Consulte Perguntas frequentes sobre o Direct Send da Meta.
Não. A Meta avalia o conteúdo real da mensagem. Mantenha conteúdo promocional fora das mensagens de Utilidade. Se você acredita que uma decisão de categoria está incorreta, siga o processo de revisão. Um envio bem-sucedido não isenta mensagens futuras de verificações de categoria ou qualidade.
Mensagens do Direct Send seguem as regras de precificação aplicáveis a Utilitário ou Autenticação. A geração automática de modelos não torna a mensagem gratuita. Consulte preços do WhatsApp para tarifas atuais e condições aplicáveis.