Disparar template pelo seu sistema (API)
Falar com muitos contatos de uma vez7 min de leitura
Para que serve: avisar um cliente pelo WhatsApp oficial quando algo acontece em outro sistema (um n8n, um ERP, uma loja virtual), sem ninguém abrir a conversa no CRM, mesmo que o cliente nunca tenha falado com a empresa.
O que você precisa
- Plano: qualquer um. O token pessoal da API vale em todos os planos.
- Permissão: o gerente conecta o número, cria o template e o token. Quem programa a integração só usa o token.
- Antes:
- Um número da API oficial conectado ao inbox: em Configurações → Integrações → Canais, ele aparece no card WhatsApp Cloud API (Meta). Número de QR code fica em Números de WhatsApp e não serve: a API recusa.
- Autorização de quem vai receber: só dispare para quem aceitou receber mensagens da sua empresa no WhatsApp (formulário, compra, atendimento anterior). A Meta exige esse consentimento; sem ele, as pessoas denunciam, a qualidade do número cai e a Meta pode restringir ou bloquear o número. Guarde de onde veio cada autorização.
- Um template Aprovado, com variáveis só no corpo (Como criar um template do WhatsApp e pedir aprovação da Meta).
- A verificação em duas etapas ligada, se você é gerente: sem ela o CRM não deixa criar token (Como proteger sua conta com 2FA).
- Quem vai montar a chamada (um desenvolvedor ou quem cuida do n8n). Ele usa o guia técnico em
https://rumocrm.com/developers/disparar-template, com exemplos em curl, Node.js e n8n.
Como funciona
Cada vez que o seu sistema chama POST /conversations, o CRM faz o seguinte:
Seu sistema → CRM acha ou cria o contato e a conversa → template na fila → Meta → WhatsApp do cliente
| Situação | O que o CRM faz |
|---|---|
| Número que o CRM nunca viu | Cria o contato (em Contatos, na aba Leads frios) e a conversa. A conversa nasce sem responsável, na fila do setor do número |
| Contato que já existe, sem conversa | Reaproveita o contato e cria a conversa |
| Conversa que já existe (aberta, encerrada ou excluída) | Reaproveita a conversa, reabre se precisar e coloca o template nela |
| Contato da carteira de outro vendedor, com token de vendedor | Recusa e não cria nada |
| Contato que pediu para não receber mensagens | Recusa e não cria nada |
A primeira mensagem é sempre o template. Quando o cliente responde, a janela de 24 horas abre e o time conversa com texto livre em Conversas.
Passo a passo
-
Confirme o número oficial. Em Configurações, abra Integrações e a seção Canais. O número precisa estar no card WhatsApp Cloud API (Meta). Se você só tem QR code, siga Como conectar a API oficial do WhatsApp.
-
Confirme o template. No card WhatsApp Cloud API (Meta), em Templates da Meta, o template precisa estar Aprovado. Anote o nome e o idioma dele (por exemplo
pedido_enviadoept_BR) e quantas variáveis o corpo tem. Se ainda não existe, clique em Criar Template e espere a Meta aprovar, de 24 a 48 horas. -
Crie o token. Vá em Configurações → Operação → API e integrações. No card Criar token, dê um Nome que diga onde ele vai rodar (por exemplo "Sistema de pedidos"). Em O que este token pode fazer, marque Inbox: enviar e, para consultar o resultado depois, Inbox: ler. Em Validade, escolha o prazo e clique em Criar token.
-
Aparece Copie o token agora. Clique em Copiar, guarde o token num cofre de segredos ou numa variável de ambiente do outro sistema e clique em Já copiei, fechar. Ele não aparece de novo.
-
Passe ao desenvolvedor: o token, o nome e o idioma do template, o que vai em cada variável do corpo e o endereço do guia técnico (
https://rumocrm.com/developers/disparar-template). A chamada éPOST https://rumocrm.com/api/v1/conversations, com o número do cliente e o template. Peça para ele mandar aIdempotency-Key(o número do pedido, por exemplo): se a conexão cair e a chamada for repetida, o cliente recebe uma mensagem só. -
Para o seu sistema saber se a mensagem saiu, cadastre um webhook. Vá em Configurações → Integrações → Técnico, clique em Adicionar Webhook no card Webhooks, preencha Nome e URL e marque Mensagem enviada (inbox), Mensagem não enviada (inbox) e Mensagem recebida. Clique em Criar Webhook (Como mandar os eventos do CRM para outro sistema (webhooks)).
-
Faça o primeiro disparo para o seu próprio número. Em Conversas, a conversa aparece com a mensagem enviada, com o dono do token como autor. Como nasce sem responsável, ela fica na aba Fila até alguém assumir. Se você pede
assignToSelfna chamada, ela já vem para o dono do token.
Se algo der errado
| O que o seu sistema recebe | Por que acontece | O que fazer |
|---|---|---|
422 channel_not_official ou 422 no_official_channel | O número é de QR code, ou não há número oficial ativo liberado para o dono do token | Conecte o número oficial (passo 1) e libere o canal para o usuário em Configurações → Equipe |
422 template_not_found | O nome ou o idioma não batem, o template ainda está Pendente ou foi Rejeitado, ou foi aprovado há menos de 5 minutos | Confira o nome e o status em Templates da Meta e tente de novo em alguns minutos |
422 template_params_mismatch | A quantidade de valores enviados é diferente da quantidade de variáveis do corpo | Envie um valor para cada {{1}}, {{2}}... do template |
422 template_not_supported | O template tem imagem ou variável no cabeçalho, ou botão de link com variável | Crie um template com variáveis só no corpo |
422 recipient_opted_out | O contato pediu para não receber mensagens | Não envie. O gerente confere em Blacklist (Como respeitar quem pediu para não receber mensagens) |
409 contact_in_other_wallet ou 409 conversation_with_other_user | O token é de um vendedor e o contato ou a conversa é de um colega | Use o token de um gerente, ou peça ao gerente para transferir o contato |
409 channel_disconnected | O número foi desligado ou o acesso dele venceu | Reconecte em Configurações → Integrações → Canais |
429 rate_limited | Mais de 30 envios por minuto pelo mesmo número | Espere o tempo do cabeçalho Retry-After e repita com a mesma Idempotency-Key |
A chamada deu certo (202), mas o cliente não recebeu | A Meta aceitou e recusou depois (pagamento da conta, número sem WhatsApp, template pausado) | Veja o motivo na conversa e em Por que minha mensagem não foi entregue?. O seu sistema recebe message.failed |
| O cliente respondeu e ninguém viu | A conversa nasceu sem responsável, na fila do setor do número | Quem atende o setor vê a resposta na aba Fila. Para já nascer com o dono do token, a chamada leva assignToSelf |
O sistema não consegue consultar a mensagem (404) | O token é de um vendedor que não atende o setor do número, e a conversa nova está sem responsável | Use assignToSelf, um token de gerente ou o webhook em vez da consulta |
Quanto custa
- O Rumo CRM não cobra por mensagem.
- A Meta cobra cada template, por categoria, na conta do WhatsApp Business do número. Como o cliente ainda não escreveu, a janela de 24 horas está fechada e todas as categorias são cobradas. Os valores e a estimativa estão em Regras e limites do disparo.
O que este recurso não faz
- Não cria nem edita template: o template é criado e aprovado na tela, antes da integração.
- Não manda texto livre nem arquivo na primeira mensagem, e não agenda envio. Depois que o cliente responde, o texto livre sai dentro de 24 horas.
- Não faz disparo em massa nem para uma lista. O limite é de 30 envios por minuto por número. Para uma lista, use a campanha (Como disparar uma campanha pelo WhatsApp oficial); para poucos números, o desenvolvedor chama a rota em sequência, respeitando o limite.
- Não aciona automação interna: não cria negócio no funil, não entra em cadência e não liga regra nem chatbot por conta própria.
- Não funciona em número de QR code, Instagram nem e-mail.
- Não garante a entrega: quem decide é a Meta e o WhatsApp do cliente.
Próximos passos
- Como funciona o disparo de mensagens de WhatsApp no Rumo CRM
- Regras e limites do disparo: Meta, janela de 24 horas, descadastro e boas práticas
- Por que minha mensagem não foi entregue?
- Como mandar os eventos do CRM para outro sistema (webhooks)
- Passo a passo: ativar o WhatsApp oficial e fazer seu primeiro disparo