MCP — Referencia Completa de Tools

Cada tool requer um nivel de permissao configurado na tela Integracoes do dashboard.

Busca contatos da instancia por nome, telefone, tag ou agente responsavel. Resultado paginado.

Parametros

Exemplo de chamada

{
  "name": "dexter_contacts_search",
  "arguments": {
    "query": "Maria",
    "agent": "sdr",
    "limit": 5
  }
}

Exemplo de resposta

{
  "total": 12,
  "offset": 0,
  "limit": 5,
  "contacts": [
    {
      "phone": "5511999990001",
      "name": "Maria Souza",
      "waName": "Maria S.",
      "agent": "sdr",
      "active": true,
      "updatedAt": 1719300000,
      "tags": ["lead-quente", "demo-agendada"]
    }
  ]
}

Caso de uso

Buscar contatos antes de enviar uma mensagem, verificar se um lead ja existe na base, ou filtrar contatos de um agente especifico para relatorios.

Permissao: Read

Retorna os dados completos de um contato: campos, tags, campos customizados e estatisticas de conversa.

Parametros

Exemplo de chamada

{
  "name": "dexter_contacts_get",
  "arguments": {
    "phone": "5511999990001"
  }
}

Exemplo de resposta

{
  "phone": "5511999990001",
  "name": "Maria Souza",
  "waName": "Maria S.",
  "agent": "sdr",
  "active": true,
  "updatedAt": 1719300000,
  "tags": ["lead-quente"],
  "customData": { "empresa": "Acme Ltda", "cargo": "Gerente" },
  "totalMessages": 47,
  "lastMessageTs": 1719299500
}

Caso de uso

Obter o perfil completo de um contato antes de iniciar uma conversa, verificar campos customizados ou conferir o volume de mensagens trocadas.

Permissao: Read

Cria ou atualiza um contato pelo telefone. Atualiza somente os campos informados (upsert inteligente) — campos omitidos permanecem inalterados.

Parametros

Exemplo de chamada

{
  "name": "dexter_contacts_upsert",
  "arguments": {
    "phone": "5511999990001",
    "name": "Maria Souza",
    "agent": "sdr",
    "active": true,
    "custom_fields": { "empresa": "Acme Ltda" }
  }
}

Exemplo de resposta

{
  "phone": "5511999990001",
  "name": "Maria Souza",
  "waName": "Maria S.",
  "agent": "sdr",
  "active": true,
  "updatedAt": 1719301000,
  "tags": [],
  "customData": { "empresa": "Acme Ltda" },
  "totalMessages": 0,
  "lastMessageTs": 0
}

Caso de uso

Cadastrar um novo lead vindo de formulario externo, atualizar o agente responsavel por um contato ou enriquecer dados customizados do CRM.

Permissao: Write

Adiciona e/ou remove tags de um contato em uma unica chamada.

Parametros

Exemplo de chamada

{
  "name": "dexter_contacts_tag",
  "arguments": {
    "phone": "5511999990001",
    "add": ["demo-agendada", "qualificado"],
    "remove": ["lead-frio"]
  }
}

Exemplo de resposta

{
  "phone": "5511999990001",
  "tags": ["lead-quente", "demo-agendada", "qualificado"]
}

Caso de uso

Classificar leads apos qualificacao automatica, mover contatos entre etapas do funil, ou segmentar audiencia para campanhas futuras.

Permissao: Write

Lista todas as tags da instancia com a quantidade de contatos em cada uma.

Parametros

Exemplo de chamada

{
  "name": "dexter_contact_tags_list",
  "arguments": {}
}

Exemplo de resposta

{
  "tags": [
    { "tag": "lead-quente", "count": 34 },
    { "tag": "cliente-ativo", "count": 18 },
    { "tag": "demo-agendada", "count": 7 }
  ],
  "total": 3
}

Caso de uso

Verificar quais tags existem antes de segmentar a audiencia de uma campanha, ou montar um relatorio de distribuicao do funil.

Permissao: Read

Relatorio sob demanda de leads parados: contatos SDR ativos sem interacao ha N dias e fora de campanha ativa. Somente leitura — nao cria itens na fila de trabalho.

Parametros

Exemplo de chamada

{
  "name": "dexter_stale_leads",
  "arguments": {
    "days": 7,
    "limit": 10
  }
}

Exemplo de resposta

{
  "days": 7,
  "total": 5,
  "leads": [
    {
      "phone": "5521988887777",
      "name": "Joao Lima",
      "silentDays": 12,
      "lastRole": "assistant",
      "lastText": "Fico no aguardo do seu retorno!",
      "leadReplied": true,
      "tier": "warm"
    }
  ]
}

Caso de uso

Identificar leads que precisam de follow-up, montar campanhas de reativacao ou gerar relatorio de leads inativos para o time comercial.

Permissao: Read

Lista conversas da instancia a partir do historico acumulado, incluindo numeros que nao estao salvos em Contatos. Resultado paginado, ordenado pela mensagem mais recente.

Parametros

Exemplo de chamada

{
  "name": "dexter_conversations_list",
  "arguments": {
    "only_unsaved": true,
    "limit": 10
  }
}

Exemplo de resposta

{
  "total": 42,
  "offset": 0,
  "limit": 10,
  "hasMore": true,
  "conversations": [
    {
      "phone": "5511988880001",
      "name": "",
      "waName": "Carlos M.",
      "savedContact": false,
      "messageCount": 8,
      "lastTs": 1719301000,
      "lastText": "Boa tarde, gostaria de saber...",
      "lastRole": "user",
      "pending": true
    }
  ]
}

Caso de uso

Descobrir telefones de conversas que ainda nao foram salvos como contato, identificar conversas pendentes de resposta (pending: true), ou montar dashboard de atividade.

Permissao: Read

Retorna mensagens da conversa de WhatsApp com um telefone (contato salvo ou nao). Por padrao devolve as ultimas N mensagens. Suporta paginacao bidirecional.

Parametros

Exemplo de chamada

{
  "name": "dexter_conversations_history",
  "arguments": {
    "phone": "5511999990001",
    "limit": 20,
    "offset": 0
  }
}

Exemplo de resposta

{
  "phone": "5511999990001",
  "count": 20,
  "total": 153,
  "offset": 0,
  "limit": 20,
  "hasMore": true,
  "oldestTs": 1719200000,
  "newestTs": 1719301000,
  "messages": [
    { "ts": 1719200000, "role": "user", "text": "Boa tarde!" },
    { "ts": 1719200010, "role": "assistant", "text": "Ola! Como posso ajudar?" }
  ]
}

Caso de uso

Ler o historico completo de uma conversa para contexto, exportar mensagens para auditoria, ou revisar a interacao do agente com um lead.

Permissao: Read

Lista as campanhas da instancia com id, nome, status e tipo. Resultado paginado.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_list",
  "arguments": {
    "status": "active",
    "limit": 10
  }
}

Exemplo de resposta

{
  "total": 3,
  "offset": 0,
  "limit": 10,
  "campaigns": [
    {
      "id": 42,
      "name": "Reativacao leads frios",
      "status": "active",
      "type": "finite"
    }
  ]
}

Caso de uso

Monitorar campanhas em execucao, listar rascunhos pendentes de ativacao ou gerar relatorio de todas as campanhas.

Permissao: Read

Status detalhado de uma campanha: contagem de contatos por estado, respostas recebidas e proximo envio agendado.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_status",
  "arguments": {
    "campaign_id": 42
  }
}

Exemplo de resposta

{
  "id": 42,
  "name": "Reativacao leads frios",
  "status": "active",
  "type": "finite",
  "contacts": {
    "total": 50,
    "replied": 8,
    "byState": { "active": 30, "done": 12, "failed": 0 }
  },
  "nextSendAtMs": 1719400000000,
  "pendingNextSend": 30,
  "createdAtMs": 1719200000000,
  "updatedAtMs": 1719300000000,
  "endsAtMs": 1719500000000
}

Caso de uso

Acompanhar o progresso de uma campanha ativa, verificar taxa de resposta ou identificar quando sera o proximo envio.

Permissao: Read

Assistente interativo de criacao de campanha finita. Retorna a proxima pergunta que precisa ser respondida antes de criar a campanha. Nao grava nenhum dado.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_prepare",
  "arguments": {
    "name": "Follow-up leads demo"
  }
}

Exemplo de resposta

{
  "campaignType": "finite",
  "ready": false,
  "filled": {
    "name": true,
    "audience": false,
    "generationMode": "",
    "selectedTopicKey": "",
    "messages": false
  },
  "missing": ["audience"],
  "askNext": "Quem recebe? Uma lista de telefones com DDI ou uma tag que ja existe na instancia?",
  "defaults": {
    "blocksCount": 3,
    "messagesPerBlock": 1,
    "sendIntervalSec": 86400,
    "maxContactsPerDay": 20,
    "endsInDays": 3,
    "allowedWindows": [
      { "days": [0,1,2,3,4], "start": "09:00", "end": "18:00", "tz": "America/Sao_Paulo" }
    ]
  }
}

Caso de uso

Guiar o processo de criacao de campanha passo a passo. Chame repetidamente preenchendo os campos pendentes ate ready: true.

Permissao: Read

Lista os assuntos disponiveis no Knowledge Base para campanhas finitas. Quando o modo de geracao for kb_topic, escolha um topicKey desta lista — nao invente assuntos.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_kb_topics",
  "arguments": {
    "knowledgeSources": {
      "assistants": ["sdr"],
      "includeGlobalBlocks": true
    }
  }
}

Exemplo de resposta

{
  "knowledgeSources": { "assistants": ["sdr"], "includeGlobalBlocks": true },
  "topics": [
    { "topicKey": "planos-preco", "title": "Planos e Precos", "snippetCount": 4 },
    { "topicKey": "funcionalidades", "title": "Funcionalidades", "snippetCount": 6 }
  ],
  "total": 2
}

Caso de uso

Listar assuntos disponiveis antes de gerar mensagens com dexter_campaigns_generate no modo kb_topic.

Permissao: Read

Previa de quem entraria numa campanha finita, por telefones ou por tag. Nao grava nenhum dado.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_audience_preview",
  "arguments": {
    "audience_tag": "lead-quente",
    "excludeActiveCampaignContacts": true
  }
}

Exemplo de resposta

{
  "eligible": 28,
  "excluded": 4,
  "alreadyInCampaign": 3,
  "samplePhones": ["5511999990001", "5521988880002", "5531977770003"]
}

Caso de uso

Verificar o tamanho e composicao da audiencia antes de criar a campanha, evitando surpresas com o volume de envios.

Permissao: Read

Gera os blocos de mensagens de uma campanha finita usando IA. Nao grava a campanha — mostre o texto ao usuario antes de criar.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_generate",
  "arguments": {
    "generationMode": "kb_topic",
    "knowledgeSources": { "assistants": ["sdr"] },
    "topicKey": "planos-preco",
    "blocksCount": 3,
    "messagesPerBlock": 1,
    "messageTone": "profissional"
  }
}

Exemplo de resposta

{
  "generated": true,
  "persisted": false,
  "messages": [
    "Ola {{nome}}! Vi que voce se interessou pelos nossos planos...",
    "{{nome}}, queria compartilhar uma novidade sobre...",
    "Ultima mensagem da serie: temos uma condicao especial..."
  ],
  "messageBlocks": [ ... ],
  "selectedTopic": "Planos e Precos",
  "selectedTopicKey": "planos-preco",
  "selectedSnippets": [ ... ],
  "knowledgeSources": { "assistants": ["sdr"] },
  "generationMode": "kb_topic"
}

Caso de uso

Gerar rascunho das mensagens da campanha para revisao humana antes de criar o rascunho final.

Permissao: Write

Cria uma campanha finita em rascunho. A campanha nao e ativada automaticamente — a ativacao requer uma chamada separada a dexter_campaigns_activate.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_create",
  "arguments": {
    "name": "Follow-up leads demo",
    "messages": [
      "Ola {{nome}}! Tudo bem? Queria retomar nossa conversa...",
      "{{nome}}, tenho uma novidade que pode te interessar...",
      "Ultima oportunidade: condicao especial ate sexta!"
    ],
    "audience_tag": "lead-quente",
    "generationMode": "scratch",
    "maxContactsPerDay": 15,
    "endsInDays": 5
  }
}

Exemplo de resposta

{
  "created": true,
  "campaignId": 43,
  "status": "draft",
  "campaignType": "finite",
  "note": "Campanha criada em RASCUNHO. Para ativar, use dexter_campaigns_activate e a frase ATIVAR com o id."
}

Caso de uso

Criar o rascunho final da campanha apos gerar e revisar as mensagens. O proximo passo e usar dexter_campaigns_activate.

Permissao: Write

Ativa uma campanha finita em rascunho. Requer confirmacao explicita do usuario.

Parametros

Fluxo de ativacao (duas chamadas)

Exemplo — chamada 1 (solicitar resumo)

{
  "name": "dexter_campaigns_activate",
  "arguments": {
    "campaign_id": 43
  }
}

Exemplo de resposta (resumo)

{
  "needsConfirmation": true,
  "activated": false,
  "campaignId": 43,
  "status": "draft",
  "name": "Follow-up leads demo",
  "firstMessage": "Ola {{nome}}! Tudo bem? Queria retomar...",
  "windows": "[{\"days\":[0,1,2,3,4],\"start\":\"09:00\",\"end\":\"18:00\"}]",
  "audience": { "eligible": 28 },
  "requiredPhrase": "ATIVAR 43",
  "note": "Mostre este resumo e espere o usuario escrever a frase. Nao invente a confirmacao."
}

Exemplo — chamada 2 (confirmar)

{
  "name": "dexter_campaigns_activate",
  "arguments": {
    "campaign_id": 43,
    "confirmation": "ATIVAR 43"
  }
}

Caso de uso

Ativar uma campanha finalizada e revisada. O fluxo de duas etapas garante que o usuario viu o resumo e confirmou deliberadamente.

Permissao: Send

Pausa uma campanha ativa da instancia. A retomada deve ser feita pelo dono no dashboard.

Parametros

Exemplo de chamada

{
  "name": "dexter_campaigns_pause",
  "arguments": {
    "campaign_id": 42
  }
}

Exemplo de resposta

{
  "paused": true,
  "campaignId": 42
}

Caso de uso

Interromper rapidamente uma campanha em andamento — por exemplo, se o conteudo precisa de correcao ou se o volume de respostas esta alto demais.

Permissao: Write

Verifica se a instancia tem Google Agenda configurada e acessivel. Nao retorna tokens ou credenciais.

Parametros

Exemplo de chamada

{
  "name": "dexter_calendar_status",
  "arguments": {}
}

Exemplo de resposta

{
  "configured": true,
  "skillEnabled": true,
  "instanceCredentials": true,
  "reachable": true,
  "timezone": "America/Sao_Paulo",
  "calendarId": "primary"
}

Caso de uso

Verificar se a agenda esta configurada antes de tentar agendar ou consultar horarios.

Permissao: Read

Retorna as janelas ocupadas da agenda Google num intervalo de datas, usando o mesmo free/busy do Dexter.

Parametros

Exemplo de chamada

{
  "name": "dexter_calendar_freebusy",
  "arguments": {
    "time_min": "2025-01-20T09:00:00-03:00",
    "time_max": "2025-01-20T18:00:00-03:00"
  }
}

Exemplo de resposta

{
  "busy": [
    { "start": "2025-01-20T10:00:00-03:00", "end": "2025-01-20T11:00:00-03:00" },
    { "start": "2025-01-20T14:00:00-03:00", "end": "2025-01-20T15:00:00-03:00" }
  ]
}

Caso de uso

Consultar janelas ocupadas antes de sugerir horarios ao lead, ou verificar disponibilidade em um dia especifico.

Permissao: Read

Lista horarios livres na agenda nos proximos dias uteis, em slots de 45 minutos. Nao cria eventos.

Parametros

Exemplo de chamada

{
  "name": "dexter_calendar_slots",
  "arguments": {
    "later": false
  }
}

Exemplo de resposta

{
  "slots": [
    {
      "start": "2025-01-21T09:00:00-03:00",
      "end": "2025-01-21T09:45:00-03:00",
      "label": "Ter 21/01 09:00-09:45"
    },
    {
      "start": "2025-01-21T11:00:00-03:00",
      "end": "2025-01-21T11:45:00-03:00",
      "label": "Ter 21/01 11:00-11:45"
    }
  ],
  "durationMin": 45
}

Caso de uso

Apresentar opcoes de horario ao lead para agendamento de reuniao, sem necessidade de consultar free/busy manualmente.

Permissao: Read

Cria um evento na Google Agenda e devolve o link do Google Meet. Nao envia mensagem no WhatsApp.

Parametros

Exemplo de chamada

{
  "name": "dexter_calendar_book",
  "arguments": {
    "confirm_booking": true,
    "start": "2025-01-21T09:00:00-03:00",
    "end": "2025-01-21T09:45:00-03:00",
    "summary": "Reuniao de demonstracao - Acme Ltda",
    "attendee_email": "maria@acme.com.br",
    "phone": "5511999990001",
    "description": "Demo do Dexter com Maria Souza"
  }
}

Exemplo de resposta

{
  "booked": true,
  "link": "https://meet.google.com/abc-defg-hij",
  "email": "maria@acme.com.br",
  "phone": "5511999990001"
}

Caso de uso

Agendar reunioes de demonstracao ou follow-up com leads qualificados, diretamente na agenda da equipe.

Permissao: Send

Envia uma mensagem de WhatsApp para um contato. Acao de alto impacto: exige a permissao "Permitir envio de mensagens" habilitada na secao MCP da tela Integracoes.

Parametros

Exemplo de chamada

{
  "name": "dexter_messages_send",
  "arguments": {
    "phone": "5511999990001",
    "message": "Ola Maria! Segue o link da proposta conforme combinado.",
    "delay_typing": 5
  }
}

Exemplo de resposta

{
  "sent": true,
  "phone": "5511999990001",
  "status": 200,
  "typing_sec": 5
}

Caso de uso

Enviar mensagem pontual a um contato — follow-up manual, resposta a solicitacao, envio de link ou documento.

Permissao: Send

Visao geral da operacao: total de contatos, campanhas por status e volume de mensagens enviadas e recebidas no periodo.

Parametros

Exemplo de chamada

{
  "name": "dexter_analytics_overview",
  "arguments": {
    "days": 30
  }
}

Exemplo de resposta

{
  "days": 30,
  "contactsTotal": 245,
  "campaignsByStatus": {
    "active": 2,
    "finished": 5,
    "draft": 1,
    "paused": 1
  },
  "messagesInbound": 1230,
  "messagesOutbound": 980,
  "conversationsWithActivity": 87
}

Caso de uso

Gerar relatorio executivo da operacao, monitorar volume de mensagens ou acompanhar a evolucao da base de contatos.

Permissao: Read

Lista os agentes de IA configurados na instancia (SDR, CS e Onboarding) com nome, funcao e objetivo.

Parametros

Exemplo de chamada

{
  "name": "dexter_agents_list",
  "arguments": {}
}

Exemplo de resposta

{
  "agents": [
    {
      "id": "sdr",
      "name": "SDR (DM)",
      "role": "pre-vendas",
      "goal": "Tirar duvidas, qualificar e encaminhar para reuniao.",
      "personality": "Proativo, consultivo e direto"
    },
    {
      "id": "cs",
      "name": "CS (Grupo)",
      "role": "suporte",
      "goal": "Suporte para clientes ativos em grupos.",
      "personality": ""
    },
    {
      "id": "onboarding",
      "name": "Onboarding (DM)",
      "role": "implantacao",
      "goal": "Acompanhamento e checklist de implantacao.",
      "personality": ""
    }
  ]
}

Caso de uso

Verificar quais agentes estao configurados, seus nomes personalizados e funcoes antes de atribuir contatos.

Permissao: Read

Lista a fila de trabalho do Dexter Expediente: leads parados, follow-ups aguardando aprovacao, itens executados e dispensados.

Parametros

Exemplo de chamada

{
  "name": "dexter_work_queue_list",
  "arguments": {
    "status": "pending",
    "limit": 10
  }
}

Exemplo de resposta

{
  "items": [
    {
      "id": 101,
      "kind": "stale_lead_followup",
      "kindLabel": "Follow-up de lead parado",
      "phone": "5511988880001",
      "title": "Maria sem resposta ha 5 dias",
      "evidence": "Ultima msg: 'Fico no aguardo' (5d atras)",
      "draft": "Ola Maria, tudo bem? Gostaria de retomar nossa conversa...",
      "status": "pending",
      "execMode": "",
      "createdAtMs": 1719300000000,
      "executedAtMs": null
    }
  ],
  "count": 1
}

Caso de uso

Verificar itens pendentes na fila antes de aprovar ou dispensar, monitorar o que ja foi executado ou revisar itens que falharam.

Permissao: Read

Aprova e executa um item pendente da fila do Expediente — envia o follow-up rascunhado ao lead. Acao de alto impacto: exige permissao de envio.

Parametros

Exemplo de chamada

{
  "name": "dexter_work_queue_approve",
  "arguments": {
    "item_id": 101
  }
}

Exemplo de resposta

{
  "executed": true,
  "itemId": 101,
  "summary": "Mensagem enviada para 5511988880001"
}

Caso de uso

Aprovar follow-ups sugeridos pelo Dexter Expediente. Opcionalmente, editar o rascunho antes de enviar passando o parametro message.

Permissao: Send

Descarta um item pendente da fila do Expediente. O item nao volta a ser sugerido por alguns dias.

Parametros

Exemplo de chamada

{
  "name": "dexter_work_queue_dismiss",
  "arguments": {
    "item_id": 102
  }
}

Exemplo de resposta

{
  "dismissed": true,
  "itemId": 102
}

Caso de uso

Descartar follow-ups que nao fazem sentido no momento — por exemplo, leads que ja responderam por outro canal ou que nao sao prioridade.

Permissao: Write

Todas as tools do conector MCP respeitam os mesmos guardrails de seguranca do Dexter: