Como funciona o Direct Send
O Direct Send usa modelos nos bastidores. Você pode enviar texto finalizado ou conteúdo interativo. Você também pode referenciar um modelo de mensagem de Utilidade existente e solicitar que a YCloud converta seus componentes suportados em uma mensagem Direct Send.
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 mantêm informações de categoria, qualidade e desempenho. Isso permite identificar qual conteúdo está apresentando bom desempenho ou causando problemas de entrega, mesmo que você não tenha criado o modelo diretamente.
Recursos suportados e limites
Elegibilidade e escopo de envio
Conecte sua WABA e número de telefone comercial à YCloud. Em Gerenciador do WhatsApp da Meta → Modelos de mensagem, verifique se sua empresa é elegível para o Direct Send. Se o acesso não estiver disponível para a sua WABA, use um modelo de mensagem de Utilidade aprovado ou entre em contato com a YCloud para verificar a elegibilidade. 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 à solicitação, transação, conta ou informações essenciais qualificadas dele. 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évias de URL. Limites de conta e controles de taxa de transferência ainda se aplicam.
Use cabeçalhos de texto para solicitações de Direct Send
interactive personalizadas. Um cabeçalho de imagem
está disponível apenas quando você converte um modelo suportado e a Meta habilitou
esse recurso para a sua WABA.
Tempo de vida da entrega (TTL)
ttlSeconds define por quanto tempo uma mensagem pode permanecer elegível para entrega. Se ela não puder ser entregue dentro desse período, será descartada. Uma mensagem entregue não é excluída quando seu TTL expira.
O intervalo 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 a deixe no padrão.
Tipos de mensagens compatíveis
Os formatos a seguir 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 aplicação continue o fluxo de trabalho.
Tratar respostas de botões de resposta
Embora você envie uma requisiçãointeractive, o Direct Send entrega o conteúdo como um modelo. O toque de um cliente no 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 recebida da YCloud:
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 em interactive.button_reply, que é o formato padrão de botão de resposta em formato livre.
Enviar por meio da YCloud
Prepare uma chave de API do lado do servidor e os números do remetente e do 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 a temporização 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. Construa a requisição
Estes exemplos enviam o conteúdo completo de forma síncrona. Você também pode usar um envio enfileirado ou converter um modelo existente de Utilidade. Substitua os marcadores de número de telefone e o URL de exemplo antes de enviar.
- Texto
- Botão de URL
- Botões de resposta
3. Rastreie a entrega
Salve oid da mensagem retornado, 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 é uma confirmação 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.
Converter um modelo existente de Utilidade
Use um modelo de Utilidade existente em sua WABA. Definatype: "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 os 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 a 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:
type torna-se text, e a variável do modelo passa a ser o ID do pedido fornecido:
accepted não confirma a entrega. Armazene o id da mensagem e rastreie os eventos de 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 pelo fluxo de trabalho comum de modelos.
Definir o tempo de vida da mensagem
Para a conversão de modelos, o valor dettlSeconds na requisição tem precedência sobre o TTL do modelo. Se você omiti-lo, a YCloud herdará um TTL positivo do modelo de até 43200 segundos. Um TTL de modelo inferior a 30 segundos falhará na validação, portanto, substitua-o por um valor de requisição válido. A YCloud não herda valores de TTL de modelo acima de 43200. Se nenhum dos valores for aplicável, a Meta usará o TTL padrão dela.
Nomear um modelo de utilidade do Direct Send
template.name identifica um modelo existente na requisição de conversão acima. templateName tem uma finalidade diferente: defina-o quando quiser que a Meta reutilize um nome reconhecível para um modelo de utilidade do Direct Send. O campo é opcional e não habilita o Direct Send por si só. Você também deve definir useDirectSend: true ou category: "utility".
400 com target templateName e mensagem A template with the same name already exists. Escolha outro nome antes de tentar novamente.
templateName não é suportado para Authentication Direct Send. Para uma mensagem de utilidade do Direct Send enfileirada, 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.
Limites de conversão de modelo e de idioma
O Direct Send de utilidade suporta texto, botões de URL de CTA e botões de resposta. Estes limites também se aplicam quando a YCloud converte um modelo de utilidade:
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 incompatíveis ou variáveis de modelo não resolvidas retornam HTTP
400 com o código WHATSAPP_DIRECT_SEND_UNSUPPORTED_COMPONENT.
Suporte a idiomas
O Direct Send suporta os idiomas de modelo do WhatsApp, exceto:
Use um idioma suportado para fluxos de trabalho do Direct Send.
Visualizar modelos gerados pelo Direct Send na YCloud
- Abra WhatsApp Manager → Templates no console da YCloud.
- Selecione a WABA usada para enviar a mensagem.
- Defina Creator → Auto generated. Use Category → Utility para restringir a lista aos modelos de utilidade.
- 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 detalhes de desempenho.
Set Creator to Auto generated. This test WABA has no matching generated templates.
auto_generated. Use o filtro Auto generated para identificá-los em vez de depender apenas de seus nomes.
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 a notificação, mude o conteúdo em sua solicitação de envio; a Meta então fará a correspondência ou gerará um modelo para esse conteúdo.
Diretrizes de integridade e conteúdo
Mantenha o conteúdo de Utilidade específico e não promocional
Mensagens de utilidade devem acompanhar uma ação esperada do cliente ou fornecer informações essenciais qualificadas. Indique o pedido, agendamento, conta ou transação relevante com clareza.
Alterar
category para utility não muda 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.
Verificar um novo caso de uso com amostras de mensagem (opcional)
POST /v2/whatsapp/messages/{wabaId}/messageSamples envia um exemplo para a Meta e retorna a categoria que a Meta detecta. Isso não envia uma mensagem para o 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 Utilidade, 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 no seu ambiente. Use detalhes fictícios de clientes na amostra:
category antes de usar o conteúdo em uma solicitação de Direct Send de Utilidade. Se a Meta detectar MARKETING ou AUTHENTICATION, revise o conteúdo ou use o fluxo de mensagens apropriado. Para uma amostra com botão, envie os campos type e interactive a partir de um exemplo de envio acima; omita os campos de destinatário e de envio.
Diferenciar um modelo pausado de uma restrição de conta
Um modelo pode ser pausado devido à baixa qualidade. Mensagens que correspondem a ele, ou que são muito semelhantes, podem falhar com o erro da Meta132015. 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 ver a restrição ativa e a expiração. Uma análise bem-sucedida de um modelo não cancela automaticamente uma restrição no nível da conta.
Receber notificações da YCloud
Inscreva-se em
whatsapp.template.correct_category_detection por meio do seu endpoint de webhook se desejar notificações de detecção de categoria. Não é uma resposta para messageSamples e não é disparado para todas as mensagens. No whatsappTemplate do evento, compare previousCategory com category. Por exemplo, previousCategory: "UTILITY" e category: "MARKETING" indicam que a Meta identificou conteúdo de marketing em um modelo Direct Send de Utilidade. 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:
violationType para o motivo e restrictions[].expiration para a expiração, quando fornecido.
Solicitar uma análise de uma decisão de categoria
Se você acredita que o conteúdo foi sinalizado incorretamente, abra Início do Suporte para Empresas da Meta → Conta do WhatsApp → Atualizações de modelos do Direct Send → Disponíveis para análise. Selecione os modelos afetados e escolha Solicitar análise. Envie a solicitação em até 60 dias a partir da 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 WABA ID, o nome ou ID do modelo, o idioma e os detalhes da notificação.Perguntas frequentes sobre o Direct Send
Preciso do nome de um modelo antes de enviar?
Preciso do nome de um modelo antes de enviar?
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 dá nome a um modelo de Direct Send de Utilidade; ele não seleciona um modelo existente.Por que o Direct Send ainda gera modelos?
Por que o Direct Send ainda gera modelos?
Os modelos oferecem 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, mas não o processamento baseado em modelos por trás da mensagem.
Posso enviar mensagens fora da janela de atendimento ao cliente de 24 horas?
Posso enviar mensagens fora da janela de atendimento ao cliente de 24 horas?
Sim, para notificações qualificadas do Direct Send de Utilidade. Sua WABA precisa ter acesso, o cliente deve estar esperando a mensagem e o conteúdo deve atender aos requisitos de Utilidade. Mensagens de serviço comuns em formato livre ainda exigem uma janela de atendimento aberta.
Por que uma mensagem pode ter êxito antes que o modelo gerado apareça?
Por que uma mensagem pode ter êxito antes que o modelo gerado apareça?
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 .
Como os modelos gerados e não utilizados são limpos?
Como os modelos gerados e não utilizados são limpos?
A Meta exclui após 24 horas os modelos gerados que nunca foram utilizados para envio. Os modelos usados anteriormente podem ser arquivados após um período de inatividade. Você não precisa excluí-los manualmente.
Definir a categoria como utilidade garante que a Meta aceitará a categoria?
Definir a categoria como utilidade garante que a Meta aceitará a categoria?
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.
Como o Direct Send é cobrado?
Como o Direct Send é cobrado?
As mensagens de utilidade seguem as mesmas regras de preços de mensagens de utilidade dos modelos de utilidade criados manualmente. Consulte Preços do WhatsApp.