Saltar para o conteúdo principal
O Meta Direct Send permite que empresas qualificadas enviem mensagens de Utilidade enviando o conteúdo completo. A Meta cuida da correspondência e da geração de modelos em segundo plano. Este guia aborda o Direct Send de Utilidade por meio da YCloud. Para envio de mensagens gerais, consulte Enviar uma mensagem do WhatsApp.

​
Como o Direct Send funciona

O Direct Send usa modelos nos bastidores. Você envia o texto finalizado ou conteúdo interativo suportado em vez de criar um modelo antes do envio. A Meta compara o conteúdo da sua mensagem com um modelo existente. Se não houver correspondência, a Meta remove informações de identificação pessoal, detecta o idioma e gera um novo modelo em segundo plano para futuras mensagens correspondentes. Por exemplo, “Seu pedido A123456 foi enviado” e “Seu pedido B789012 foi enviado” compartilham a mesma estrutura. Notificações posteriores podem reutilizar um modelo gerado correspondente. Os modelos gerados retêm informações de categoria, qualidade e desempenho. Isso permite identificar quais conteúdos estão tendo bom desempenho ou causando problemas de entrega, mesmo que você mesmo não tenha criado o modelo.

​
Recursos suportados e limites

​
Qualificação e escopo de envio

Portfólios de negócios com um limite de mensagens de 100.000 ou ilimitado geralmente são qualificados para o Direct Send de Utilidade. Conecte sua WABA e o número de telefone comercial à YCloud. Em Meta WhatsApp Manager → Modelos de mensagem, verifique se a sua empresa é qualificada para o Direct Send. Se o acesso não estiver disponível para a sua WABA, use um modelo de Utilidade aprovado ou entre em contato com a YCloud para verificar a qualificação. O Direct Send de Utilidade pode iniciar uma notificação esperada fora da janela de atendimento ao cliente de 24 horas. Obtenha a permissão do cliente e mantenha o conteúdo vinculado à sua solicitação, transação, conta ou informações essenciais qualificadas. Promoções e códigos de verificação estão fora deste fluxo de trabalho de Utilidade.

​
Tamanho da mensagem e botões

Os exemplos de envio abaixo usam cabeçalhos de texto. Mensagens de texto não exibem pré-visualizações de URL. Limites de conta e controles de taxa de transferência ainda se aplicam. Use cabeçalhos de texto para solicitações personalizadas de Direct Send interactive.

​
Tempo de vida da entrega (TTL)

O ttlSeconds define por quanto tempo uma mensagem pode permanecer elegível para entrega. Se não puder ser entregue dentro desse período, ela será descartada. Uma mensagem entregue não é excluída quando o seu TTL expira. O padrão e o intervalo personalizado permitido diferem. Para uma atualização de entrega que seja útil por apenas 30 minutos, defina ttlSeconds: 1800; não deixe no valor padrão.

​
Suporte a idiomas

O Direct Send suporta idiomas de modelos do WhatsApp exceto: Use um idioma suportado para fluxos de trabalho do Direct Send.

​
Tipos de mensagem suportados

Os seguintes formatos abrangem notificações de texto, links e respostas de clientes por meio da YCloud. Um botão de URL abre um site. Um botão de resposta envia a resposta selecionada de volta para a sua empresa, permitindo que a sua aplicação continue o fluxo de trabalho.

​
Tratar respostas de botões de resposta

Embora você envie uma requisição interactive, o Direct Send entrega o conteúdo como um modelo. O toque do cliente em um botão de resposta, portanto, utiliza o formato de resposta rápida de modelo: type: button, com button.payload e button.text. Campos relevantes em um evento de mensagem de entrada da 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 essa resposta a partir de interactive.button_reply, que é o formato comum de botão de resposta em texto livre.

​
Enviar por meio da YCloud

Prepare uma chave de API do lado do servidor e os números de remetente e destinatário no formato E.164. Você só precisará do ID da WABA se optar por enviar amostras de mensagens.

​
1. Escolha o modo de envio

O nome do endpoint sendDirectly descreve o momento do envio. Para usar o Direct Send, sua WABA deve ter acesso e sua requisição deve incluir os campos do Direct Send abaixo.

​
2. Crie a requisição

Estes exemplos enviam conteúdo completo sincronicamente. Você também pode usar um envio enfileirado. Substitua os espaços reservados de números de telefone e o URL de exemplo antes de enviar.

​
3. Acompanhe a entrega

Salve o id retornado da mensagem, o seu externalId e o wamid quando disponível. Receba atualizações por meio de whatsapp.message.updated ou consulte GET /v2/whatsapp/messages/{id}. Após accepted, o resultado do envio é sent ou failed. Mensagens bem-sucedidas podem avançar para delivered e read. Uma requisição aceita não é um comprovante de entrega. Para erros de envio síncrono, inspecione error.whatsappApiError quando presente. Para mensagens enfileiradas, inspecione as atualizações de status subsequentes. Se uma requisição expirar (timeout), faça a conciliação da mensagem original antes de tentar novamente.

​
Definir um nome para um modelo de Utilidade do Direct Send

Defina templateName quando quiser que a Meta reutilize um nome reconhecível para um modelo de Utilidade do Direct Send. O campo é opcional e não ativa o Direct Send por si só. Você também deve definir useDirectSend: true ou category: "utility".
O nome diferencia maiúsculas de minúsculas. Use de 1 a 512 letras minúsculas, dígitos ou sublinhados. A 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. A YCloud verifica isso antes de uma chamada síncrona ao provedor ou antes de aceitar uma mensagem enfileirada. Modelos excluídos não reservam o nome, e você pode reutilizar um nome gerado anteriormente pela Meta para o Direct Send. Se um modelo regular já estiver usando o nome, a API retornará HTTP 400 com target templateName e mensagem A template with the same name already exists. Escolha outro nome antes de tentar novamente. templateName não é compatível com o Direct Send de Autenticação. Para uma mensagem enfileirada de Utilidade do Direct Send, a YCloud retorna o erro de validação sem retornar um ID de mensagem e, caso contrário, encaminha o nome para a Meta sem armazená-lo no registro da mensagem. A YCloud ignora o campo para mensagens que não usam o Direct Send.

​
Visualizar modelos gerados pelo Direct Send na YCloud

  1. Abra WhatsApp Manager → Modelos no console da YCloud.
  2. Selecione a WABA usada para enviar a mensagem.
  3. Defina Criador → Gerado automaticamente. Use Categoria → Utilidade para restringir a lista a modelos de Utilidade.
  4. Verifique o nome, a categoria, o idioma, o status e o horário da última atualização do modelo. Clique em seu nome ou em Insights para abrir sua pré-visualização e os detalhes de desempenho.
Filtro de criador definido como Gerado automaticamente em Modelos

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

Os nomes de modelos gerados por conteúdo geralmente começam com auto_generated. Use o filtro Gerado automaticamente para identificá-los em vez de confiar apenas em seus nomes. A página de insights mostra a pré-visualização 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. Os modelos gerados não podem ser editados ou excluídos manualmente. Para alterar a notificação, altere o conteúdo na sua solicitação de envio; a Meta então faz a correspondência ou gera um modelo para esse conteúdo.

​
Diretrizes de integridade e conteúdo

​
Mantenha o conteúdo de Utility específico e não promocional

As mensagens de Utility devem decorrer de uma ação esperada do cliente ou fornecer informações essenciais de qualificação. Declare claramente o pedido, o agendamento, a conta ou a transação relevante. Mudar category para utility não altera o significado do conteúdo. A Meta continua avaliando os modelos gerados após o envio. Você pode verificar um caso de uso materialmente diferente com uma amostra de mensagem antes de enviar.

​
Verifique um novo caso de uso com amostras de mensagens (opcional)

POST /v2/whatsapp/messages/{wabaId}/messageSamples envia um exemplo para a Meta e retorna a categoria que a Meta detecta. Não envia uma mensagem para um cliente. Esta verificação é opcional; você não precisa chamá-la para cada mensagem ou antes de usar o Direct Send. Para um novo caso de uso de Utility, recomendamos verificar três ou quatro amostras representativas, uma por solicitação. Substitua WABA_ID pelo ID da sua conta do WhatsApp Business e defina YCLOUD_API_KEY em seu ambiente. Use dados fictícios de clientes na amostra:
Exemplo de resposta:
Verifique category antes de usar o conteúdo em uma solicitação de Utility Direct Send. 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 envio acima; omita os campos de destinatário e de envio.

​
Distinga um modelo pausado de uma restrição de conta

Um modelo pode ser pausado devido à baixa qualidade. As mensagens que correspondem a ele, ou são muito semelhantes, podem falhar com o erro da Meta 132015. Encontre o modelo afetado na YCloud, inspecione seu conteúdo e status e resolva a causa antes de retomar essa notificação. O uso indevido repetido de categorias pode restringir o Direct Send para toda a WABA: Acompanhe o aviso da conta para verificar a restrição ativa e a expiração. Uma análise bem-sucedida de um modelo não suspende automaticamente uma restrição no nível da conta.

​
Receba notificações da YCloud

Inscreva-se em whatsapp.template.correct_category_detection por meio do seu webhook endpoint se desejar receber notificações de detecção de categoria. Não é uma resposta a messageSamples e não é disparado para todas as mensagens. No whatsappTemplate do evento, compare previousCategory com category. Por exemplo, previousCategory: "UTILITY" e category: "MARKETING" significam que a Meta identificou conteúdo de marketing em um modelo de Utility Direct Send. Revise o conteúdo antes de enviar mensagens semelhantes novamente. Use whatsapp.message.updated para rastrear a entrega separadamente. Campos relevantes de um evento de restrição de conta da YCloud:
Use o ID da WABA para pausar o fluxo de trabalho afetado. Leia violationType para saber o motivo e restrictions[].expiration para a sua expiração, quando fornecido. 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.

​
Solicitar uma revisão de uma decisão de categoria

Se você acredita que o conteúdo foi sinalizado incorretamente, abra Meta Business Support Home → Conta do WhatsApp → Atualizações de modelos do Direct Send → Disponível para análise. Selecione os modelos afetados e escolha Solicitar análise. Envie a solicitação em até 60 dias após a notificação. Cada modelo sinalizado pode ser analisado uma vez. Acompanhe o resultado como Em análise, Revertido ou Inalterado. Se a opção de análise não estiver disponível, entre em contato com a YCloud informando o ID da WABA, o nome ou ID do modelo, o idioma e os detalhes da notificação.

​
Extensão YCloud: reutilizar modelos de Utilidade existentes

A YCloud adiciona a conversão de modelos sobre o Direct Send da Meta. Use esta extensão quando sua integração já enviar nomes de modelos e parâmetros. A YCloud preenche as variáveis e converte os componentes compatíveis em conteúdo de mensagem completo, enviando em seguida esse conteúdo para o Meta Direct Send para correspondência ou geração. Essa conversão é fornecida pela YCloud; não é uma etapa no processo de correspondência e geração do Direct Send da Meta. template.name seleciona o modelo existente a ser convertido. O campo opcional templateName descrito acima define o nome de um modelo do Direct Send e não seleciona o modelo usado para conversão.

​
Converter um modelo de Utilidade existente

Use um modelo de Utilidade existente em sua WABA. Defina type: "template" e useDirectSend: true. Forneça o nome do modelo, o idioma e todos os parâmetros obrigatórios. A YCloud substitui as variáveis e converte componentes compatíveis em texto ou conteúdo interativo com category: "utility". O modelo deve atender aos limites de conversão abaixo. A YCloud não exige o status APPROVED para esta conversão. Se o modelo tiver um cabeçalho de imagem, confirme se a Meta habilitou o Direct Send com cabeçalho de imagem para sua WABA antes de usá-lo. Isso requer acesso separado da Meta. 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:
A resposta contém o conteúdo convertido. Para este exemplo, type se torna text, e a variável do modelo se torna o ID do pedido fornecido:
Uma resposta accepted não confirma a entrega. Armazene o id da mensagem e rastreie os eventos whatsapp.message.updated. Revise os limites de conversão abaixo antes de reutilizar um modelo com cabeçalhos ou botões. Se a 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 sua elegibilidade antes de tentar novamente ou envie um modelo de Utilidade aprovado por meio do fluxo de trabalho de modelo comum.

​
Definir o tempo de vida da mensagem de conversão

Para a conversão de modelos, o valor de ttlSeconds da requisição tem precedência sobre o TTL do modelo. Se você o omitir, a YCloud herdará um TTL positivo do modelo de até 43200 segundos. Um TTL do modelo abaixo de 30 segundos falha na validação, portanto, substitua-o por um valor válido na requisição. A YCloud não herda valores de TTL do modelo acima de 43200. Se nenhum dos valores se aplicar, a Meta usará seu TTL padrão.

​
Limites de conversão de modelos

Os seguintes limites se aplicam à conversão feita pela YCloud de um modelo de Utilidade existente em conteúdo do Direct Send: Não combine botões de URL de CTA e de resposta rápida. Outros tipos de cabeçalho e botão não podem ser convertidos. Componentes não compatíveis ou variáveis de modelo não resolvidas retornam HTTP 400 com o código WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT.

​
Perguntas frequentes sobre o Direct Send

Não para conteúdo personalizado. Forneça a mensagem completa e deixe a Meta fazer a correspondência ou gerar um modelo. Para converter um modelo de Utilidade existente, forneça seu template.name e defina useDirectSend: true. O campo opcional templateName nomeia um modelo do Direct Send de Utilidade; ele não seleciona um modelo existente.
Os modelos dão suporte a verificações de categoria e qualidade, relatórios de desempenho e solução de problemas. O Direct Send elimina a necessidade de criá-los manualmente, não o processamento baseado em modelos por trás da mensagem.
Sim, para notificações qualificadas do Direct Send de Utilidade. Sua WABA deve ter acesso, o cliente deve estar esperando a mensagem e o conteúdo deve atender aos requisitos de Utilidade. Mensagens de serviço comuns e de formato livre ainda exigem uma janela de atendimento aberta.
A geração e a sincronização do modelo são assíncronas e podem ser concluídas após o envio da mensagem. Depois de concluído, selecione a WABA correta e use o filtro Gerado automaticamente .
A Meta exclui os modelos gerados que nunca foram usados para envio após 24 horas. Modelos usados anteriormente podem ser arquivados após um período de inatividade. Você não precisa excluí-los manualmente.
Não. A Meta avalia o conteúdo real. Remova termos promocionais de notificações de Utilidade e use o processo de análise se uma mensagem genuína de Utilidade for sinalizada incorretamente.
As mensagens de Utilidade seguem as mesmas regras de preços de mensagens de Utilidade que os modelos de Utilidade criados manualmente. Consulte WhatsApp pricing.