Integração com WhatsApp Business

Esta página descreve como ligar um Agente SipPulse AI a um número da Plataforma WhatsApp Business (WABA), habilitar recursos adicionais e acompanhar o tráfego de mensagens.

1. Pré-requisitos

Para conectar seu Agente ao WhatsApp, é fundamental que sua empresa já possua uma estrutura configurada na plataforma da Meta. A hierarquia é a seguinte:

Meta Business Account → WhatsApp Business Account (WABA) → Número de Telefone

Certifique-se de que todos os itens abaixo estão concluídos antes de prosseguir.

Requisito	Detalhes e Ações
1. Conta Meta Business Verificada	A sua empresa precisa de uma conta no Meta Business Suite. É crucial que ela passe pelo processo de verificação da empresa. Sem isso, a Meta impõe limites severos que impedem a operação. Ação: Verifique sua empresa no Centro de Segurança do Business Suite. O status deve ser Verificada.
2. Conta do WhatsApp Business (WABA)	Dentro da sua conta Business, você deve ter uma Conta do WhatsApp (WABA). Se você já usa o WhatsApp com outra plataforma, provavelmente já tem uma. Caso contrário, o processo de conexão com o SipPulse AI pode ajudar a criá-la. Ação: Verifique a existência de uma WABA em Configurações do Negócio → Contas → Contas do WhatsApp.
3. Número de Telefone Válido e Registrado	O número de telefone deve ser capaz de receber chamadas de voz ou SMS para verificação. Não pode estar em uso por outra conta do WhatsApp (pessoal ou Business App). Ação: Adicione o número à sua WABA e complete a verificação. Durante a conexão com o SipPulse AI, se o número ainda não estiver registrado com a API do WhatsApp, será solicitado o registro, que pode exigir um PIN de autenticação de dois fatores (2FA).
4. Permissões de Administrador	Você precisa ter acesso de administrador à conta Meta Business para autorizar a integração. Isso é necessário para conceder ao SipPulse AI as permissões de BSP (Business Solution Provider). Ação: Confirme seu nível de acesso em Configurações do Negócio → Pessoas.

2. Conectar o número

Abra ⋮ → Publicar na linha do Agente e clique em Conectar no cartão WhatsApp.
Um pop-up da Meta (conhecido como Embedded Signup) será exibido. Faça login e siga as etapas para selecionar sua Meta Business Account, a WABA e o número de telefone desejado.
Caso o número esteja apenas verificado, o fluxo solicitará o Registro para ativá-lo na plataforma. Pode ser necessário informar um PIN de autenticação de dois fatores (2FA) ou criar um novo.
Após a aprovação, o cartão na interface do SipPulse AI exibirá o número e o status mudará para Online. A partir desse momento, o Agente já está pronto para responder às mensagens recebidas.

Integração automática

Nenhuma configuração adicional de webhook é necessária. Ao concluir a conexão, o SipPulse AI é adicionado como Parceiro BSP (Business Solution Provider) do seu WhatsApp Business Account (WABA); a plataforma passa a gerir o envio e o recebimento de mensagens desse número de forma transparente.

Caso deseje revogar o acesso no futuro, acesse Meta Business Manager → Configurações do negócio → Contas → Contas do WhatsApp → Configurações → Parceiros e remova SipPulse AI da lista.

3. Ativar ou desativar rapidamente

Use o toggle no canto superior direito do cartão.

Ligado → o Agente processa mensagens em tempo real.
Desligado → o tráfego de entrada é ignorado; não há cobrança de tokens.

4. Preferências

Abra ⋮ → Preferências no cartão para ajustar o comportamento por número.

4.1 Encerramento por inatividade

Opção	Descrição
Tempo (min)	Período sem mensagens do usuário após o qual a conversa é encerrada.
Mensagem de fechamento	Texto enviado automaticamente antes do encerramento. Se vazio, nada é enviado.

Quando uma conversa é encerrada:
O Agente executa Pós‑Análises configuradas.
O webhook thread.closed é disparado (ver Webhooks).

4.2 Suporte a áudio (transcrição)

Campo	Função
Ativado	Converte mensagens de voz em texto para que o Agente possa responder.
Modelo	Escolha o modelo de transcrição (`pulse-precision-v3`, etc.). Custo conforme tabela de preços.

Se desativado, o usuário recebe a resposta padrão “Desculpe, não consigo processar mensagens de áudio.” O mesmo se aplica a imagens, vídeos ou documentos – suporte para esses tipos será adicionado futuramente.

5. Envio de mensagens proativas

Para que o Agente inicie uma conversa com um usuário, o WhatsApp exige o uso de Modelos de Mensagem (também conhecidos como Message Templates ou HSM). Esses modelos precisam ser criados e pré-aprovados pela Meta.

5.1 Criando um Modelo de Mensagem

Acesse o Meta Business Suite.
Navegue até Todas as ferramentas → Gerenciador do WhatsApp.
Selecione a WABA correta e vá para Ferramentas da conta → Modelos de mensagem.
Clique em Criar modelo.

Durante a criação, você definirá:

Categoria:
- Marketing: Promoções, ofertas, anúncios.
- Utilidade: Notificações de conta, alertas de pedido, etc.
- Autenticação: Códigos de uso único para login.
Nome: Um identificador único (ex: aviso_pedido_enviado).
Idiomas: Você pode criar versões para múltiplos idiomas.
Componentes:
- Cabeçalho (Opcional): Texto, imagem, vídeo ou documento.
- Corpo: O texto principal da mensagem. Use variáveis como 1, 2 para conteúdo dinâmico.
- Rodapé (Opcional): Uma linha de texto curta.
- Botões (Opcional): Botões de resposta rápida ou de chamada para ação (visitar site, ligar).

Após o envio, o modelo passa por uma revisão da Meta, que geralmente leva alguns minutos.

Referência: Para diretrizes detalhadas sobre a criação de templates, consulte a documentação oficial da Meta.

Importante: Se nenhum template aprovado existir na sua WABA, a lista de modelos na interface do SipPulse AI aparecerá vazia.

5.2 Envio manual pela UI

Clique em Enviar Mensagem no menu do cartão WhatsApp.
No painel lateral, escolha o Template desejado.
Informe o Número de destino (+5511987654321).
Preencha os Campos variáveis do template caso exista (ex.: {{name}}, {{order_id}}).
(Opcional) Escreva Instruções adicionais para contextualizar o Agente antes do envio.
Clique em Enviar.

5.3 Custos específicos

Cada template disparado abre uma conversa paga cujo valor é cobrado diretamente pela Meta (vide seção Custos).
O custo varia segundo a categoria do template e a região do destinatário.

5.4 Envio via API

Clique em </> Código na interface para obter exemplos completos em Python, JavaScript e cURL.

Endpoint:

text

POST /agent-deploy-whatsapp/{deploy_id}/send-message

Corpo da Requisição (Exemplo): O objeto variables é uma abstração do SipPulse AI para simplificar o preenchimento dos componentes do modelo.

json

{
  "template_name": "pedido_confirmado",
  "language_code": "pt_BR",
  "to": "+5511987654321",
  "variables": {
     "body": {
      "name": "Maria",
      "order_id": "98765"
    },
    "buttons": [
      "A98765"
    ]
  }
}

Estrutura do variables:

A API abstrai a complexidade dos componentes. Basta enviar os dados que deseja preencher:

body: (Obrigatório) Um objeto (dicionário) onde cada chave corresponde ao nome da variável no corpo do template (ex: name, order_id), e o valor é o conteúdo a ser inserido.
buttons: (Opcional) Uma lista de strings. Cada string na lista preenche uma variável nos botões dinâmicos, na ordem em que aparecem. É usado para completar URLs ou para botões de resposta rápida com conteúdo variável.

Cabeçalhos Obrigatórios:

Content-Type: application/json
api-key: {SIPPULSE_API_KEY}

Entrega não garantida

A resposta 200 Ok indica que o pedido foi recebido pelo SipPulse AI. A entrega ao usuário final depende da aprovação do template, da janela de conversação, do roteamento do WhatsApp e de possíveis pendências de pagamento na conta Meta Business. Utilize a guia Depuração para confirmar o status da mensagem.

6. Depuração

O menu ⋮ → Depuração exibe o histórico de mensagens e eventos:

Coluna	Significado
Processado em	Data/hora em UTC
Status	`received`, `sent`, `delivered`, `failed`, etc.
Tipo	`text`, `button`, etc...
Conteúdo	Trecho da mensagem ou descrição do evento

Filtros rápidos permitem isolar falhas ou testar tempo real com o botão Atualizar.

7. Custos

A utilização do canal WhatsApp envolve dois tipos de custos distintos:

Custos da Plataforma SipPulse AI:
- Processamento de Mensagens: Consumo de tokens do Agente, de acordo com o modelo de linguagem (LLM) configurado.
- Transcrição de Áudio: Custo adicional cobrado por minuto de áudio processado, conforme o modelo de transcrição escolhido.
Custos da Plataforma Meta:
- Conversas: A Meta cobra por cada conversa de 24 horas. O preço varia conforme a categoria da conversa (iniciada pelo usuário ou pela empresa via template) e o país do usuário final.
- Acompanhamento: Os custos da Meta são faturados diretamente na sua conta. Você pode monitorá-los em Meta Business Suite → Faturamento e Pagamentos.

Para detalhes sobre os preços da Meta, consulte a documentação oficial de preços da Plataforma WhatsApp Business.

Agentes

Implantando Agentes

Configurações

Integração com WhatsApp Business

1. Pré-requisitos

2. Conectar o número

3. Ativar ou desativar rapidamente

4. Preferências

4.1 Encerramento por inatividade

4.2 Suporte a áudio (transcrição)

5. Envio de mensagens proativas

5.1 Criando um Modelo de Mensagem

5.2 Envio manual pela UI

5.3 Custos específicos

5.4 Envio via API

6. Depuração

7. Custos

Implantando Agentes

Integração com WhatsApp Business ​

1. Pré-requisitos ​

2. Conectar o número ​

3. Ativar ou desativar rapidamente ​

4. Preferências ​

4.1 Encerramento por inatividade ​

4.2 Suporte a áudio (transcrição) ​

5. Envio de mensagens proativas ​

5.1 Criando um Modelo de Mensagem ​

5.2 Envio manual pela UI ​

5.3 Custos específicos ​

5.4 Envio via API ​

6. Depuração ​

7. Custos ​

Integração com WhatsApp Business

1. Pré-requisitos

2. Conectar o número

3. Ativar ou desativar rapidamente

4. Preferências

4.1 Encerramento por inatividade

4.2 Suporte a áudio (transcrição)

5. Envio de mensagens proativas

5.1 Criando um Modelo de Mensagem

5.2 Envio manual pela UI

5.3 Custos específicos

5.4 Envio via API

6. Depuração

7. Custos