> ## Documentation Index
> Fetch the complete documentation index at: https://ajuda.pandazap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configure as Integrações Externas da Plataforma
> Cadastre no PanÐá Zap as credenciais globais (URLs de API, chaves, tokens) dos provedores de IA, BSPs, gateways de WhatsApp não oficiais, webhooks, webchat, Google Calendar, SMS, voz e outros conectores externos que os canais e demais módulos da plataforma depois consomem.
Esta página reúne as duas telas de **Configurações** onde o Administrador cadastra credenciais, URLs e chaves de serviços externos usados pela plataforma: a aba **Bots IA** (provedores de automação e de inteligência artificial) e a aba **Integrações** (BSPs, webhooks, webchat, Google Calendar, gateways não oficiais de WhatsApp, SMS, voz e outros conectores).
Nenhuma dessas telas conecta um canal sozinha: elas apenas guardam as credenciais globais da conta. A criação efetiva do canal (número de WhatsApp, sessão, widget etc.) acontece depois, no menu **Canais**, documentado nas páginas específicas de cada tipo de canal. Pense nesta página como o "cofre de chaves" que os canais, o Chat Flow, os Agentes de IA e outros módulos vão buscar quando precisam falar com um serviço de fora do PanÐá Zap.
Esta página trata da aba **Integrações**, separada da aba **Integrações Meta** (conexão oficial com WhatsApp Business API, Instagram e Messenger direto pela Meta), que é documentada em outra página do Guia da Plataforma.
## Bots e IA
**Quem usa:** Administrador (habilitação e configuração das chaves). Atendentes e Supervisores usam os recursos de IA resultantes diretamente na tela de atendimento.
**O que é:** o painel **Bots e IA** centraliza e gerencia todas as ferramentas de automação e modelos de linguagem (LLMs) que vão operar no sistema. A plataforma tem integração nativa com:
* **Construtores de Fluxo e Automação:** Typebot, N8N, Dify e DialogFlow.
* **Modelos de Inteligência Artificial (LLMs):** ChatGPT, Grok, Gemini, Qwen, Claude, Deepseek, Ollama e LM Studio.
Clique no menu **Configurações** e selecione a aba **Bots IA**.
Em **Idioma Padrão da IA**, selecione o idioma principal do seu público (por exemplo, Português): é o idioma que a IA usará para interpretar e descrever mídias recebidas nos atendimentos (descrição de imagens e extração de texto via ChatGPT/GPT-4o ou Gemini). Se nada for selecionado, o sistema adota Português como padrão.
No menu lateral de Bots IA, clique no provedor desejado (por exemplo, **ChatGPT**).
Ative a chave **Habilitar \[Nome da IA]**: sem isso, a IA não aparece como opção nos canais.
Preencha a **API Key** correspondente, gerada no site do próprio provedor.
Se quiser automação total, ative também **Habilitar para todos os tickets**: a IA passará a processar e responder automaticamente todos os novos atendimentos, sem necessidade de ativação manual ticket a ticket.
Vá até o menu **Canais** e insira as credenciais (API Keys/Tokens) dentro das configurações de cada número/conexão que efetivamente usará aquela inteligência artificial. Habilitar o provedor em Bots IA é só o primeiro passo.
**Benefícios e quando usar:** ative os construtores de fluxo (Typebot, N8N, Dify, DialogFlow) quando quiser montar chatbots e automações visuais sem programar do zero. Ative os provedores de LLM quando quiser recursos de inteligência artificial nos atendimentos: descrição automática de imagens, geração de texto, e a base para o Copiloto de IA.
O painel Bots e IA também alimenta o **Copiloto de IA**, o assistente que apoia o Atendente em tempo real na tela de atendimento (sugestão de resposta, análise de sentimento, reescrita de mensagem, resumo de conversa, tradução inline e mais). O Copiloto tem sub-aba e fluxo de configuração próprios (Configurações → Bots IA → Copiloto de IA) e é detalhado por completo na página **Agentes de IA** do Guia da Plataforma; aqui basta saber que ele existe e depende dos provedores habilitados nesta tela.
**Dicas e observações importantes:**
* **A ativação dos provedores de IA é por conta do assinante.** É preciso criar uma conta e configurar o provedor por fora (no site da OpenAI, Google, Anthropic, Groq etc.) e só depois habilitar dentro do PanÐá Zap.
* As alterações desta página são salvas automaticamente assim que os campos são preenchidos ou os botões de seleção são alterados: não existe um botão "Salvar" separado.
## Integrações
**Quem usa:** Administrador.
**O que é:** o hub de **Integrações Externas** do PanÐá Zap: uma segunda aba de Configurações, separada da "Integrações Meta", que reúne conectores com provedores de WhatsApp não oficiais, canais de BSP, ferramentas de voz/SMS/IA e utilitários como Webhooks, Webchat e Google Calendar. Cada um dos itens abaixo corresponde a uma página do menu lateral desta aba.
**Como acessar:** menu **Configurações → Integrações**.
Boa parte destas integrações (Z-API, UazAPI, Evolution, Wuzapi) são **gateways não oficiais de WhatsApp**: conectam números via QR Code em vez da API oficial da Meta. Elas são úteis quando a empresa ainda não migrou para o WhatsApp Business API oficial, mas carregam o risco inerente de qualquer solução não oficial (possibilidade de bloqueio do número pela Meta). Sempre que possível, avalie se a Integração Meta (canal oficial) não atende melhor à sua necessidade antes de optar por um gateway não oficial.
**Quem usa:** Administrador.
**O que é:** página que unifica dois canais de **BSP** (Business Solution Providers, provedores de solução de negócio homologados pela Meta para operar contas WhatsApp Business API) em abas separadas: **360dialog** e **Gupshup**. Cada BSP tem sua própria sub-navegação para Canais, Templates e Credenciais.
**Integração em beta:** os canais BSP (Dialog360 e Gupshup) ainda estão em fase de testes e ajustes, sem previsão de homologação definida; a equipe responsável trabalha continuamente em correções.
**Aba Dialog360, passo a passo:**
1. Acesse **Configurações → Integrações → BSP** e selecione a aba **Dialog360**.
2. Em **Canais**, veja a lista de canais WhatsApp Business já conectados via 360dialog (colunas: Nome, Channel ID, Telefone, Status, Qualidade, Ações).
3. Clique em **+ Novo Canal** e escolha um dos dois modos:
* **Manual:** para contas 360dialog comuns (Customer Account). Cole a **D360-API-KEY** emitida no WABA Manager; os campos são preenchidos em um popup seguro com validação de licença.
* **Onboarding:** exclusivo para Tech Providers/Partners com credenciais oficiais 360dialog: abre o fluxo oficial 360dialog para autorizar a conexão e receber as credenciais automaticamente (clique em **Conectar via Dialog360**). Se você não tem relação Partner ativa com o 360dialog, use o modo Manual.
4. Em **Templates**, clique em **+ Novo Template** e preencha:
| Campo | Detalhe |
| ------------------ | -------------------------------------------------------- |
| Nome | Identificação do template |
| Idioma | Idioma do template |
| Categoria | Marketing, Utilidade ou Autenticação |
| Header | Opcional |
| Corpo da mensagem | Aceita variáveis `{{1}}`, `{{2}}`... até 1024 caracteres |
| Footer | Opcional, até 60 caracteres |
| Botões Quick Reply | Até 3 botões, até 20 caracteres cada |
O campo **Preview** mostra como a mensagem ficará antes de enviar para aprovação da Meta.
5\. Em **Credenciais**, configure os dados de Partner apenas se sua empresa atuar como BSP em nome de outros tenants: **Partner ID** (identificador alfanumérico do painel 360dialog, não é o e-mail), **Partner API Key** e **Platform Secret** (segredo HMAC do webhook). Deixe em branco se for usar o fluxo Manual com Customer Account. O salvamento é automático ao digitar.
**Aba Gupshup, passo a passo:**
1. Selecione a aba **Gupshup**.
2. Em **Canais**, clique em **+ Novo Canal** e escolha:
* **Manual:** para contas Gupshup comuns, cole **App ID** e **App Token** do painel Gupshup; os demais campos (API Key, Phone Number ID, WABA ID) são preenchidos em popup seguro.
* **Embedded Signup:** exclusivo para Tech Providers/Partners com Solution ID aprovado: informe o **Nome do canal** (opcional) e o **App ID** criado em `partner.gupshup.io`, depois clique em **Iniciar Embedded Signup**.
3. Em **Templates**, use o seletor de canal no topo e clique em **+ Criar Template**, preenchendo os mesmos campos do Dialog360 (Nome, Idioma, Categoria, Header, Corpo, Footer, Botões). O formulário Gupshup conta com o botão **✨ Gerar com IA** para criar o corpo do template a partir de um prompt.
4. Em **Credenciais**, configure os dados de Partner (**Partner Email**, **Partner Password**, **Solution ID**, **App ID** opcional) apenas se for atuar como BSP para outros tenants; para uma conta Customer comum, deixe em branco e use o fluxo Manual (nesse caso, o webhook precisa ser configurado manualmente no painel do app Gupshup).
**Benefícios e quando usar:** os canais BSP são uma alternativa à conexão direta via Meta (Integrações Meta) para empresas que já operam ou preferem operar através de um parceiro homologado 360dialog ou Gupshup: por exemplo, quando a empresa já tem contrato com um desses BSPs por outros motivos (preço, suporte local, recursos específicos).
**Dicas e observações importantes:**
* **Partner Account x Customer Account:** uma Partner Account (criada em `hub.360dialog.com` ou `partner.gupshup.io`) permite criar canais e emitir credenciais em nome de vários clientes, e exige cadastro e aprovação separados junto ao BSP. Uma Customer Account comum só gerencia os canais criados no próprio painel do BSP. Para conectá-la ao PanÐá Zap, use sempre o fluxo **Manual**, sem preencher os campos de Partner.
**Quem usa:** Administrador (configuração). Supervisores e o time de marketing se beneficiam diretamente dos relatórios de atribuição de anúncios.
**O que é:** ferramenta que identifica e mensura a eficácia dos anúncios pagos, atribuindo as mensagens recebidas no PanÐá Zap a campanhas específicas do Meta Ads (Facebook/Instagram) e gerando relatórios para o Google Analytics 4 (GA4). O sistema captura o parâmetro técnico `CTWA Click ID`, permitindo saber exatamente qual anúncio gerou cada atendimento: informação que também é devolvida à Meta para otimizar o algoritmo de entrega de anúncios e encontrar leads mais qualificados.
1. No menu principal, clique em **Configurações → Integrações** e, no submenu lateral esquerdo, clique em **Conversões Ads**.
2. Na aba **Configurações**, clique em **+ Nova credencial** para cadastrar as chaves de acesso:
| Serviço | Campos |
| ------------- | --------------------------------------------------------------------------------------------------------------- |
| Meta/Facebook | **Pixel ID** e **Access Token** (gerados no Gerenciador de Eventos da Meta, em Configurações → Conversions API) |
| Google GA4 | **Measurement ID** e **API Secret** (chave secreta do protocolo de mensuração) |
3. Clique em **+ Nova regra** para definir o que dispara uma conversão:
* Em **Gatilho**, selecione "Conversa Iniciada via Anúncio (WABA/Instagram/Messenger)".
* Em **Evento (Meta)**, use preferencialmente `LeadSubmitted` (ou `Lead`): é esse nome que aparece no Gerenciador de Anúncios para otimização de campanha.
* Em **Evento (G.A)**, defina um nome como `qualify_lead` ou `generate_lead` para fins de relatório no Analytics.
4. Configure a campanha na Meta como do tipo **"Cliques para o WhatsApp"** (destino direto no WhatsApp): é esse formato que faz a Meta anexar o `CTWA Click ID` quando o cliente clica no anúncio e envia mensagem. O PanÐá Zap identifica esse parâmetro automaticamente e devolve a confirmação de conversão para Meta e Google.
5. Na aba **Relatórios de Anúncios**, filtre por período, canal ou ID do anúncio para auditar os resultados: a tabela mostra Título do Anúncio, Contato, número do Ticket e o código CTWA Click ID; o **Status do Evento** confirma se a conversão foi "Enviada" com sucesso; use "Ver anúncio" para visualizar a peça criativa.
**Benefícios e quando usar:** essencial para empresas que investem em anúncios "Clique para o WhatsApp" no Meta Ads e querem saber, com precisão, quais campanhas realmente geram conversas e vendas, e não apenas cliques.
**Limitação de atribuição:** o rastreamento **não funciona** se o anúncio enviar o cliente para um site ou landing page intermediária antes do WhatsApp: quando isso acontece, o parâmetro original do anúncio (Click ID) se perde, impossibilitando a atribuição direta nesta página.
**Dicas e observações importantes:**
* **Google Ads é diferente da Meta:** o Google Ads não envia o ID de clique nativamente dentro da mensagem do WhatsApp. A integração com Google aqui serve para alimentar o GA4 com relatórios de volume, mas não otimiza lances de campanhas de pesquisa diretamente como ocorre com Facebook/Instagram.
* Em alguns casos a Meta cria um conjunto de dados automático para mensagens (por exemplo, "PanÐá Zap Event Data"). Verifique no Gerenciador de Eventos se o Pixel ID que você está usando é o mesmo que está recebendo os eventos de mensagem.
**Quem usa:** Administrador, normalmente em conjunto com quem cuida das automações externas (n8n, Make, etc.).
**O que é:** tela para configurar URLs de webhook que integram o PanÐá Zap a ferramentas externas, recebendo notificações automáticas sempre que eventos relevantes ocorrem na plataforma, sem precisar programar contra a API "na unha".
1. Acesse **Configurações → Integrações → Webhooks**.
2. Ative o toggle **Ativar webhook**.
3. Informe a **URL do Webhook**: o endereço público, em HTTPS, que receberá as requisições POST com os dados dos eventos.
4. Se quiser receber eventos de novas mensagens e atendimentos, ative também **Webhook mensagens**.
5. Clique em **Salvar**.
6. Role até **Eventos de canal e usuário** e ative, individualmente, os eventos que deseja monitorar: **Webhook criar/atualizar canal**, **Webhook criar/atualizar usuário** e **Webhook criar/atualizar/renovar API**. Cada toggle é independente.
7. Clique em **Salvar** novamente.
**Benefícios e quando usar:** use ferramentas como n8n ou Make para receber, filtrar e automatizar ações com base nos eventos enviados pelo PanÐá Zap: por exemplo, registrar automaticamente em uma planilha todo novo canal criado, ou notificar um grupo interno quando um usuário for cadastrado.
**Dicas e observações importantes:**
* **A URL precisa ser pública, acessível externamente, aceitar requisições POST e usar HTTPS.** URLs locais (`localhost`) não funcionam.
* **Eventos não chegam na sua URL?** A causa mais comum é a URL estar inacessível externamente, sem HTTPS, ou com firewall bloqueando entradas. Use um serviço como o RequestBin para gerar uma URL temporária de teste e confirmar que os eventos estão sendo disparados pelo PanÐá Zap antes de apontar para a URL definitiva.
* Para verificar se o webhook está disparando corretamente, consulte o **Log de Auditoria**: ele guarda o histórico de eventos enviados e ajuda a identificar erros ou falhas no disparo.
**Quem usa:** Administrador (configuração). Atendentes e Supervisores recebem as conversas do widget normalmente, como qualquer outro ticket.
**O que é:** tela para configurar o widget de **Webchat**, que incorpora um chat ao vivo diretamente no site da empresa. As mensagens dos visitantes chegam em tempo real na plataforma como atendimentos normais.
1. Certifique-se de que já existe um canal do tipo Webchat instalado e conectado (pré-requisito).
2. Acesse **Configurações → Integrações → Webchat** e confira se o painel de status exibe, em verde, a mensagem confirmando que o serviço está ativo.
3. Em **Canal Webchat**, selecione a sessão Webchat que receberá os atendimentos vindos do site.
4. Se desejar, marque **Habilitar botões de menu (#MENU)**: quando ativo, mensagens no formato `#MENU` são renderizadas como botões clicáveis no widget.
5. Clique em **Gerar Widget**.
6. Copie o código JavaScript gerado e cole no HTML do site, **antes do fechamento da tag ``**.
7. Teste enviando uma mensagem pelo widget: ela deve chegar na plataforma como um novo atendimento.
**Benefícios e quando usar:** ideal para empresas que querem oferecer atendimento em tempo real diretamente no site institucional ou loja virtual, sem depender apenas do WhatsApp: os visitantes conversam pelo próprio site e a conversa entra na mesma fila/painel usado para os demais canais.