Você não precisa abrir a caixa de entrada para enviar um modelo para uma pessoa. Digite o pedido no chat com o Octo do jeito que diria a um colega, e o Octo encontra o modelo e preenche as variáveis. Ele ainda não envia: mostra exatamente o que vai enviar, e a mensagem só sai quando você clica em Confirmar. O envio passa pelo mesmo caminho da caixa de entrada e da API, então é verificado do mesmo jeito e cai na mesma conversa.
Isto é para um destinatário por vez. Para uma lista inteira, use uma campanha. Por que o WhatsApp precisa de um modelo está em Quando uma mensagem do WhatsApp precisa ser um modelo.
Um exemplo de pedido
A Lavanderia Tidewater tem um modelo de utilidade aprovado, pickup_confirmation,
com o corpo
Olá {{1}}, sua coleta está confirmada para {{2}}. Responda aqui se quiser mudar.
A Ana perguntou na semana passada sobre a lavagem de um edredom, disse que daria
retorno e não escreveu mais. Você digita:
Envie para Ana Ruiz a confirmação de coleta para terça-feira, das 9h às 11h.
O Octo está preparado para resolver isso nesta ordem:
- Encontrar a Ana. Um nome é procurado nos seus contatos; um número de
telefone pode ser usado como está. De qualquer forma, ele precisa terminar em
formato internacional (
+14255550123) — o envio recusa qualquer outra coisa. - Verificar o último contato dela. Quando a Ana escreveu pela última vez no WhatsApp diz ao Octo se a janela de 24 horas está aberta, e se alguém já mandou mensagem para ela hoje.
- Encontrar o modelo. O Octo busca nos seus modelos pelo nome e pelo nome de exibição, olhando só os aprovados.
- Preencher as variáveis —
{{1}}=Ana,{{2}}=terça-feira, das 9h às 11h— e preparar o envio. O Octo diz que preparou para você confirmar; ele não diz “enviado”. - Esperar por você. Um cartão aparece no chat — veja abaixo. Nada chega à Ana até você clicar em Confirmar.
O Octo descreve cada passo do jeito dele. As verificações do resto deste guia são feitas pelo próprio envio, sempre.
Diga qual modelo, e cada valor
Quanto mais o seu pedido nomear, menos o Octo precisa escolher:
Envie para +14255550123 o modelo
pickup_confirmation. Nome: Ana. Horário: terça-feira, das 9h às 11h.
Se você só descrever a mensagem, o Octo escolhe o modelo aprovado que melhor se encaixa e diz qual escolheu. Se faltar uma variável no seu pedido, diga-a ou espere que ele pergunte — um modelo nunca é enviado com um espaço vazio (veja abaixo).
Modelos com botões também funcionam. O modelo de marketing da Lavanderia Tidewater com um botão de copiar código recebe o código como valor:
Envie para o Ben o modelo
duvet_promocom o código FRESH20.
Confirme antes de enviar
No chat do painel, o envio preparado aparece como um cartão com o título Enviar este modelo do WhatsApp?:
| Linha | O que mostra |
|---|---|
| Para | O número para onde vai — +14255550123 |
| Modelo | O modelo e o idioma — pickup_confirmation (pt_BR) |
| Valores | Cada valor ao lado do espaço que preenche, em ordem: cabeçalho, depois corpo, depois botões — Corpo 1 → Ana, Corpo 2 → terça-feira, das 9h às 11h |
| Expira em … | Quando o pedido perde a validade: 24 horas depois de o Octo prepará-lo |
Depois, Confirmar ou Cancelar.
- Confirmar envia. O cartão muda para Enviado, e uma nota aparece no chat: Done ✅ — Template “pickup_confirmation” sent to +14255550123 via WhatsApp. Se o WhatsApp ou uma das verificações abaixo recusar, o cartão diz Não enviado com o motivo.
- Cancelar não envia nada. O cartão diz Cancelado — nada foi enviado.
- Não fazer nada não envia nada. Depois de 24 horas o cartão diz Expirado — nada foi enviado.
Alguns detalhes que importam:
- Leia os valores, não só o número. O cartão é o último ponto em que um espaço errado ou um erro de digitação pode ser pego. Para mudar algo, cancele e peça de novo.
- Os botões esperam o Octo. Enquanto o Octo ainda está escrevendo a resposta, o cartão diz Você poderá confirmar quando o Octo terminar de responder.
- Vários modelos, vários cartões. Peça dois envios num chat e você recebe dois cartões; cada um é confirmado ou cancelado separadamente.
- Voltar depois é seguro. Recarregue a página e o cartão mostra o que de fato aconteceu. Um pedido já enviado, cancelado ou expirado nunca volta a mostrar botões ativos, e clicar em Confirmar duas vezes não envia duas vezes.
- Quem pode confirmar. Só a pessoa que pediu ao Octo, ou um proprietário ou administrador do espaço de trabalho, pode confirmar ou cancelar.
Falando com o Octo por e-mail, WhatsApp ou Slack
O Octo pergunta lá também. A mensagem mostra o que ele vai fazer e um código curto. Por e-mail você responde com o código; no WhatsApp e no Slack também há botões Confirm e Cancel. A linha que você aprova cita o modelo, o número e os valores:
Send WhatsApp template "pickup_confirmation" (en_US) to +14255550123 — body 1: "Ana", body 2: "Tuesday, 9–11am"Um valor num espaço com nome de código — otp, pin, um token — aparece como
•••• nessa linha. Um pedido sem resposta expira depois de 24 horas, e nada é
enviado.
O que o Octo recusa
Toda recusa acontece antes de o WhatsApp ser contatado, e o Octo fica sabendo o motivo.
| Situação | O que acontece |
|---|---|
| O modelo está pendente, rejeitado, pausado ou desativado | Recusado: só um modelo aprovado pode ser enviado. |
| Falta uma variável, ou ela veio vazia | Recusado, citando o espaço — por exemplo body is missing variable “customer_name”, ou que o corpo espera 2 valores e recebeu 1. |
| Um valor é longo demais | Recusado. Um código para copiar tem no máximo 15 caracteres. |
| O modelo tem cabeçalho de imagem, vídeo ou documento | O Octo não consegue fornecer o arquivo, então o envio é recusado. Envie do seu próprio sistema, que aceita o payload completo de modelo da Meta. |
| O número de WhatsApp do modelo não está mais ativo | Recusado. |
| O faturamento não está configurado para o espaço de trabalho | Recusado com Billing setup required. |
| O número está enviando rápido demais, ou atingiu o limite diário | Recusado com o tempo de espera. O Octo recebe a espera e diz quando tentar de novo; ele não foi feito para repetir por conta própria. Veja Com que rapidez um número pode enviar. |
Estas recusas deixam a tentativa visível na conversa como uma mensagem que não saiu:
- O cliente cancelou o recebimento de mensagens do WhatsApp. Registrado como bloqueado. O Octo não consegue passar por cima de um cancelamento.
- O número de WhatsApp ainda aguarda verificação.
- O espaço de trabalho está suspenso, ou o destino não está habilitado para ele. Registrado como falha.
- A Meta rejeitou a mensagem. Registrado como falha; o Octo recebe o erro da Meta e pode tentar de novo com outros valores.
Texto livre em vez de um modelo
Se a janela estiver aberta, o Octo pode enviar suas palavras como estão. Peça “Mande no WhatsApp para a Ana: seu entregador chega em dez minutos” e, se a Ana escreveu nas últimas 24 horas naquele número, o texto sai como uma mensagem normal.
Se não, o envio de texto livre é recusado com a janela fechada como motivo. O Octo não faz passar por baixo dos panos: ele precisa trocar para um modelo aprovado, e quando nenhum serve, ele diz. Ele pode ajudar você a criar um, mas um modelo novo ainda precisa ser aprovado pela Meta antes que alguém possa recebê-lo. Traga seus modelos para o Omni Octo explica isso.
Onde a mensagem aparece
- Qual número envia. Os modelos pertencem a um número de WhatsApp, então o modelo decide o remetente. Se você tiver dois números, cite o modelo sincronizado com o que você quer.
- Qual conversa. A mesma que as mensagens do cliente já usam, exatamente como num envio do seu próprio sistema. Quando a Ana responde, a resposta dela entra nessa conversa.
- Quem responde à resposta. O Octo não assume a conversa. Se um agente de IA estava atendendo, continua atendendo; se você tinha assumido, ela continua com você. Isso é diferente de enviar a partir de uma conversa, onde você assume primeiro.
- O que aparece. A mensagem na conversa mostra o corpo com os valores, registrada como enviada por você. Ela começa como enviada; entregue, lida ou falha chegam depois, vindos da Meta.
“Enviado” na resposta do Octo significa que a Meta aceitou a mensagem. Não significa que a Ana a recebeu — e um modelo de marketing pode nunca ser entregue.
Pedir duas vezes envia duas vezes
Cada pedido é um cartão novo, e cada cartão confirmado é um envio novo. Não há verificação de “já enviado” entre pedidos: se você pedir de novo, ou pedir ao Octo para “tentar de novo” depois de um envio que de fato saiu, e confirmar os dois, a Ana recebe o modelo duas vezes — e cada um conta nos limites do número. Confira o status do cartão anterior antes de confirmar um reenvio.
O que o Octo não faz
- Enviar para uma lista. Um pedido é um destinatário; use uma campanha.
- Enviar um modelo com cabeçalho de mídia. Ele não tem como fornecer o arquivo.
- Passar por cima de um cancelamento, nem enviar um modelo não aprovado.
- Fazer texto livre passar com a janela fechada.
O Octo fora do chat
Quando um programa fala com o Octo no lugar de uma pessoa, o envio continua esperando por uma pessoa:
| Onde o programa se conecta | O que acontece |
|---|---|
/mcp — passando um trabalho ao Octo com send_message | Fica em espera. O resultado traz um pending_action com um código. Nada é enviado até alguém responder YES <code> na mesma conversa. |
/mcp/tools — chamando as ferramentas do Octo diretamente | Recusado com confirmation_required. |
/v1, uma conversa armazenada | Fica em espera de uma resposta YES <code>, do mesmo jeito. |
/v1, uma requisição que não armazena nada | Não é oferecido. |
Se o seu próprio software precisa enviar um modelo sem uma pessoa aprovar cada um, chame o endpoint de envio de modelos diretamente — Enviar um modelo do seu próprio sistema.
Para onde ir depois
- Enviar um modelo a partir de uma conversa — o mesmo envio, com pré-visualização, de dentro da conversa.
- Enviar um modelo para uma lista — quando é mais de uma pessoa.
- Com que rapidez um número pode enviar — os limites que os envios do Octo compartilham com todas as outras vias.