Integrações & Segurança

Configure integrações externas, proteja suas credenciais e entenda como o Dexter mantém seus dados seguros.

Visão geral

O Dexter se integra com vários serviços para ampliar as capacidades dos seus assistentes. Esta página cobre como configurar cada integração e boas práticas de segurança.

Todas as integrações são configuradas pela tela Configurações → Integrações no dashboard, com credenciais armazenadas de forma segura no servidor.

API Keys

O que são

API Keys são chaves de autenticação que permitem que sistemas externos acessem a API REST e o servidor MCP do Dexter em nome da sua instância. Cada chave é gerada com o prefixo dx_live_ e está vinculada a uma única instância.

Como gerar

1
Acesse o dashboard

Vá em Configurações → Integrações e localize a seção API Key.

2
Gere a chave

Clique em Gerar nova API Key. A chave será exibida uma única vez — copie e armazene em local seguro.

Como usar

Envie a chave no header Authorization de cada requisição: 

Authorization: Bearer YOUR_API_KEY
Atenção: nunca compartilhe sua API Key, não a exponha em código frontend ou repositórios públicos. Se suspeitar de comprometimento, gere uma nova chave imediatamente.

Boas práticas

  • Armazene a chave em variáveis de ambiente do servidor, nunca no código-fonte.
  • Não exponha a chave em aplicações frontend ou mobile.
  • Rotacione a chave periodicamente — gere uma nova e descarte a antiga.
  • Use permissões mínimas (veja Permissões MCP e API).

Integrações disponíveis

OpenAI

A API Key da OpenAI alimenta os modelos de IA que dão inteligência aos seus assistentes. Sem ela, o assistente não consegue gerar respostas.

Z-API

Provedor externo de conexão WhatsApp. Você precisará de três credenciais da sua conta Z-API: Instance ID, Token e Client Token.

Evolution API

Com a Evolution API, o Dexter provisiona a instância WhatsApp automaticamente. Basta seguir o assistente de conexão no dashboard — nenhuma configuração externa é necessária.

Google Calendar

Integração via OAuth que permite ao assistente consultar agenda, verificar horários livres e agendar reuniões diretamente pelo WhatsApp. Disponível nos planos Professional e Scale.

Firecrawl / Apify

Serviços de enriquecimento de dados usados pelo Dexter Data Intelligence (DDI) para pesquisar informações públicas sobre leads e alimentar a base de contatos.

Validador WhatsApp

Verifica se um número de telefone possui WhatsApp ativo antes de enviar mensagens, reduzindo falhas de entrega e melhorando a qualidade da base de contatos.

Resumo

Integração Credenciais necessárias Planos disponíveis
OpenAI API Key Todos
Z-API Instance ID, Token, Client Token Todos
Evolution API Provisionamento automático Todos
Google Calendar OAuth (autorização no dashboard) Professional, Scale
Firecrawl / Apify API Key do serviço Todos (DDI)
Validador WhatsApp Configurado automaticamente Todos

Configurar integrações

1
Acesse a tela de integrações

No dashboard, vá em Configurações → Integrações.

2
Preencha as credenciais

Insira as chaves e tokens da integração desejada nos campos correspondentes. Para a OpenAI, cole a API Key. Para a Z-API, preencha Instance ID, Token e Client Token.

3
Teste a conexão

Clique em Testar ao lado da integração. O Dexter verificará se as credenciais estão corretas e se a conexão funciona.

4
Salve

Após o teste bem-sucedido, clique em Salvar. A integração estará ativa imediatamente.

Dica: você pode alterar ou revogar credenciais a qualquer momento retornando à tela de integrações.

Webhooks

O Dexter pode enviar notificações HTTP (webhooks) para uma URL configurada por você sempre que eventos relevantes ocorrem na sua instância.

Eventos disponíveis

Evento Header X-Dexter-Event Descrição
Mensagem recebida message.received Disparado quando uma mensagem inbound chega no WhatsApp

Como configurar

1
Acesse webhooks

No dashboard, vá em Configurações → Integrações e localize a seção Webhook de Notificação.

2
Informe a URL e o secret

Insira a URL do seu endpoint e um webhook secret para validar a autenticidade das chamadas.

3
Ative e salve

Marque o webhook como ativo e clique em Salvar.

Formato do payload

O Dexter envia um POST com corpo JSON para a URL configurada:

{
  "event": "message.received",
  "phone": "5511999999999",
  "name": "Nome do contato",
  "isGroup": false,
  "type": "ReceivedCallback",
  "text": "Conteudo da mensagem",
  "messageId": "ABCDEF123456",
  "timestamp": 1719500000
}

Headers da requisição

Header Descrição
Content-Type application/json
User-Agent Dexter-Webhooks/1.0
X-Dexter-Event Nome do evento (ex.: message.received)
X-Dexter-Signature Assinatura HMAC-SHA256 do body, prefixada com sha256=

Validando a assinatura

Para garantir que a chamada veio do Dexter, valide o header X-Dexter-Signature comparando com o HMAC-SHA256 do body usando seu webhook secret: 

# Python
import hmac, hashlib

def verify_signature(body: bytes, secret: str, signature: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode("utf-8"), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)
Importante: sempre valide a assinatura antes de processar o payload. Requisições sem assinatura válida devem ser rejeitadas com status 401.

Permissões MCP e API

O Dexter usa um sistema de três níveis de permissão para controlar o que cada API Key pode fazer via MCP e API REST.

Nível Acesso Exemplos de operações
Read Somente leitura Listar contatos, consultar campanhas, ver métricas, ler histórico de conversas
Write Leitura + escrita de dados Criar/atualizar contatos, adicionar/remover tags
Send Leitura + escrita + envio de mensagens Enviar mensagens WhatsApp via API ou MCP

Como configurar

1
Acesse permissões

No dashboard, vá em Configurações → Integrações. Na seção MCP, ative o endpoint e configure os níveis desejados.

2
Selecione os níveis

Ative Read (habilitado automaticamente com o MCP), Write e/ou Send conforme a necessidade.

Princípio do menor privilégio: conceda apenas as permissões estritamente necessárias para a integração. Se você precisa apenas consultar dados, não ative Write ou Send.

Rate limits

O Dexter aplica limites de taxa automáticos para proteger sua conta e garantir a estabilidade do serviço. Esses limites previnem envios acidentais em massa e protegem contra uso indevido da API.

Limites de envio de mensagens

  • Gap mínimo entre envios para o mesmo número de telefone.
  • Proteção contra envio da mesma mensagem para o mesmo número em intervalo curto.
  • Limites de requisições por minuto nos endpoints da API.

Resposta quando excedido

Se o limite for excedido, a API retorna HTTP 429 (Too Many Requests) com um campo retryAfterSec indicando quantos segundos aguardar: 

{
  "ok": false,
  "error": "rate_limited",
  "retryAfterSec": 30
}
Recomendação: implemente retry com backoff exponencial na sua integração. Ao receber 429, aguarde o tempo indicado em retryAfterSec antes de tentar novamente.

Allowlist de envio

O Dexter oferece um modo de segurança que restringe o envio de mensagens apenas para números previamente autorizados em uma allowlist.

Quando usar

  • Ambientes de teste e staging, para evitar envios acidentais a números reais.
  • Fase de validação, antes de liberar o envio para toda a base de contatos.
  • Operações críticas onde o envio precisa ser controlado manualmente.

Como funciona

Quando ativo, qualquer tentativa de envio para um número fora da allowlist é bloqueada com status 403. Isso vale para todos os canais de envio: assistente, campanha, API REST e MCP.

Configuração: a allowlist é controlada por variável de ambiente no servidor e não está exposta na interface do dashboard. Consulte o suporte ou o administrador do sistema para ativá-la.

Segurança de dados

Dados em trânsito

Todas as comunicações entre o seu navegador, a API e o servidor do Dexter são protegidas por HTTPS (TLS).

Credenciais

Tokens, API Keys e segredos de integração são armazenados de forma segura no servidor. Credenciais sensíveis nunca são retornadas em chamadas de API — campos protegidos são mascarados na interface.

Isolamento de dados

Cada instância (tenant) opera de forma isolada. Dados de contatos, conversas, campanhas e configurações de uma instância não são acessíveis por outra.

Sem acesso por terceiros

O Dexter não compartilha mensagens ou dados de contato com terceiros. As mensagens trafegam entre o provedor WhatsApp (Z-API ou Evolution) e o servidor do Dexter, sem intermediários.

Conformidade LGPD

Os dados dos seus clientes ficam sob controle do tenant (sua empresa). Você é o controlador dos dados e pode excluir contatos e histórico a qualquer momento pelo dashboard.

Erros comuns

Código Mensagem Causa provável Solução
401 Unauthorized API Key inválida, expirada ou ausente Verifique se a chave está correta e inclua o header Authorization: Bearer YOUR_API_KEY
403 Forbidden Permissão insuficiente para a operação Ative a permissão necessária (Write ou Send) na tela de Integrações
429 Too Many Requests Rate limit excedido Aguarde o tempo indicado em retryAfterSec e tente novamente
403 send_api_disabled Envio via API não está habilitado Ative API de envio em Configurações → Integrações
403 BLOCKED by allowlist Número não está na allowlist de envio Adicione o número à allowlist ou desative o modo allowlist
Webhook secret inválido: se a validação de assinatura falhar no seu endpoint, verifique se o secret configurado no dashboard é o mesmo usado para calcular o HMAC no lado do receptor.
API REST — Referência MCP — Visão Geral MCP — Referência de Tools Primeiros Passos