Integração com WhatsApp

Conecte seu agent ao WhatsApp Business para a comunicação com clientes.

Visão Geral

A integração com WhatsApp oferece:

• Capacidades de mensageria empresarial
• Suporte a mídia rica
• Respostas automatizadas
• Alcance global
• Conformidade com a janela de mensageria de 24 horas

Pré-requisitos

• Um AI agent ativo (criado na seção Agents)
• Uma WhatsApp Business Account (WABA)
• Um número de telefone verificado no WhatsApp Business
• Acesso ao Meta Developer Portal

Passos de Configuração

1. Conectar com Embedded Signup (Recomendado)

A forma mais fácil de conectar o WhatsApp é pelo fluxo embedded de signup da Meta:

1. Vá para Agents → Selecione seu agent
2. Navegue até a aba Integrations
3. Clique em WhatsApp
4. Clique em Connect with Facebook para abrir o popup de signup da Meta
5. Faça login com a sua conta Facebook/Meta
6. Selecione ou crie uma WhatsApp Business Account
7. Escolha o número de telefone para conectar
8. O popup fecha e sua conexão é estabelecida

2. Verificação de Telefone (Se Necessário)

Depois de concluir o signup da Meta, talvez você precise verificar seu número de telefone:

1. Escolha como receber seu código de verificação: SMS ou Voice Call
2. Clique em Send Code
3. Insira o código de 6 dígitos que você recebeu
4. Clique em Verify

Se você não recebeu o código, clique em “Didn’t receive the code? Send again” para tentar de novo.

3. Verificação em Duas Etapas (Se Habilitada)

Se sua conta do WhatsApp Business tem a Verificação em Duas Etapas habilitada:

1. Insira seu PIN de 6 dígitos quando for solicitado
2. Clique em Complete Registration

4. Configurar o Webhook (Se Necessário)

Após a configuração, talvez você precise configurar seu webhook no Meta Business Suite:

1. Copie a webhook URL fornecida após a conexão
2. No Meta Developer Portal, vá para WhatsApp → Configuration
3. Adicione a webhook URL
4. Inscreva-se no campo de webhook messages

Usando o Bot

Mensagens de Clientes

Quando os clientes enviam mensagens para o seu número do WhatsApp:

1. A mensagem chega via WhatsApp
2. O Cuneiform Chat processa a requisição
3. O agent gera uma resposta a partir do conteúdo
4. A resposta é enviada de volta ao cliente

Fluxo da Conversa

Cliente → WhatsApp → Cuneiform Chat → Agent → Resposta → Cliente

Recursos

Janela de Mensageria de 24 Horas

Regras da WhatsApp Business API:

• Você pode responder às mensagens iniciadas pelo cliente por 24 horas
• Após 24 horas, a janela se fecha até que o cliente envie uma nova mensagem
• Cada nova mensagem do cliente reabre a janela

Mídia Rica

As respostas podem incluir:

• Mensagens de texto
• Links
• Texto formatado

Multi-Idioma

Seu agent detecta automaticamente o idioma do cliente e responde no mesmo idioma — 176 idiomas suportados, sem necessidade de configuração.

Gerenciando Números Conectados

Cada número do WhatsApp conectado exibe:

• Business name ou número de telefone exibido
• Status badge - Active, Inactive ou Error
• Phone number
• Carimbo de Last activity

Ações Disponíveis

Acesse essas opções pelo menu de três pontos no card da integração.

Solução de Problemas

Falha na Conexão

1. Garanta que você tem uma WhatsApp Business Account válida
2. Confira se seu número de telefone está verificado
3. Tente o fluxo de embedded signup de novo

A Verificação de Telefone Não Funciona

1. Garanta que você tem acesso ao número de telefone para SMS/Voz
2. Aguarde alguns minutos antes de pedir um novo código
3. Confira se o número de telefone já não está conectado em outro lugar

Erro de Verificação em Duas Etapas

1. Insira o PIN configurado no WhatsApp Business Manager → Security Center
2. Ele é diferente do código de verificação por SMS
3. Entre em contato com o admin do seu WhatsApp Business se você não souber o PIN

As Mensagens Não Chegam

1. Verifique se o webhook está configurado corretamente no Meta Business Suite
2. Confira se a inscrição do webhook inclui messages
3. Confirme se o status da integração é “Active”

Falhas nas Respostas

1. Cheque se seu agent funciona no Playground
2. Confirme se a janela de 24 horas está ativa (o cliente enviou mensagem recentemente)
3. Verifique o status da integração no painel admin

Segurança

• Os access tokens são criptografados e armazenados de forma segura
• As mensagens são processadas por conexões seguras

Conformidade

O WhatsApp Business tem políticas de uso:

• Responda apenas às conversas iniciadas pelo cliente
• Forneça opções de opt-out
• Siga as políticas Commerce e Business da Meta

Desconectando

Para remover a integração com WhatsApp:

1. Vá para Agents → Selecione o agent → Integrations
2. Clique no menu de três pontos da sua integração com WhatsApp
3. Selecione Disconnect

Isso impede o agent de responder. Para remover totalmente:

• Apague o webhook no Meta Developer Portal
• Opcionalmente, remova o produto WhatsApp do seu app na Meta

Perguntas Comuns

P: Como conecto o WhatsApp? R: Use o embedded signup clicando em “WhatsApp” na aba Integrations e depois em “Connect with Facebook”. Isso te conduz automaticamente pelo processo de signup da Meta.

P: Por que está me pedindo um código de verificação? R: O WhatsApp exige verificação de telefone para novas conexões. Escolha SMS ou Voice Call para receber um código de 6 dígitos e depois insira-o para concluir a configuração.

P: O que é o PIN da Verificação em Duas Etapas? R: Se você habilitou a Verificação em Duas Etapas no WhatsApp Business Manager, vai precisar inserir esse PIN de 6 dígitos durante a configuração. Ele é diferente do código de verificação por SMS.

P: Posso conectar vários números do WhatsApp? R: Sim, você pode conectar vários números do WhatsApp Business. Cada número pode ser conectado a um AI agent diferente (ou ao mesmo).