Cosmobots

Português

English

Português

English

Appearance

Conectar o WhatsApp ​

A Cosmika se conecta ao WhatsApp pela API oficial da Meta (WhatsApp Cloud API). A conexão usa o seu próprio app e a sua própria conta WhatsApp Business na Meta: você cria as credenciais lá, cadastra um canal na Cosmika e aponta o webhook do app para a Cosmika.

Para quem é esta página

O passo a passo pede acesso de administrador ao Meta Business (Gerenciador de Negócios) e ao app no Meta for Developers. Na Cosmika, criar canais é permitido para administradores e supervisores.

Como a conexão funciona ​

  • Mensagens recebidas chegam pelo webhook. A Cosmika confere a assinatura de cada evento com a chave secreta do app.
  • Mensagens enviadas saem com o token de acesso que você cadastrar.

Antes de começar ​

Você vai precisar de:

  • Uma conta no Meta Business (Gerenciador de Negócios) com uma conta do WhatsApp Business (WABA).
  • Um app no Meta for Developers com o produto WhatsApp adicionado.
  • Um número de telefone adicionado à WABA.

O que fica com você e o que fica com a Cosmika

A Cosmika não registra o número na Cloud API e não inscreve a WABA no seu app. Esses dois passos são feitos por você, na Meta (veja o passo 2). A Cosmika recebe as credenciais e passa a receber e enviar mensagens.

Passo a passo ​

  1. Reúna os dados na Meta

    Anote estes cinco valores. A primeira coluna traz o nome do campo na Cosmika; os nomes dos menus da Meta podem aparecer em português ou em inglês, dependendo do idioma da sua conta.

    Campo na CosmikaOnde encontrar na Meta
    ID do número de telefoneNo app, em WhatsApp > Configuração da API (API Setup), o Phone number ID. É o identificador do número, não o número em si.
    ID da conta do WhatsApp BusinessNa mesma tela, o WhatsApp Business Account ID (WABA ID).
    Token de acessoUm token permanente de usuário do sistema (veja abaixo).
    Chave secreta do appNo app, em Configurações do app > Básico (App settings > Basic), campo Chave secreta do app (App secret).
    Token de verificação do webhookVocê inventa. Qualquer texto aleatório serve (por exemplo, uma sequência longa de letras e números). Guarde-o: você vai usar o mesmo valor na Cosmika e na Meta.

    Como gerar o token de acesso recomendado

    1. No Meta Business, abra Configurações do negócio > Usuários > Usuários do sistema e crie um usuário do sistema (ou use um existente).
    2. Em Atribuir ativos, dê a esse usuário acesso ao app e à conta do WhatsApp Business (WABA).
    3. Clique em Gerar novo token, escolha o app e marque as permissões whatsapp_business_messaging e whatsapp_business_management. Se houver opção de validade, escolha a que não expira.
    4. Copie o token na hora: a Meta só mostra uma vez.

    Não use o token temporário

    O token exibido na tela Configuração da API é temporário e expira em poucas horas. Quando ele expira, os envios param de funcionar. Use o token permanente do usuário do sistema.

  2. Registre o número e inscreva a WABA no app

    Se o número ainda não está registrado na Cloud API, registre-o. O pin é o PIN de 6 dígitos da verificação em duas etapas do número (se ainda não existir, ele passa a ser esse):

    bash
    curl -X POST "https://graph.facebook.com/v20.0/<PHONE_NUMBER_ID>/register" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"messaging_product": "whatsapp", "pin": "<PIN_DE_6_DIGITOS>"}'

    Depois, inscreva a WABA no seu app. Sem isso, a Meta não entrega os eventos do número ao webhook do app:

    bash
    curl -X POST "https://graph.facebook.com/v20.0/<WABA_ID>/subscribed_apps" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

    As duas chamadas respondem {"success": true} quando dão certo.

  3. Crie o canal na Cosmika

    1. Entre em app.cosmobots.io e abra Canais no menu lateral.
    2. Clique em Novo canal.
    3. Em Nome do canal, dê um nome que sua equipe reconheça (por exemplo, "WhatsApp Atendimento").
    4. Em Tipo de canal, escolha WhatsApp.
    5. Preencha os campos:
      • ID do número de telefone
      • ID da conta do WhatsApp Business
      • Token de acesso
      • Chave secreta do app
      • Token de verificação do webhook
    6. Clique em Novo canal no fim do formulário. A Cosmika abre a página Editar canal do canal recém-criado.

    A chave secreta do app é obrigatória

    Sem a Chave secreta do app, a Cosmika rejeita todas as mensagens recebidas, porque não consegue validar a assinatura dos eventos da Meta. O canal parece criado, mas nada chega. Use a chave secreta do mesmo app em que você vai configurar o webhook.

    Por segurança, o token de acesso, a chave secreta do app e o token de verificação nunca são exibidos de novo depois de salvos. Se precisar corrigir algum deles, veja Alterar as credenciais.

  4. Configure o webhook no app da Meta

    1. Na Cosmika, abra o canal que você acabou de criar (Canais > clique no canal). Na seção Conexão com o Meta, clique em Copiar ao lado da URL de callback. Ela segue este formato:

      https://app.cosmobots.io/api/webhooks/whatsapp/<ID-do-canal>

    2. No app da Meta, abra WhatsApp > Configuração (Configuration) e, em Webhook, clique em Editar.

    3. Cole a URL em URL de callback (Callback URL).

    4. Em Verificar token (Verify token), cole o mesmo token de verificação do webhook configurado no canal.

    5. Clique em Verificar e salvar (Verify and save). A Meta chama a Cosmika na hora; se o token ou a URL não baterem, a Meta mostra erro e não salva.

    6. Em Campos do webhook (Webhook fields), assine o campo messages.

    Não esqueça a inscrição da WABA

    Configurar o webhook no app não basta: a WABA também precisa estar inscrita no app (a chamada subscribed_apps do passo 2). A Cosmika não faz essa inscrição por você.

  5. Teste

    1. De um celular, mande uma mensagem para o número conectado.
    2. Abra Conversas na Cosmika: a conversa aparece na lista em alguns segundos.
    3. Responda pela Cosmika e confira se a resposta chega ao celular.

    Se nada aparecer, vá para Solução de problemas.

Alterar as credenciais ​

Na página do canal, a seção Credenciais do WhatsApp mostra os dados da conexão. Só administradores podem alterá-los; para as outras pessoas, a seção aparece apenas para consulta.

  1. Abra Canais e clique no canal WhatsApp.
  2. Na seção Credenciais do WhatsApp:
    • ID do número de telefone e ID da conta do WhatsApp Business aparecem preenchidos e podem ser editados direto no campo.
    • Token de acesso, Chave secreta do app e Token de verificação do webhook nunca são exibidos. Cada um aparece como configurado (ou Não configurado). Para trocar, clique em Substituir e cole o novo valor. Deixar o campo em branco mantém o valor atual, e Manter o atual desiste da troca.
  3. Clique em Salvar credenciais. A tela confirma com "Credenciais salvas."

Se trocar o ID da conta do WhatsApp Business, sincronize os modelos de novo. Se trocar o Token de verificação do webhook, cole o mesmo valor novo no cadastro do webhook no app da Meta.

Modelos (templates) do WhatsApp ​

Os modelos aprovados na Meta são usados para escrever para o cliente fora da janela de 24 horas e em Transmissões.

  1. Abra Canais e clique no canal WhatsApp.
  2. Na seção Modelos do WhatsApp, clique em Sincronizar com a Meta.
  3. A lista mostra cada modelo com idioma e status.

Os modelos são criados e aprovados na Meta (no Gerenciador do WhatsApp). A Cosmika só busca os que já existem.

A janela de 24 horas ​

A Meta só permite mensagem livre (texto, arquivo) até 24 horas depois da última mensagem do cliente. Depois disso, só é possível enviar um modelo aprovado.

Quando a janela fecha, a Cosmika mostra um aviso acima do campo de resposta dizendo que a janela de 24 horas fechou e que o WhatsApp vai rejeitar mensagem livre.

Nesse caso, use o ícone Enviar modelo no campo de resposta (ele aparece quando o canal tem modelos sincronizados). Quando o cliente responder, a janela abre de novo por mais 24 horas.

Solução de problemas ​

Nenhuma mensagem recebida aparece na Cosmika ​

Confira, nesta ordem:

  1. Chave secreta do app: é a do mesmo app onde o webhook está configurado? Se ela estiver errada ou aparecer como Não configurado, todo evento é rejeitado. Um administrador corrige em Alterar as credenciais.
  2. Campo messages: em WhatsApp > Configuração > Campos do webhook, o campo messages está assinado?
  3. WABA inscrita no app: você fez a chamada subscribed_apps do passo 2? Sem ela, a Meta não envia os eventos do número.
  4. URL de callback: é a URL copiada da seção Conexão com o Meta deste canal? A URL de outro canal (ou de um canal excluído) não recebe nada.
  5. Número registrado: a chamada register do passo 2 foi feita para este ID do número de telefone?
  6. Um app, vários números: a URL de callback é uma só por app na Meta, e cada canal da Cosmika aceita apenas os eventos do seu próprio ID do número de telefone. Para conectar mais de um número do mesmo app, fale com o suporte.

A Meta não aceita a URL ao clicar em "Verificar e salvar" ​

  • O Verificar token digitado na Meta precisa ser idêntico ao Token de verificação do webhook do canal (diferença de maiúsculas, espaços ou caracteres extras já quebra). Como o valor salvo não é exibido, se não tiver certeza, substitua-o por um novo em Alterar as credenciais e use esse mesmo valor na Meta.
  • A URL precisa ser exatamente a URL de callback copiada da seção Conexão com o Meta do canal.

A mensagem enviada aparece como falha ​

Quando o envio falha, a mensagem fica marcada como não entregue na conversa, com o botão Tentar novamente. A tela não mostra o código de erro da Meta; se precisar dele, fale com o suporte informando o número da conversa (o # no topo). Os casos mais comuns:

Erro 131047: passaram 24 horas desde a última mensagem do cliente ​

A janela de atendimento fechou. Mensagem livre não é mais aceita: envie um modelo aprovado com Enviar modelo. Veja A janela de 24 horas.

Erro 130497: envio bloqueado para usuários de um país ​

A conta WhatsApp Business está impedida pela Meta de enviar mensagens para usuários de determinado país. É uma restrição da conta na Meta, não da Cosmika, e nenhuma plataforma consegue contornar. Costuma se resolver com:

  • verificação do negócio no Meta Business (Gerenciador de Negócios);
  • perfil da empresa completo na conta do WhatsApp Business;
  • aumento do nível de limite de envio da conta (que a Meta libera conforme o histórico de uso e a qualidade das mensagens).

Depois que a Meta libera a conta, os envios voltam a funcionar sem nenhuma mudança na Cosmika.

Todos os envios falham, em todas as conversas ​

  • O token de acesso pode ter expirado (token temporário) ou perdido permissões. Gere um token permanente de usuário do sistema, como no passo 1, e substitua-o no canal em Alterar as credenciais.
  • Confira também o status da plataforma da Meta em metastatus.com: quando a Meta está instável, os envios falham em todas as plataformas ao mesmo tempo.

"Outro canal WhatsApp desta conta já usa este ID de número" ​

Esse aviso aparece ao salvar as credenciais: a Cosmika não aceita dois canais com o mesmo ID do número de telefone na mesma conta. Use o canal que já existe para esse número ou confira se o ID foi copiado do número certo.

Os modelos não aparecem para enviar ​

  • Clique em Sincronizar com a Meta na página do canal.
  • Só modelos aprovados na Meta podem ser enviados. Modelos em análise ou rejeitados não servem.

Próximos passos ​

Cosmobots — plataforma de atendimento conversacional

© 2026 Cosmobots