API REST — Referência

Referência completa dos endpoints públicos da API REST do Dexter. Todos os exemplos usam curl; adapte para a linguagem do seu projeto.

Visão geral

Autenticação

Os endpoints /api/v1/* usam autenticação via API Key no header Authorization.

Inclua a chave em todas as requisições:

Authorization: Bearer YOUR_API_KEY

Erros de autenticação

Código	Erro	Causa
401	missing_bearer_token	Header Authorization ausente ou sem prefixo Bearer .
401	invalid_api_key	Chave inválida, expirada ou revogada.
503	instance_not_configured	A instância associada à chave não está configurada (sem credenciais Z-API/Evolution).

Enviar mensagem — POST /api/v1/messages

Envia uma mensagem de WhatsApp para um número de telefone.

Parâmetros (body JSON)

Parâmetro	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do destinatário com DDI, sem símbolos. Ex.: "5511999999999"
message	string	Sim	Texto da mensagem a enviar.
delay_typing	integer	Não	Delay de digitação em segundos antes do envio. Se omitido, um valor aleatório entre 3 e 10 s é usado. Valores informados são limitados ao intervalo 3–15 s.
delay_send	integer	Não	Agendar o envio para daqui a N minutos (1–1440, ou seja, até 24 h). O envio fica em memória — um restart do servidor descarta envios pendentes.

Exemplo — envio imediato

curl -X POST https://app.dexteragents.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Ola! Como posso ajudar?"
  }'

Resposta de sucesso

{
  "ok": true,
  "status": 200,
  "typing_sec": 5,
  "response": "..."
}

Exemplo — envio agendado

curl -X POST https://app.dexteragents.com/api/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "message": "Lembrete: sua reuniao e amanha as 14h.",
    "delay_send": 60
  }'

Resposta (agendado)

{
  "ok": true,
  "scheduled": true,
  "dispatch_at": "2026-09-25T15:30:00",
  "delay_send_min": 60,
  "typing_sec": 7,
  "note": "scheduled in-memory; a server restart drops pending sends"
}

Erros específicos

Código	Erro	Causa
400	invalid_json	Body não é JSON válido.
400	phone_and_message_required	phone ou message ausente/vazio.
400	invalid_delay_send	delay_send não é um número válido.
403	send_api_disabled	A permissão de envio via API não está habilitada na instância.
409	suppressed	Número bloqueado pelo Dexter Data Intelligence (supressão automática).
502	—	Falha na comunicação com o provedor WhatsApp (Z-API/Evolution).

Gerenciar leads — POST /api/v1/leads

Cria ou atualiza um lead (contato) e, opcionalmente, envia uma primeira mensagem. Ideal para integrações com formulários, landing pages e CRMs externos.

Parâmetros (body JSON)

Parâmetro	Tipo	Obrigatório	Descrição
phone	string	Sim	Número do lead com DDI. Ex.: "5511999999999"
name	string	Não	Nome do contato.
message	string	Não	Mensagem inicial a enviar ao lead (requer send_first_message habilitado na config).
definir_agente	string	Não	Agente que atenderá o lead (ex.: "sdr", "cs"). Se omitido ou inválido, usa o agente padrão da configuração.
lock_agent	boolean	Não	Se true, trava o agente definido (impede roteamento automático). Padrão: true.
delay_typing	integer	Não	Delay de digitação (3–15 s). Padrão: aleatório 3–10 s.
delay_send	integer	Não	Agendar envio da mensagem inicial em N minutos (1–1440).
campos extras	qualquer	Não	Qualquer campo adicional no body é salvo como customData no contato. Use para armazenar origem, campanha, utm, etc.

Exemplo

curl -X POST https://app.dexteragents.com/api/v1/leads \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999999999",
    "name": "Maria Silva",
    "definir_agente": "sdr",
    "message": "Oi Maria! Vi que voce se cadastrou. Como posso ajudar?",
    "origem": "landing-page",
    "utm_source": "google"
  }'

Resposta de sucesso

{
  "ok": true,
  "contact": "5511999999999",
  "agent": "sdr",
  "locked": true,
  "sent": true,
  "send_status": 200
}

Resposta (com envio agendado)

{
  "ok": true,
  "contact": "5511999999999",
  "agent": "sdr",
  "locked": true,
  "sent": false,
  "scheduled": true,
  "dispatch_at": "2026-09-25T16:00:00",
  "delay_send_min": 30,
  "typing_sec": 5
}

Erros específicos

Código	Erro	Causa
400	invalid_json	Body não é JSON válido.
400	phone_required	phone ausente ou vazio.
400	invalid_delay_send	delay_send não é um número válido.
403	lead_intake_disabled	Lead Intake não está habilitado na instância.
500	contact_upsert_failed	Erro ao salvar o contato no banco de dados.

Webhook de mensagens recebidas — POST /zapi/webhook

Endpoint que recebe notificações do provedor WhatsApp (Z-API ou Evolution) quando uma mensagem chega ao seu número. Você não chama este endpoint — ele é chamado pelo provedor.

URL do webhook

Configure no painel do seu provedor WhatsApp a URL:

https://app.dexteragents.com/zapi/webhook?instance=SEU_INSTANCE_ID

Validação de secret (opcional, recomendado)

Se a variável WEBHOOK_SECRET estiver configurada, o Dexter valida o secret em cada requisição. Envie de uma das formas:

Método	Exemplo
Query parameter	/zapi/webhook?instance=123&secret=YOUR_WEBHOOK_SECRET
Header	X-Webhook-Secret: YOUR_WEBHOOK_SECRET

Payload recebido (exemplo Z-API)

{
  "phone": "5511999999999",
  "chatName": "Maria Silva",
  "messageId": "ABCDEF1234567890",
  "fromMe": false,
  "senderName": "Maria Silva",
  "type": "ReceivedCallback",
  "body": {
    "text": "Oi, quero saber mais sobre o servico"
  }
}

Tipos de callback aceitos

O Dexter processa apenas os tipos:

• ReceivedCallback — mensagem recebida
• ReactionCallback — reação a mensagem

Todos os outros tipos (DeliveryCallback, MessageStatusCallback, etc.) são ignorados com 200 OK.

Deduplicação

O Dexter mantém um buffer de até 5.000 messageIds por instância, persistido em disco. Se o provedor entregar a mesma mensagem mais de uma vez, a segunda chamada recebe:

{
  "ok": true,
  "received": true,
  "dedup": true,
  "messageId": "ABCDEF1234567890"
}

Resposta esperada

Retorne 200 OK ao provedor. O Dexter sempre responde com JSON:

{
  "ok": true,
  "received": true
}

Comportamento com campanhas ativas

MCP — POST /api/v1/mcp

Endpoint do Model Context Protocol (MCP) para integração com agentes de IA, como Claude, GPT e outros que suportam MCP.

Níveis de permissão

As tools MCP são agrupadas por nível de acesso, configurável no dashboard:

Nível	Permissão	Descrição
Leitura	mcp.enabled	Consultar contatos, conversas, campanhas, agentes, métricas.
Escrita	mcp.enabled + mcp.allow_write	Criar/editar contatos, tags e campanhas.
Envio	mcp.enabled + mcp.allow_send	Enviar mensagens WhatsApp via MCP.

Exemplo — requisição JSON-RPC

curl -X POST https://app.dexteragents.com/api/v1/mcp \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {"name": "meu-agente", "version": "1.0"}
    }
  }'

Resposta

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {"tools": {}},
    "serverInfo": {"name": "dexter-mcp", "version": "1.0.0"},
    "instructions": "..."
  }
}

Códigos de erro

Tabela geral de códigos HTTP retornados pela API:

Código	Significado	Ação recomendada
200	Sucesso	—
202	Aceito (MCP: notificação processada)	—
400	Request inválido	Verifique os parâmetros enviados. O campo error na resposta indica o problema específico.
401	Não autenticado	Verifique se o header Authorization: Bearer YOUR_API_KEY está presente e correto.
403	Sem permissão	O recurso existe, mas a permissão necessária não está habilitada. Verifique as Integrações no dashboard.
404	Não encontrado	Verifique a URL do endpoint.
405	Método não permitido	O endpoint MCP aceita apenas POST. Requisições GET retornam 405.
409	Conflito / Suprimido	O número está na lista de supressão do Data Intelligence. O envio foi bloqueado por proteção automática.
429	Rate limited	Limite de requisições atingido. Aguarde e tente novamente com backoff exponencial.
500	Erro interno	Erro inesperado no servidor. Se persistir, entre em contato com o suporte.
502	Erro no provedor	Falha na comunicação com Z-API/Evolution. Verifique a conexão do WhatsApp no dashboard.
503	Instância não configurada	A instância associada à API Key não possui credenciais do provedor WhatsApp configuradas.

Todas as respostas de erro incluem um body JSON com o campo error:

{
  "ok": false,
  "error": "phone_and_message_required"
}

Boas práticas

Links relacionados