# API REST

> Source: https://eesier.com.br/rest

A API REST do eesier é uma API JSON em `https://mcp.eesier.com` que expõe as mesmas 202 ferramentas do servidor MCP. Toda rota recebe um token e devolve JSON.

- **Endereço base**: `https://mcp.eesier.com/rest/v1`
- **Autenticação**: `Authorization: Bearer <token>`
- **Content type**: `application/json`
- **Obter um token**: Console do eesier → Conta → Agentes Externos (MCP) → Gerar Token. O mesmo token serve para o MCP; revogar derruba os dois.

## Primeira chamada

```bash
curl https://mcp.eesier.com/rest/v1/call/whoami \
  -H "Authorization: Bearer $EESIER_TOKEN"
```

## chamando uma ferramenta

### Executar uma ferramenta

```bash
curl -X POST https://mcp.eesier.com/rest/v1/tools/search_leads \
  -H "Authorization: Bearer $EESIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "Interested", "page_size": 5}'
```

Todo o resto é um POST com um objeto JSON de parâmetros nomeados.

### Descobrir todas as ferramentas

```bash
curl https://mcp.eesier.com/rest/v1/tools \
  -H "Authorization: Bearer $EESIER_TOKEN"
```

A versão legível por máquina desta página, direto do servidor em execução.

Uma ferramenta sem parâmetros não precisa de corpo nenhum — corpo ausente, {} e null significam a mesma coisa: sem argumentos.

## os endpoints

| | | |
|---|---|---|
| `POST` | `/rest/v1/tools/{tool_name}` | Executa uma ferramenta. O corpo é um objeto JSON de parâmetros nomeados. |
| `GET` | `/rest/v1/call/{tool_name}` | Executa uma ferramenta de leitura pela query string. Qualquer outra devolve 405. |
| `GET` | `/rest/v1/tools` | O catálogo completo: { version, server_version, tool_count, tools[] }. |
| `GET` | `/rest/v1/tools/{tool_name}` | O schema de uma ferramenta — o mesmo objeto que o catálogo lista. |

## respostas

**O status diz o que aconteceu** — Uma chamada que deu certo responde **200** com o JSON da própria ferramenta. Uma que falhou responde um **4xx ou 5xx** de verdade — e o corpo continua sendo o JSON da ferramenta, então você tem o motivo legível por máquina e um status em que o seu cliente HTTP pode decidir sem interpretar nada.

- `200` — A ferramenta rodou e deu certo. O JSON dela é o corpo.
- `400` — A requisição nem chegou na ferramenta: JSON malformado, corpo que não é objeto, parâmetro desconhecido, obrigatório ausente ou valor que não converte.
- `401` — Token ausente, malformado, expirado ou revogado.
- `403` — A ferramenta existe, mas o seu plano não inclui ela. O corpo diz o que ativar.
- `404` — Não existe ferramenta com esse nome — o corpo sugere a mais próxima — ou a ferramenta rodou e o lead, a campanha ou o site que você pediu não existe.
- `405` — Verbo errado — quase sempre um GET em uma ferramenta que não é de leitura.
- `422` — A ferramenta rodou e recusou a requisição pelos critérios dela. O corpo diz o porquê.
- `500` — A ferramenta lançou um erro permanente para esses argumentos. Não repita a mesma chamada.
- `503` — A ferramenta lançou um erro transitório de plataforma ou de serviço externo. Repita a mesma chamada em alguns segundos.

Todo 4xx e 5xx traz os mesmos três campos, então um único trecho de código no cliente dá conta de todos:

```json
{
  "error": "unknown parameter 'lead_ids' for tool 'get_lead'",
  "type": "UnknownParameter",
  "detail": "accepted parameters: lead_id"
}
```

- `UnknownTool` — Esse nome de ferramenta não existe. Veja a sugestão em detail.
- `UnknownParameter` — Você mandou um parâmetro que a ferramenta não aceita — um erro de digitação é recusado, nunca ignorado.
- `MissingParameter` — Faltou um parâmetro obrigatório.
- `ParameterTypeMismatch` — O valor não pode ser convertido para o tipo do parâmetro.
- `InvalidRequestBody` — O corpo é JSON válido, mas não é um objeto de parâmetros nomeados.
- `NotReadOnly` — Você tentou chamar por GET uma ferramenta que escreve. Use POST.
- `JsonException` — O corpo não é JSON válido.

Token ausente ou inválido devolve 401 com um corpo que diz o que fazer:

```json
{
  "error": "...",
  "how_to_fix": "...",
  "documentation": "https://mcp.eesier.com/SKILL.md"
}
```

## como os valores são lidos

Nada que perderia informação é adivinhado — é recusado.

- **string** — O texto vai literal. Um número ou booleano JSON chega como o literal dele. Objetos e listas são recusados — nenhum parâmetro aceita.
- **integer** — Um número JSON ou a forma textual dele. Um valor fracionário como 3.7, ou fora da faixa, é recusado — nunca truncado, nunca estourado.
- **number** — O separador decimal é '.', nunca ','. "1,5" falha alto, com um detail dizendo isso, em vez de virar 15 silenciosamente.
- **boolean** — Aceita true/false, "true"/"false", 1/0 e "1"/"0". "sim" é recusado.
- **Parâmetro desconhecido é recusado** — Mais rígido que o MCP de propósito: um parâmetro digitado errado e descartado em silêncio devolveria uma chamada bem-sucedida com resultado estranho. O 400 lista todos os nomes aceitos.
- **null e omissão são coisas diferentes** — Omita o parâmetro e vale o padrão da própria ferramenta. null explícito só é aceito por parâmetro que admite nulo. Query string não expressa null — use POST quando precisar.
- **Nomes diferenciam maiúsculas** — O despacho é exato, igual ao MCP. get_lead funciona; GET_LEAD devolve 404 com o nome certo em detail.
- **Datas em UTC ISO 8601** — Toda data volta como 2026-01-31T14:05:00Z. Os filtros aceitam datas ISO. Chame whoami para saber o fuso da conta.
- **Listas paginam explicitamente** — page começa em 0 e page_size vale 20 por padrão, com teto de 100. O total volta junto com as linhas.

## todos os endpoints

### Sessão

Identifica a conta conectada e lê as notificações pendentes. whoami é a primeira chamada de toda sessão — devolve o perfil, o plano e o fuso horário da conta.

#### `acknowledge_notification` (escrita)

Confirma o recebimento de uma notificação que você já exibiu ao usuário — ela deixa de aparecer em list_pending_notifications para você. Isso é apenas um marcador do lado do agente: a entrega da notificação ao usuário pela própria plataforma não é afetada.

- `POST /rest/v1/tools/acknowledge_notification`

| Parâmetros | | |
|---|---|---|
| `notification_id` | integer, obrigatório | ID da notificação (de list_pending_notifications) |

#### `list_notification_history` (leitura)

Lista as notificações do sistema passadas e pendentes do cliente (mais recentes primeiro, paginado) — incluindo aquelas já processadas pela plataforma ou já reconhecidas. Use list_pending_notifications para apenas as novas, ainda não vistas.

- `POST /rest/v1/tools/list_notification_history`
- `GET /rest/v1/call/list_notification_history`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Notificações por página (padrão 20, máximo 100) |

#### `list_pending_notifications` (leitura)

Lista todas as notificações do sistema pendentes (não processadas) na fila para o cliente. Estas são mensagens de aviso que a plataforma quer que o usuário veja — atualizações da plataforma ou confirmações de ações que ainda não foram apresentadas. Apresente-as ao usuário; você não pode marcá-las como processadas — elas permanecem na fila até que a plataforma as limpe internamente. Ordenadas pelas mais antigas primeiro. Depois de apresentar uma, chame acknowledge_notification para que ela pare de reaparecer aqui; para notificações passadas use list_notification_history.

- `POST /rest/v1/tools/list_pending_notifications`
- `GET /rest/v1/call/list_pending_notifications`

Parâmetros: —

#### `whoami` (leitura)

Retorna as informações de perfil do cliente autenticado, incluindo nome, telefone, e-mail, idioma, deslocamento de fuso horário em relação ao UTC (em horas, pode ser nulo se não estiver definido), plano de assinatura e elegibilidade para prospecção.

- `POST /rest/v1/tools/whoami`
- `GET /rest/v1/call/whoami`

Parâmetros: —

### Leads

Busca, lê, cadastra e atualiza leads. Assume um lead do agente, devolve para ele, interrompe, ou lista tudo que está esperando por uma pessoa agora.

#### `get_lead` (leitura)

Obtém o perfil completo de um lead, incluindo informações de contato, dados da empresa, status de prospecção e histórico de conversas. Os corpos das threads de e-mail são incluídos inline (últimos 50 por direção); a atividade de WhatsApp e voz aparece como contagens — use get_lead_conversation para a linha do tempo completa e mesclada entre canais.

- `POST /rest/v1/tools/get_lead`
- `GET /rest/v1/call/get_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `list_lead_emails` (leitura)

Lista os e-mails trocados com um lead específico (enviados e recebidos), mais antigos primeiro. Paginado — outbound_total/inbound_total informam o tamanho total da thread. Defina include_bodies=false para uma visualização leve, somente com metadados (datas, assuntos, nomes de anexos).

- `POST /rest/v1/tools/list_lead_emails`
- `GET /rest/v1/call/list_lead_emails`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | E-mails por direção por página (padrão 20, máximo 100) |
| `include_bodies` | boolean, opcional, padrão `true` | Incluir o corpo completo dos e-mails (padrão true); false retorna apenas metadados |

#### `list_pending_review` (leitura)

Lista os leads que foram sinalizados para revisão humana pelo agente de prospecção.

- `POST /rest/v1/tools/list_pending_review`
- `GET /rest/v1/call/list_pending_review`

Parâmetros: —

#### `register_lead` (escrita)

Registra manualmente um novo lead para que o Blue Button possa prospectá-lo. É necessário um e-mail válido para que o lead seja efetivamente contatado (apenas o telefone só habilita WhatsApp/voz). Faz deduplicação: se já existir um lead com o mesmo e-mail ou telefone, retorna o id desse lead em vez de criar um duplicado. Para trazer muitos leads de uma vez, use import_leads; para um lead indicado por outro lead, use register_referral_lead.

- `POST /rest/v1/tools/register_lead`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome do contato |
| `email` | string, opcional | Endereço de email |
| `phone` | string, opcional | Número de telefone |
| `company` | string, opcional | Nome da empresa |
| `status` | string, opcional | Status inicial: Cold (padrão) ou Confirmed |
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico para atribuir ao lead |

#### `return_lead_to_pipeline` (escrita)

Retorna um lead ao pipeline autônomo de prospecção com instruções opcionais para o próximo contato.

- `POST /rest/v1/tools/return_lead_to_pipeline`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `instructions` | string, opcional | Instruções para o próximo contato do agente |
| `next_touch_date` | string, opcional | Quando fazer o próximo contato (data ISO, padrão: agora) |

#### `search_leads` (leitura)

Busca leads por consulta, status, campanha, intervalo de datas, ou data da última mensagem de prospecção. Oferece suporte a ordenação por date_created (padrão), last_prospecting_message, ou status. Retorna resultados paginados. Cada resultado inclui last_outbound_at (data da última mensagem enviada para este lead) e last_inbound_at (data da última resposta deste lead) para que você possa triar a atividade sem abrir a conversa.

- `POST /rest/v1/tools/search_leads`
- `GET /rest/v1/call/search_leads`

| Parâmetros | | |
|---|---|---|
| `query` | string, opcional | Consulta de busca (corresponde a nome, nome da empresa, email) |
| `status` | string, opcional | Filtrar por status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Frozen, Closed, Unqualified, Rejected, Gatekeeper |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico |
| `created_after` | string, opcional | Somente leads criados nesta data ou depois (formato ISO, ex.: 2026-01-01) |
| `created_before` | string, opcional | Somente leads criados nesta data ou antes (formato ISO, ex.: 2026-03-31) |
| `last_prospecting_message_after` | string, opcional | Somente leads que receberam uma mensagem de prospecção nesta data ou depois (formato ISO) |
| `sort_by` | string, opcional | Ordem de classificação: date_created (padrão, mais recentes primeiro), last_prospecting_message (atividade mais recente primeiro), status (por status e depois por data). Valores não reconhecidos usam date_created como padrão. |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |
| `has_linkedin` | boolean, opcional | Filtrar pela presença no LinkedIn: true retorna apenas leads que têm uma URL de perfil do LinkedIn, false apenas leads sem uma. Omita para todos os leads. |

#### `send_message_to_lead` (escrita)

Envia um e-mail direto para um lead a partir do endereço Blue Button do cliente. EFEITO COLATERAL: isso assume o controle do lead (remove-o do pipeline autônomo, o mesmo que take_over_lead) — o cliente passa a ser o dono da conversa a partir daí. O e-mail é colocado na fila para envio, não é enviado instantaneamente. Se o cliente só quiser direcionar a abordagem sem assumir o controle, use return_lead_to_pipeline com instruções em vez disso. Para WhatsApp, use send_whatsapp_message_to_lead.

- `POST /rest/v1/tools/send_message_to_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `subject` | string, obrigatório | Assunto do email |
| `body` | string, obrigatório | Corpo do email |

#### `stop_lead` (destrutiva)

Para a prospecção de um lead — o Blue Button finaliza o lead e não envia mais nada. Reversível: recover_lead_to_pipeline devolve o lead ao pipeline com uma abordagem de reengajamento. Contraste: take_over_lead significa que o cliente vai cuidar pessoalmente do lead; stop_lead significa que ninguém vai cuidar. Para registrar POR QUÊ (ganho/perdido/desistiu, valor do negócio) use register_lead_outcome em vez disso — ele para a prospecção E mantém o histórico do resultado.

- `POST /rest/v1/tools/stop_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `reason` | string, opcional | Motivo da interrupção |

#### `take_over_lead` (escrita)

Assume o controle de um lead — marca como controlado pelo usuário, removendo-o do pipeline de prospecção autônoma (o Blue Button para de entrar em contato; o cliente passa a lidar com ele pelos próprios canais). Para devolver o lead ao Blue Button depois, use recover_lead_to_pipeline (reengajamento suave). Contraste: stop_lead encerra a prospecção sem implicar que o cliente vai cuidar do lead; send_message_to_lead também assume o controle como efeito colateral; return_lead_to_pipeline é a retomada pós-revisão-humana.

- `POST /rest/v1/tools/take_over_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `update_lead` (escrita)

Atualiza o status, objetivo ou histórico de um lead. Passe apenas os campos que deseja alterar. Observação: definir um status aqui NÃO para nem pausa a prospecção — para remover o lead do pipeline, use stop_lead (finaliza permanentemente) ou take_over_lead (o cliente cuida pessoalmente).

- `POST /rest/v1/tools/update_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `status` | string, opcional | Novo status: Pending, Cold, Confirmed, Aware, NotInterested, Interested, Frozen, Closed, Unqualified, Rejected, Gatekeeper |
| `goal` | string, opcional | Objetivo de prospecção específico do lead |
| `background` | string, opcional | Contexto de background sobre este lead |

### Operações de lead

Age sobre um lead: envia mensagem de WhatsApp, importa uma lista, reagenda o próximo contato, registra uma indicação ou gera uma apresentação para um lead específico.

#### `create_lead_presentation` (escrita)

Gera uma apresentação estratégica personalizada (PDF) para um lead específico, com base no negócio do cliente e no contexto do lead. É executado de forma síncrona e pode levar um minuto. Retorna a URL do PDF. Se o lead já tiver uma apresentação, retorna a existente. Respeita a opção 'generate custom presentations' do cliente/campanha.

- `POST /rest/v1/tools/create_lead_presentation`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

#### `import_leads` (escrita)

Importe muitos leads de uma vez. Forneça um customer_file_id existente (um arquivo CSV/Excel/TXT enviado) OU linhas inline (rows_json: um array JSON de objetos com name, email, phone, company — email ou phone obrigatório por linha). A importação é enfileirada e processada em segundo plano (deduplicada contra leads existentes); novos leads entram na prospecção automaticamente. Para um único lead, use register_lead.

- `POST /rest/v1/tools/import_leads`

| Parâmetros | | |
|---|---|---|
| `customer_file_id` | integer, opcional | Id de um arquivo do cliente já enviado (.csv, .xlsx, .xls, .txt) para importar |
| `rows_json` | string, opcional | Leads embutidos como um array JSON, ex.: [{"name":"Ana","email":"ana@acme.com","phone":"+5511999999999","company":"Acme"}]. Máximo de 500 linhas por chamada. |
| `instructions` | string, opcional | Instruções especiais para extração (mapeamento de colunas, filtros) |
| `status` | string, opcional | Status inicial para os leads importados (ex.: Cold, Confirmed) |
| `preferred_channel` | string, opcional | Canal de primeiro contato: Email ou WhatsApp (aplicado por lead somente quando ele tiver essa informação de contato) |
| `first_message_instructions` | string, opcional | Instruções para a primeira mensagem de prospecção aos leads importados |
| `prospecting_background` | string, opcional | Contexto sobre os leads importados (ex.: 'Leads do workshop de IA da TechConf 2026') |
| `prospecting_goal` | string, opcional | Objetivo de prospecção para os leads importados, substituindo o objetivo em nível de cliente |
| `campaign` | string, opcional | Nome da campanha ou campaign_id numérico para atribuir aos leads importados |

#### `register_referral_lead` (escrita)

Registra um NOVO lead indicado por um lead existente ('fale com o X'). Passa pelo pipeline compartilhado de indicações: deduplicação, verificação de e-mail, cópia de dados da empresa quando same_company, enriquecimento e entrada automática na prospecção. Precisa de pelo menos um e-mail ou um telefone para a pessoa indicada. Requer um plano pago ativo.

- `POST /rest/v1/tools/register_referral_lead`

| Parâmetros | | |
|---|---|---|
| `referring_lead_id` | integer, obrigatório | ID do lead existente que fez a indicação |
| `lead_name` | string, obrigatório | Nome da pessoa indicada |
| `lead_email` | string, opcional | Email da pessoa indicada |
| `lead_phone` | string, opcional | Telefone da pessoa indicada |
| `same_company` | boolean, opcional, padrão `false` | True quando a pessoa indicada trabalha na MESMA empresa que o lead que fez a indicação (os dados da empresa são copiados) |
| `status` | string, opcional | Status inicial (ex.: Cold, Confirmed) |
| `instructions_for_first_touch` | string, opcional | Instruções para o primeiro contato com o lead indicado |

#### `reschedule_lead_touch` (escrita)

Atualiza a data do próximo contato de prospecção e/ou o canal preferido para um ou mais leads em prospecção ativa, selecionados por IDs de lead explícitos e/ou pelo arquivo do qual foram importados. Definir next_touch_date como agora faz com que cada lead seja contatado o quanto antes. Leads que a fila de prospecção não pegaria (nunca iniciados, finalizados, aguardando revisão, assumidos, rejeitados, ou congelados sem uma resposta mais recente) são ignorados e reportados.

- `POST /rest/v1/tools/reschedule_lead_touch`

| Parâmetros | | |
|---|---|---|
| `lead_ids` | string, opcional | IDs de leads separados por vírgula para atualizar (opcional se imported_from_file_id for fornecido) |
| `imported_from_file_id` | integer, opcional | Atualiza todo lead em prospecção ativa importado deste id de arquivo do cliente |
| `next_touch_date` | string, opcional | Nova data/hora do próximo contato em UTC (formato ISO). Informe a hora UTC atual para contatar o quanto antes. Omita para manter o agendamento de cada lead. |
| `preferred_channel` | string, opcional | Novo canal preferido de primeiro contato: Email ou WhatsApp (aplicado apenas onde o lead for alcançável nesse canal) |

#### `send_whatsapp_message_to_lead` (escrita)

Envia uma mensagem de WhatsApp direta para um lead no número de prospecção do cliente. O comportamento espelha o do agente no aplicativo: se o controle do lead NÃO foi assumido, a mensagem fica reservada como instruções para o próximo contato e é entregue no próximo contato natural de prospecção do lead (o controle do lead NÃO é assumido). Se o controle do lead FOI assumido e sua janela de atendimento de WhatsApp de 24h está aberta (o lead enviou mensagem nas últimas 24h), a mensagem é enviada agora, ao pé da letra; se a janela estiver fechada, o envio é recusado (política do WhatsApp) — use e-mail via send_message_to_lead em vez disso. Requer uma linha de WhatsApp de prospecção ativa (register_whatsapp_line).

- `POST /rest/v1/tools/send_whatsapp_message_to_lead`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `message` | string, obrigatório | A mensagem a ser entregue, escrita exatamente como deve chegar ao lead |
| `attachment_url` | string, opcional | URL https absoluta opcional de um arquivo para enviar como mensagem de mídia do WhatsApp após o texto |

### Desfechos

Fecha o ciclo: registra o que aconteceu com um lead, responde a uma pergunta que ele fez, recupera ele para o pipeline ou lê o histórico do seu ciclo de vida.

#### `answer_lead_question` (escrita)

Salva a resposta do cliente para uma pergunta que um lead fez anteriormente e que a plataforma não conseguiu responder (preço, área de entrega, especificações, processo...). A resposta é armazenada no FAQ do negócio, para que TODO lead futuro a receba, e, se o lead que perguntou ainda estiver no pipeline, a resposta é repassada no próximo contato. Informe open_question_id quando conhecido; caso contrário, informe question_text.

- `POST /rest/v1/tools/answer_lead_question`

| Parâmetros | | |
|---|---|---|
| `answer_text` | string, obrigatório | A resposta do cliente, em suas próprias palavras |
| `open_question_id` | integer, opcional | ID da pergunta em aberto que está sendo respondida, quando conhecido |
| `question_text` | string, opcional | O texto da pergunta — obrigatório quando nenhum open_question_id for fornecido |

#### `list_lead_lifecycle_events` (leitura)

Lista o histórico de ciclo de vida/desfecho de um lead específico (desfecho registrado, recuperado, check-ins silenciados, perguntas respondidas, desfechos de reuniões...), mais recentes primeiro. A trilha de auditoria somente-acréscimo por trás de register_lead_outcome e suas irmãs.

- `POST /rest/v1/tools/list_lead_lifecycle_events`
- `GET /rest/v1/call/list_lead_lifecycle_events`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `limit` | integer, opcional, padrão `50` | Número máximo de eventos a retornar (padrão 50, máximo 200) |

#### `mute_lead_check_ins` (escrita)

Interrompe as perguntas periódicas de acompanhamento do tipo 'como foi com esse lead?' para um lead específico, quando o cliente pede para não ser mais lembrado sobre ele. NÃO altera o status do lead nem o estado do pipeline.

- `POST /rest/v1/tools/mute_lead_check_ins`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `reason` | string, opcional | Por que o cliente quer parar de ouvir falar sobre este lead, com as próprias palavras |

#### `recover_lead_to_pipeline` (escrita)

Traz DE VOLTA para o pipeline autônomo de prospecção um lead que o cliente havia assumido pessoalmente (ou desistido), com um enquadramento de reengajamento suave (o lead já conhece o negócio). Use esta ferramenta — e NÃO return_lead_to_pipeline — quando o cliente assumiu PESSOALMENTE o lead ou parou de buscá-lo e agora quer que o Blue Button o retome. Recusa leads descadastrados e leads com um resultado won/lost já registrado. O primeiro contato de reengajamento acontece após um pequeno atraso.

- `POST /rest/v1/tools/recover_lead_to_pipeline`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `owner_context` | string, opcional | Contexto que o cliente deu para a recuperação, com as próprias palavras (ex.: 'ele pediu para conversar depois das férias') |

#### `register_lead_outcome` (escrita)

Registra o resultado FINAL de um lead, conforme relatado pelo cliente: 'won' (fechou a venda), 'lost' (concorrente, desistiu, sem orçamento) ou 'gave_up' (o cliente não vai mais buscar esse lead). Use para QUALQUER atualização sobre como a história de um lead terminou — incluindo anúncios positivos casuais ('fechei com o X'). Também interrompe a prospecção desse lead. Só informe reason/deal_value_brl quando o cliente os fornecer espontaneamente — NUNCA pergunte pelo valor do negócio. Contraste: stop_lead encerra a prospecção sem registrar o motivo; esta mantém o histórico do resultado.

- `POST /rest/v1/tools/register_lead_outcome`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `outcome` | string, obrigatório | O resultado: 'won', 'lost' ou 'gave_up' |
| `reason` | string, opcional | As próprias palavras do cliente sobre o porquê/como terminou — apenas quando mencionado espontaneamente |
| `deal_value_brl` | number, opcional | Valor do negócio em BRL — APENAS quando o cliente mencionou explicitamente um valor |

### Reuniões

Lista as reuniões marcadas com leads, confirma ou cancela, e registra quem realmente compareceu.

#### `cancel_lead_meeting` (destrutiva)

Cancela uma reunião do lado do cliente e envia o lead de volta ao pipeline de prospecção, para que o executor comunique o cancelamento no próximo contato.

- `POST /rest/v1/tools/cancel_lead_meeting`

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião a ser cancelada |
| `next_touch_date` | string, obrigatório | Quando o executor deve reengajar o lead sobre o cancelamento (ISO 8601 UTC, geralmente dentro de algumas horas) |
| `reason` | string, opcional | Motivo de cancelamento opcional — anexado às notas da reunião e incluído nas instruções de próximo contato |
| `additional_instructions` | string, opcional | Instruções extras opcionais de próximo contato para o executor, escritas no idioma do cliente |

#### `confirm_lead_meeting` (escrita)

Confirma uma reunião do lado do cliente (chame quando o cliente aceitar uma reunião proposta pelo lead). Registra a aceitação do cliente.

- `POST /rest/v1/tools/confirm_lead_meeting`

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião que o cliente está confirmando |

#### `list_lead_meetings` (leitura)

Lista as reuniões entre o cliente e seus leads. Opcionalmente, filtre por um lead específico, inclua reuniões canceladas, ou inclua reuniões passadas.

- `POST /rest/v1/tools/list_lead_meetings`
- `GET /rest/v1/call/list_lead_meetings`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, opcional | ID do lead opcional para filtrar |
| `include_cancelled` | boolean, opcional, padrão `false` | Incluir reuniões canceladas (padrão false) |
| `include_past` | boolean, opcional, padrão `true` | Incluir reuniões passadas dos últimos 30 dias (padrão true). Defina false para somente as futuras. |

#### `update_lead_meeting_attendance` (escrita)

Registra a presença em uma reunião que já aconteceu — se o cliente e/ou o lead compareceram, além de notas de resultado opcionais. Passe pelo menos um campo.

- `POST /rest/v1/tools/update_lead_meeting_attendance`

| Parâmetros | | |
|---|---|---|
| `meeting_id` | integer, obrigatório | Id da reunião a ser atualizada |
| `has_customer_attended` | boolean, opcional | Se o cliente compareceu |
| `has_lead_attended` | boolean, opcional | Se o lead compareceu |
| `notes` | string, opcional | Notas opcionais sobre o resultado — anexadas às notas existentes |

### Inteligência de timing

Lê os sinais de timing coletados para um lead — quando esse tipo de contato costuma responder.

#### `get_lead_timing_intelligence` (leitura)

Obtém a inteligência de timing de um lead: os melhores horários para contatá-lo (por dia da semana, no horário local do lead), quando o lead historicamente responde, e o tempo médio de resposta dele. Construído a partir do histórico deste lead, recorrendo ao setor dele, a este cliente, e depois aos dados de toda a plataforma (o campo source indica qual). Use isso para cronometrar os toques de send_message_to_lead / return_lead_to_pipeline.

- `POST /rest/v1/tools/get_lead_timing_intelligence`
- `GET /rest/v1/call/get_lead_timing_intelligence`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |

### Conversas

Lê o que foi realmente dito. Linha do tempo completa de um lead em todos os canais, a thread de WhatsApp isolada, ou uma busca por significado em todas as conversas de uma vez.

#### `get_lead_conversation` (leitura)

Obtém a linha do tempo completa da conversa de um lead entre canais — e-mail, WhatsApp e chamadas de voz — mesclada cronologicamente, com cada item marcado com seu canal e direção. Paginado. Esta é a única ferramenta que mostra a conversa INTEIRA como o lead a vivenciou; para um único canal, use list_lead_emails ou list_lead_whatsapp_messages.

- `POST /rest/v1/tools/get_lead_conversation`
- `GET /rest/v1/call/get_lead_conversation`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `30` | Itens por página (padrão 30, máximo 100) |
| `order` | string, opcional, padrão `newest_first` | Ordenação: newest_first (padrão) ou oldest_first |
| `include_transcripts` | boolean, opcional, padrão `false` | Incluir transcrições completas das chamadas de voz (padrão false — apenas o resumo do resultado) |

#### `list_lead_whatsapp_messages` (leitura)

Lista as mensagens do WhatsApp trocadas com um lead específico (enviadas e recebidas), mais antigas primeiro. Paginado — outbound_total/inbound_total informam o tamanho total da thread. Defina include_bodies=false para uma visualização leve, somente com metadados. Para os e-mails do lead use list_lead_emails; para a linha do tempo combinada de e-mail+WhatsApp+voz use get_lead_conversation.

- `POST /rest/v1/tools/list_lead_whatsapp_messages`
- `GET /rest/v1/call/list_lead_whatsapp_messages`

| Parâmetros | | |
|---|---|---|
| `lead_id` | integer, obrigatório | ID do lead |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Mensagens por direção por página (padrão 20, máximo 100) |
| `include_bodies` | boolean, opcional, padrão `true` | Incluir o corpo completo das mensagens (padrão true); false retorna apenas metadados |

#### `search_lead_conversations` (leitura)

Busca semântica em TODAS as conversas de LEAD do cliente — e-mails de leads e mensagens de WhatsApp de leads — por significado, não por palavras-chave (ex.: 'leads que perguntaram sobre preço', 'objeções sobre duração de contrato'). Retorna trechos com lead_id; busque as conversas completas via get_lead_conversation / list_lead_emails / list_lead_whatsapp_messages. Opcionalmente, restrinja a um lead ou um canal. NÃO é para o próprio chat do cliente com seu agente Blue Button — isso é search_my_agent_conversation.

- `POST /rest/v1/tools/search_lead_conversations`
- `GET /rest/v1/call/search_lead_conversations`

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | O que buscar, formulado por significado (qualquer idioma) |
| `lead_id` | integer, opcional | Restringir à conversa de um lead (opcional) |
| `channel` | string, opcional | Restringir canal: email, whatsapp, email_inbound, email_outbound, whatsapp_inbound, whatsapp_outbound (opcional; padrão = todos) |
| `top_k` | integer, opcional, padrão `10` | Máximo de resultados (padrão 10, máximo 25) |
| `min_score` | number, opcional | Pontuação mínima de similaridade 0..1 (opcional) |

#### `search_my_agent_conversation` (leitura)

Busca semântica na PRÓPRIA conversa passada do cliente com seu agente Blue Button (o assistente de WhatsApp com quem ele conversa) — use para lembrar o que o cliente discutiu, decidiu, ou pediu anteriormente. NÃO é para conversas de leads — isso é search_lead_conversations.

- `POST /rest/v1/tools/search_my_agent_conversation`
- `GET /rest/v1/call/search_my_agent_conversation`

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | O que buscar, formulado por significado (qualquer idioma) |
| `top_k` | integer, opcional, padrão `5` | Número máximo de resultados (padrão 5, máximo 10) |

### Campanhas

Roda trilhas de prospecção separadas para produtos ou mercados diferentes: cria, pausa, retoma, renomeia, arquiva, compara resultados e move leads entre elas.

#### `archive_campaign` (destrutiva)

Arquiva uma campanha permanentemente. Todo lead nela tem seu vínculo com a campanha removido e volta para a prospecção padrão, e a campanha deixa de aparecer nas listas de campanhas. Use pause_campaign para uma interrupção temporária.

- `POST /rest/v1/tools/archive_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `compare_campaigns` (leitura)

Compara duas campanhas lado a lado: configuração e estatísticas de leads.

- `POST /rest/v1/tools/compare_campaigns`
- `GET /rest/v1/call/compare_campaigns`

| Parâmetros | | |
|---|---|---|
| `name_a` | string, obrigatório | Nome da primeira campanha |
| `name_b` | string, obrigatório | Nome da segunda campanha |

#### `create_campaign` (escrita)

Cria uma nova campanha de prospecção. Name e business_name são obrigatórios. Cada campanha é ISOLADA — ela NÃO herda nenhum campo dos padrões em nível de cliente, portanto preencha todos os campos relevantes no momento da criação.

- `POST /rest/v1/tools/create_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha (único por cliente) |
| `business_name` | string, obrigatório | Nome do negócio para esta campanha |
| `business_description` | string, opcional | Descrição do negócio para esta campanha — o produto/serviço que ela representa. OBRIGATÓRIO quando a campanha representa um produto diferente do negócio principal do cliente, caso contrário o texto de prospecção não terá contexto sobre o produto. |
| `business_website` | string, opcional | URL do site do negócio para esta campanha |
| `icp` | string, opcional | Perfil de cliente ideal |
| `cnae_filter` | string, opcional | Códigos CNAE a incluir, separados por vírgula |
| `cnae_exclusion_filter` | string, opcional | Códigos CNAE a excluir, separados por vírgula |
| `instructions` | string, opcional | Instruções de prospecção |
| `email_instructions` | string, opcional | Sobreposição de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail para ESTA campanha, aplicada por cima das instruções gerais da campanha (substituição direta da sobreposição de e-mail). |
| `whatsapp_instructions` | string, opcional | Camada de instruções do canal do WhatsApp — orientações extras aplicadas SOMENTE ao contatar um lead pelo WhatsApp nesta campanha, sobrepostas às instruções gerais da campanha (substituição bruta da camada do WhatsApp). |
| `voice_instructions` | string, opcional | Camada de instruções do canal de voz — orientações extras aplicadas SOMENTE em ligações ativas desta campanha, sobrepostas às instruções gerais da campanha (substituição bruta da camada de voz). |
| `goal` | string, opcional | Objetivo de prospecção |
| `lead_qualification_instructions` | string, opcional | Instruções de qualificação de leads — regras sobre COMO avaliar leads em relação ao ICP (requisitos obrigatórios vs. preferências flexíveis, condições de override, regras de tolerância, limites de desqualificação) |
| `human_review_criteria` | string, opcional | Critérios de revisão humana — quando sinalizar um lead para revisão manual em vez de avançar automaticamente |
| `email_display_name` | string, opcional | Substituição do nome de exibição do e-mail para esta campanha (ex: 'Carlos from PrimeAssist'). Deixe em branco para usar o nome de exibição em nível de cliente. |
| `uf_filter` | string, opcional | Códigos de estados brasileiros separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Códigos de país ISO |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários |
| `max_employee_count` | integer, opcional | Número máximo de funcionários |
| `min_annual_revenue` | number, opcional | Receita anual mínima |
| `max_annual_revenue` | number, opcional | Receita anual máxima |
| `company_size_filter` | string, opcional | Portes de empresa separados por vírgula: Micro,Small,Medium,Large |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Vazio = herda o filtro de tipo de empresa do cliente (padrão do cliente = apenas Private — MEI / empresários individuais, governo, estatais e entidades sem fins lucrativos excluídos). |
| `lead_generation_active` | boolean, opcional | Se deve gerar automaticamente NOVOS leads para esta trilha. O padrão é true. Defina como false APENAS quando a campanha deve trabalhar SOMENTE com uma lista que o próprio usuário importa e nunca receber leads gerados automaticamente. Os leads existentes continuam sendo prospectados — apenas a aquisição de novos leads é pausada quando false. |

#### `get_campaign` (leitura)

Retorna a configuração completa e as estatísticas de leads de uma campanha específica. Aceita o nome da campanha ou seu campaign_id numérico (conforme retornado por list_campaigns, search_leads, get_lead).

- `POST /rest/v1/tools/get_campaign`
- `GET /rest/v1/call/get_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `list_campaigns` (leitura)

Lista todas as campanhas de prospecção do cliente com suas estatísticas de leads (total, interested, confirmed, cold, aware, frozen, not interested, taken over, pending review) e métricas de e-mail (e-mails enviados, respostas recebidas, taxa de resposta).

- `POST /rest/v1/tools/list_campaigns`
- `GET /rest/v1/call/list_campaigns`

Parâmetros: —

#### `move_leads_to_campaign` (escrita)

Move leads de uma campanha para outra, ou os remove de sua campanha e os retorna à prospecção padrão (sem campanha). Informe o nome da campanha de destino, ou 'default' para remover os leads de qualquer campanha. Opcionalmente, filtre por status do lead.

- `POST /rest/v1/tools/move_leads_to_campaign`

| Parâmetros | | |
|---|---|---|
| `target_campaign` | string, obrigatório | Nome da campanha de destino ou campaign_id numérico, ou 'default' (ou 'none') para remover os leads de sua campanha e devolvê-los à prospecção padrão |
| `lead_ids` | string, obrigatório | IDs de leads separados por vírgula para mover |
| `status_filter` | string, opcional | Mover apenas leads com este status (opcional) |

#### `pause_campaign` (escrita)

Pausa uma campanha. Os leads dessa campanha não serão processados até que ela seja retomada.

- `POST /rest/v1/tools/pause_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `rename_campaign` (escrita)

Renomeia uma campanha.

- `POST /rest/v1/tools/rename_campaign`

| Parâmetros | | |
|---|---|---|
| `old_name` | string, obrigatório | Nome atual da campanha |
| `new_name` | string, obrigatório | Novo nome da campanha |

#### `resume_campaign` (escrita)

Retoma uma campanha pausada.

- `POST /rest/v1/tools/resume_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |

#### `set_campaign_lead_generation_active` (escrita)

Alterna se o sistema GERA AUTOMATICAMENTE novos leads para uma campanha. true = gerar novos leads (padrão). false = parar de gerar novos leads — trabalhar apenas a lista existente. INDEPENDENTE de pausar/retomar: uma campanha com lead_generation_active=false mas is_active=true continua prospectando seus leads existentes, apenas sem aquisição de novos leads. Use isso quando o usuário quiser que uma campanha trabalhe APENAS em uma lista que ele mesmo importou.

- `POST /rest/v1/tools/set_campaign_lead_generation_active`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome da campanha ou campaign_id numérico |
| `active` | boolean, obrigatório | true para continuar gerando novos leads, false para parar de gerar novos leads (leads existentes continuam sendo prospectados) |

#### `update_campaign` (escrita)

Atualiza a configuração de uma campanha existente. Passe apenas os campos que deseja alterar. Para filtros numéricos (número de funcionários, receita), defina como -1 para limpar.

- `POST /rest/v1/tools/update_campaign`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | Nome atual da campanha |
| `business_name` | string, opcional | Novo nome do negócio |
| `business_description` | string, opcional | Descrição do negócio |
| `business_website` | string, opcional | Site do negócio |
| `icp` | string, opcional | Perfil de cliente ideal |
| `cnae_filter` | string, opcional | Filtro de inclusão de CNAE |
| `cnae_exclusion_filter` | string, opcional | Filtro de exclusão de CNAE |
| `uf_filter` | string, opcional | Códigos de estado brasileiros separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Filtro de país |
| `instructions` | string, opcional | Instruções de prospecção |
| `email_instructions` | string, opcional | Camada de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta da camada de e-mail). |
| `whatsapp_instructions` | string, opcional | Overlay de instruções do canal WhatsApp — orientação extra aplicada APENAS ao contatar um lead pelo WhatsApp para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta do overlay do WhatsApp). |
| `voice_instructions` | string, opcional | Overlay de instruções do canal de voz — orientação extra aplicada APENAS em chamadas outbound para ESTA campanha, sobreposta às instruções gerais da campanha (substituição bruta do overlay de voz). |
| `goal` | string, opcional | Objetivo de prospecção |
| `strategy` | string, opcional | Estratégia |
| `human_review_criteria` | string, opcional | Critérios de revisão humana |
| `lead_qualification_instructions` | string, opcional | Instruções de qualificação de leads — regras sobre COMO avaliar leads em relação ao ICP (requisitos obrigatórios vs. preferências flexíveis, condições de override, regras de flexibilidade, limiares de desqualificação) |
| `email_display_name` | string, opcional | Nome de exibição do e-mail |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários (-1 para limpar) |
| `max_employee_count` | integer, opcional | Número máximo de funcionários (-1 para limpar) |
| `min_annual_revenue` | number, opcional | Receita anual mínima (-1 para limpar) |
| `max_annual_revenue` | number, opcional | Receita anual máxima (-1 para limpar) |
| `company_size_filter` | string, opcional | Portes de empresa separados por vírgula: Micro,Small,Medium,Large (vazio para limpar) |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Uma string vazia limpa a substituição da campanha e herda o filtro de tipo de empresa do cliente (padrão do cliente = apenas Private — MEI / empresários individuais, governo, estatais e entidades sem fins lucrativos excluídos). |
| `lead_generation_active` | boolean, opcional | Se deve gerar automaticamente NOVOS leads para esta trilha. true = gerar novos leads (padrão para novas campanhas). false = parar de gerar novos leads, trabalhar apenas a lista existente. Independente de pause/resume — quando false a campanha continua prospectando seus leads existentes, apenas não adquire novos. |
| `is_active` | boolean, opcional | Se esta campanha está ou não em execução. false pausa toda a trilha (o mesmo que pause_campaign), true a retoma. |
| `voice_calling_active` | boolean, opcional | Chamada de voz outbound por trilha. true liga para os leads desta trilha, false nunca liga para eles, omitir para manter a configuração atual. Limpe para herdar a configuração de nível de cliente via clear_voice_calling_active. |
| `generate_custom_presentations` | boolean, opcional | Se deve gerar uma apresentação personalizada por lead para esta trilha (true/false) |
| `notify_on_interested` | boolean, opcional | Alertar quando um lead desta trilha demonstrar interesse (true/false) |
| `notify_on_confirmed` | boolean, opcional | Alertar quando um lead desta trilha for confirmado (true/false) |
| `min_founding_date` | string, opcional | Data de fundação da empresa mais antiga a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |
| `max_founding_date` | string, opcional | Data de fundação da empresa mais recente a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |

### Configurações de prospecção

A chave geral mais tudo que define quem é contatado e como: segmentação, regras e preferências.

#### `get_prospecting_config` (leitura)

Retorna toda a configuração de prospecção: filtros (CNAE, localização), instruções, objetivo, estratégia, critérios de revisão humana, instruções de qualificação de leads, configurações de notificação, modo e status de ativação.

- `POST /rest/v1/tools/get_prospecting_config`
- `GET /rest/v1/call/get_prospecting_config`

Parâmetros: —

#### `set_allow_template_whatsapp_messages` (escrita)

Permite ou bloqueia mensagens de template de WhatsApp iniciadas pelo agente para leads. Quando bloqueado, o agente só pode responder a leads que escreveram primeiro, dentro da janela de 24 horas do WhatsApp, e nunca abre uma conversa por template. Respostas de texto livre não são afetadas.

- `POST /rest/v1/tools/set_allow_template_whatsapp_messages`

| Parâmetros | | |
|---|---|---|
| `allowed` | boolean, obrigatório | true para permitir mensagens de template iniciadas pelo agente, false para apenas responder |

#### `set_prospecting_active` (escrita)

Ativa ou desativa a prospecção autônoma. Retorna o novo status e as informações de elegibilidade.

- `POST /rest/v1/tools/set_prospecting_active`

| Parâmetros | | |
|---|---|---|
| `active` | boolean, obrigatório | true para ativar, false para desativar |

#### `set_prospecting_preferences` (escrita)

Atualiza as preferências de prospecção: modo (Active/Passive), apresentações personalizadas e configurações de notificação. Passe apenas os campos que deseja alterar.

- `POST /rest/v1/tools/set_prospecting_preferences`

| Parâmetros | | |
|---|---|---|
| `mode` | string, opcional | Modo de prospecção: 'Active' (buscando leads) ou 'Passive' (pausado até revisão) |
| `generate_presentations` | boolean, opcional | Se deve gerar apresentações personalizadas por lead (true/false) |
| `notification_email` | string, opcional | Endereço de e-mail para receber notificações de prospecção |
| `notify_on_interested` | boolean, opcional | Notificar (in-app/WhatsApp) quando leads demonstrarem interesse (true/false) |
| `notify_on_confirmed` | boolean, opcional | Notificar (in-app/WhatsApp) quando leads forem confirmados (true/false) |
| `notify_on_interested_via_email` | boolean, opcional | Enviar o E-MAIL com a marca da empresa quando leads demonstrarem interesse (true/false) — independente do alerta in-app/WhatsApp |
| `notify_on_confirmed_via_email` | boolean, opcional | Enviar o E-MAIL com a marca da empresa quando leads forem confirmados (true/false) — independente do alerta in-app/WhatsApp |
| `notify_on_first_whatsapp_message` | boolean, opcional | Notificar (aviso único) quando um lead enviar a primeira mensagem no WhatsApp (true/false) |
| `cc_on_interested_lead_emails` | boolean, opcional | Copiar o cliente nos e-mails de lead interessado enviados aos endereços de notificação (true/false) |

#### `set_prospecting_rules` (escrita)

Atualiza as regras de prospecção: instruções para o agente, objetivo de abordagem, estratégia, critérios de revisão humana e instruções de qualificação de leads. Passe apenas os campos que deseja alterar.

- `POST /rest/v1/tools/set_prospecting_rules`

| Parâmetros | | |
|---|---|---|
| `instructions` | string, opcional | Instruções sobre como o agente deve prospectar (substituição direta) |
| `goal` | string, opcional | Objetivo desejado da prospecção (ex.: 'agendar uma demonstração', 'marcar uma reunião') |
| `strategy` | string, opcional | Documento de estratégia de prospecção |
| `human_review_criteria` | string, opcional | Critérios para quando escalar leads para revisão humana |
| `lead_qualification_instructions` | string, opcional | Regras sobre COMO avaliar leads em relação ao ICP — quais características são requisitos obrigatórios versus preferências flexíveis, condições de exceção, regras de tolerância, limites de desqualificação. Distinto do ICP em si (quem visar). |
| `email_instructions` | string, opcional | Sobreposição de instruções do canal de e-mail — orientação extra aplicada APENAS ao contatar um lead por e-mail, sobreposta às instruções gerais (substituição direta da sobreposição de e-mail). |
| `whatsapp_instructions` | string, opcional | Sobreposição de instruções do canal de WhatsApp — orientação extra aplicada APENAS ao contatar um lead pelo WhatsApp, sobreposta às instruções gerais (substituição direta da sobreposição de WhatsApp). |
| `voice_instructions` | string, opcional | Sobreposição de instruções do canal de voz — orientação extra aplicada APENAS em ligações ativas, sobreposta às instruções gerais (substituição direta da sobreposição de voz). |
| `email_signature` | string, opcional | Bloco de assinatura exato anexado literalmente a cada e-mail de prospecção. Quando definido, o copywriter não escreve assinatura própria. Envie uma string vazia para limpá-lo e voltar à assinatura padrão somente com o nome. |

#### `set_targeting` (escrita)

Atualiza os filtros de segmentação da prospecção. Passe apenas os campos que deseja alterar. Valores separados por vírgula para campos multivalorados. Para filtros numéricos (número de funcionários, receita), defina como -1 para limpar.

- `POST /rest/v1/tools/set_targeting`

| Parâmetros | | |
|---|---|---|
| `cnae_filter` | string, opcional | Códigos CNAE separados por vírgula a incluir (ex.: '6201,6202,6311') |
| `cnae_exclusion_filter` | string, opcional | Códigos CNAE separados por vírgula a excluir |
| `uf_filter` | string, opcional | Códigos de estado brasileiro separados por vírgula (ex.: 'SP,RJ,MG') |
| `city_filter` | string, opcional | Nomes de cidades separados por vírgula |
| `country_filter` | string, opcional | Códigos de país ISO separados por vírgula (ex.: 'BR,US') |
| `min_employee_count` | integer, opcional | Número mínimo de funcionários (-1 para limpar) |
| `max_employee_count` | integer, opcional | Número máximo de funcionários (-1 para limpar) |
| `min_annual_revenue` | number, opcional | Receita anual mínima (-1 para limpar) |
| `max_annual_revenue` | number, opcional | Receita anual máxima (-1 para limpar) |
| `company_size_filter` | string, opcional | Tamanhos de empresa separados por vírgula: Micro,Small,Medium,Large (vazio para limpar) |
| `company_type_filter` | string, opcional | Tipos de empresa separados por vírgula para incluir nas buscas de leads: Private, Individual, Government, StateOwned, NonProfit. Padrão (vazio) = apenas Private — MEI / empreendedores individuais, governo, estatais e entidades sem fins lucrativos são excluídos. |
| `min_founding_date` | string, opcional | Data de fundação mais antiga da empresa a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |
| `max_founding_date` | string, opcional | Data de fundação mais recente da empresa a incluir, no formato 'yyyy-MM-dd' (vazio para limpar) |

### Arquivos de prospecção

O catálogo de arquivos que o agente pode enviar para um lead — apresentações, tabelas de preço, guias — no escopo de uma campanha ou da conta inteira.

#### `list_prospecting_files` (leitura)

Lista o catálogo de arquivos de prospecção — os materiais que o agente de prospecção pode oferecer e enviar aos leads, com o title, description, url e escopo de campanha de cada arquivo.

- `POST /rest/v1/tools/list_prospecting_files`
- `GET /rest/v1/call/list_prospecting_files`

Parâmetros: —

#### `register_prospecting_file` (escrita)

Registra um arquivo no catálogo de arquivos de prospecção — os materiais que o agente de prospecção pode oferecer e ENVIAR AOS LEADS durante o contato (tabela de preços, apresentação institucional, guia de integração), via anexos de e-mail e documentos do WhatsApp. Forneça customer_file_id (um arquivo do cliente já enviado — preferido) ou uma url direta. Se nenhuma description for informada, uma é gerada automaticamente a partir do conteúdo do arquivo, para que o agente saiba quando enviá-lo. NÃO serve para o conhecimento do negócio a partir do qual o agente responde perguntas (register_business_file) nem para o guia personalizado gerado por IA por lead.

- `POST /rest/v1/tools/register_prospecting_file`

| Parâmetros | | |
|---|---|---|
| `title` | string, obrigatório | Título curto voltado para o lead, ex.: 'Tabela de preços' |
| `description` | string, opcional | O que o arquivo contém e quando enviá-lo a um lead (1 a 3 frases). Deixe em branco para gerar automaticamente a partir do conteúdo do arquivo. |
| `customer_file_id` | integer, opcional | Id de um arquivo de cliente existente para registrar (preferível a uma url direta) |
| `url` | string, opcional | URL pública direta do arquivo (alternativa a customer_file_id) |
| `campaign` | string, opcional | Nome de campanha opcional para tornar o arquivo enviável APENAS para os leads dessa campanha. Deixe em branco para um arquivo válido para todo o cliente, enviável a qualquer lead. |
| `sort_order` | integer, opcional, padrão `0` | Ordem de exibição/prompt no catálogo (menor primeiro, padrão 0) |

#### `remove_prospecting_file` (destrutiva)

Remove um arquivo do catálogo de arquivos de prospecção para que o agente de prospecção pare de oferecê-lo e enviá-lo aos leads. Encontre o id com list_prospecting_files.

- `POST /rest/v1/tools/remove_prospecting_file`

| Parâmetros | | |
|---|---|---|
| `prospecting_file_id` | integer, obrigatório | Id do arquivo de prospecção a ser removido |

#### `update_prospecting_file` (escrita)

Atualiza o título, a descrição, o escopo de campanha ou a ordem de exibição de um arquivo de prospecção. Encontre o id com list_prospecting_files. Para alterar o arquivo em si, remova a entrada e registre uma nova.

- `POST /rest/v1/tools/update_prospecting_file`

| Parâmetros | | |
|---|---|---|
| `prospecting_file_id` | integer, obrigatório | Id do arquivo de prospecção a ser atualizado |
| `title` | string, opcional | Novo título voltado ao lead |
| `description` | string, opcional | Nova descrição do que o arquivo contém e de quando enviá-lo |
| `campaign` | string, opcional | Nome da campanha à qual o arquivo deve ser vinculado, ou 'all' para torná-lo válido para todo o cliente |
| `sort_order` | integer, opcional | Nova ordem de exibição/prompt no catálogo (menor primeiro) |

### Relatórios

Os números: relatório principal de prospecção, funil por setor e por estado, tendências de performance, performance das mensagens, estimativas de volume e um resumo narrativo do que mudou.

#### `estimate_lead_volume` (leitura)

Retorna um benchmark do que um cliente PAGO típico da Blue Button (e clientes pagos com um ICP semelhante) produz nos últimos 30 dias: novos leads encontrados, respostas confirmadas (conversas reais), leads interessados (quentes), e mensagens enviadas — cada um mostrado como um intervalo da mediana (cliente típico) até o topo (os mais ativos) por semana e por mês. Usuários somente do teste gratuito são excluídos. A ferramenta escolhe o benchmark mais relevante automaticamente — Similar (clientes pagos com sobreposição de CNAE) quando disponível, Global (todos os clientes pagos) caso contrário.

- `POST /rest/v1/tools/estimate_lead_volume`
- `GET /rest/v1/call/estimate_lead_volume`

Parâmetros: —

#### `get_funnel_by_industry` (leitura)

Obtém uma divisão do funil por setor. Para clientes brasileiros, agrupa por divisão do CNAE. Para clientes internacionais, agrupa pelo campo CompanyIndustry dos dados da Apollo/Lusha. Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/get_funnel_by_industry`
- `GET /rest/v1/call/get_funnel_by_industry`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para o funil global) |

#### `get_funnel_timeline` (leitura)

Contagem de leads ENTRANDO em cada estágio do funil por bucket de tempo (dia ou semana). Estágios rastreados: cold (DateProspectingStarted), confirmed (DateConfirmedProspectingQualification), interested (DateConfirmedInterest), closed (DateStatusChanged enquanto o Status atual = Closed — APROXIMAÇÃO: um lead que esteve Closed e depois mudou para outro status não será contado, porque a plataforma não armazena histórico de status). Aware não é exposto — a plataforma não rastreia de forma confiável a entrada nesse estágio. Buckets ausentes preenchidos com zeros, do mais recente para o mais antigo. Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/get_funnel_timeline`
- `GET /rest/v1/call/get_funnel_timeline`

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `bucket` | string, opcional, padrão `day` | Tamanho do bucket: 'day' (padrão) ou 'week' (alinhado à segunda-feira) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para a timeline global) |

#### `get_message_performance` (leitura)

Taxa de resposta detalhada por campanha e/ou tipo de mensagem em uma janela de tempo. Retorna total sent, replied (e-mails de saída distintos com pelo menos uma resposta), reply_rate_pct, além de um detalhamento. O formato do detalhamento depende de group_by: 'campaign' retorna uma linha por campanha (tipos de mensagem agrupados); 'type' retorna uma linha por tipo de mensagem (campanhas agrupadas); 'both' (padrão) retorna uma linha por combinação campanha×tipo (uma matriz — NÃO duas listas separadas — então espere até N_campaigns × N_types linhas). Tipos de mensagem: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse a mensagens recebidas), direct (DirectMessage enviada em nome do usuário), user_written (UserWrittenMessage enviada manualmente pelo usuário). Padrão de 30 dias.

- `POST /rest/v1/tools/get_message_performance`
- `GET /rest/v1/call/get_message_performance`

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias retroativos (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para todas as campanhas) |
| `group_by` | string, opcional, padrão `both` | Como agrupar o detalhamento: 'campaign', 'type', ou 'both' (padrão) |

#### `get_metrics_by_state_and_industry` (leitura)

Detalha cada métrica de prospecção por ESTADO brasileiro e por SETOR (descrição do CNAE) ao longo de uma janela de tempo, para que você possa comparar quais estados/setores estão performando melhor. Para cada dimensão, retorna os grupos principais por volume de leads — cada um com new_leads, emails_sent, responses, whatsapp_sent, whatsapp_responses, conscientizados, interested (tornou-se interested na janela), confirmed_aware_interested_or_takenover, referrals, e contagens de reuniões (convites feitos/recebidos, agendadas, realizadas) — além do grupo com melhor desempenho por categoria de métrica. Leads sem estado/CNAE caem em 'Não informado' e são excluídos das seleções de melhor desempenho. interested é contado por DateConfirmedInterest (o momento em que o lead converteu). Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/get_metrics_by_state_and_industry`
- `GET /rest/v1/call/get_metrics_by_state_and_industry`

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias retroativos (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para a conta inteira) |

#### `get_performance_trends` (leitura)

Obtenha as tendências de desempenho de prospecção por dia durante a janela especificada. Todas as métricas são contagens diárias de FLOW (eventos que aconteceram naquele dia), não estoques cumulativos. Cada linha tem: leads_generated (leads criados naquele dia), emails_sent (e-mails de prospecção de saída enviados naquele dia), replies_received (respostas de entrada a e-mails de saída recebidas naquele dia), confirmed (leads cujo status se tornou Confirmed pela primeira vez naquele dia, ou seja, DateConfirmedProspectingQualification cai naquele dia), interested (leads cujo status se tornou Interested pela primeira vez naquele dia, ou seja, DateConfirmedInterest cai naquele dia — esta é a contagem de entradas por dia, NÃO o número total de leads atualmente com Status=Interested), whatsapp_sent (mensagens de WhatsApp de prospecção enviadas naquele dia, por DateSent), whatsapp_replies_received (respostas de WhatsApp de leads naquele dia, pelo timestamp de envio do lead). Dias faltantes são preenchidos com zeros. Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/get_performance_trends`
- `GET /rest/v1/call/get_performance_trends`

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para tendências globais) |

#### `get_prospecting_report` (leitura)

Obtenha um relatório geral de prospecção: total de leads, leads por status, e-mails enviados, taxa de resposta e resumo do pipeline. Também retorna atividade no WhatsApp: whatsapp_sent (mensagens de WhatsApp de prospecção enviadas), whatsapp_responses (respostas de WhatsApp recebidas, contadas separadamente das respostas por e-mail) e leads_talked_to_on_whatsapp (leads distintos com qualquer mensagem de WhatsApp em qualquer direção). Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/get_prospecting_report`
- `GET /rest/v1/call/get_prospecting_report`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para relatório global) |

#### `get_whatsapp_message_performance` (leitura)

Desempenho de respostas de WhatsApp detalhado por campanha e/ou tipo de mensagem em uma janela de tempo. OBSERVAÇÃO: diferente de get_message_performance (e-mail), a taxa de resposta do WhatsApp é reportada no nível do LEAD — o WhatsApp de entrada não tem vínculo por mensagem com uma mensagem de saída específica, então 'replied' não pode ser atribuído por mensagem. Retorna total sent (contagem de mensagens), leads_messaged (leads distintos contatados), leads_replied (leads distintos que enviaram pelo menos uma mensagem de entrada em ou após sua primeira mensagem de saída daquele tipo na janela), lead_reply_rate_pct (leads_replied / leads_messaged), além de uma discriminação. group_by: 'campaign' (uma linha por campanha), 'type' (uma linha por tipo de mensagem), 'both' (padrão, matriz campaign×type). Tipos de mensagem: first_contact (AutonomousFirstTouch), follow_up (AutonomousFollowUp), response (AutonomousResponse), direct (DirectMessage), user_written (UserWrittenMessage). Padrão de 30 dias.

- `POST /rest/v1/tools/get_whatsapp_message_performance`
- `GET /rest/v1/call/get_whatsapp_message_performance`

| Parâmetros | | |
|---|---|---|
| `days` | integer, opcional, padrão `30` | Número de dias para olhar para trás (padrão 30, máximo 365) |
| `campaign` | string, opcional | Filtra por nome da campanha ou campaign_id numérico (opcional, omita para todas as campanhas) |
| `group_by` | string, opcional, padrão `both` | Como agrupar o detalhamento: 'campaign', 'type', ou 'both' (padrão) |

#### `list_prospecting_optimizations` (leitura)

Lista o histórico de otimizações autônomas de prospecção em ordem cronológica reversa (mais recentes primeiro). Paginado. Cada entrada mostra quando o agente revisor de prospecção rodou e quais mudanças de segmentação/configuração ele fez e por quê. Opcionalmente, filtre por campanha.

- `POST /rest/v1/tools/list_prospecting_optimizations`
- `GET /rest/v1/call/list_prospecting_optimizations`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, opcional | Filtrar por nome da campanha ou campaign_id numérico (opcional, omita para todas as otimizações) |
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |

#### `what_changed_since` (leitura)

Resumo completo do que aconteceu na operação de prospecção desde uma determinada data — criado para o caso 'fiquei ausente por meses, o que aconteceu?'. Blocos: (1) activity_summary — o trabalho bruto do motor na janela: new_leads, emails_sent, email_replies, whatsapp_sent, whatsapp_replies; (2) funnel_progress — leads que atingiram cada estágio na janela: reached_confirmed, became_interested; (3) new_interested_leads — os próprios leads interessados (até 100, mais total_count); (4) outcomes — negócios fechados na janela: won_count, lost_count, gave_up_count, total_deal_value_brl, e won_items; (5) meetings — contagens de agendadas, canceladas, realizadas e no_show na janela, mais items; (6) pending_human_review — o monte ATUAL de leads aguardando o dono da conta (uma captura instantânea ao vivo, NÃO limitada à janela): total_count mais items; (7) support_answered — solicitações de suporte respondidas pela equipe na janela (message + answer); (8) campaign_performance_changes — campanhas cuja taxa de resposta variou pelo menos 3 pontos percentuais (janela de 30 dias terminando em since_date vs since_date→now, ignorando janelas com menos de 50 enviados); (9) optimizer_adjustments — alterações do prospecting-optimizer persistidas desde essa data (limitadas a 500 itens; total_count/returned_count/truncated informam o total real). Todas as contagens com janela cobrem since_date→now; os timestamps estão em UTC.

- `POST /rest/v1/tools/what_changed_since`
- `GET /rest/v1/call/what_changed_since`

| Parâmetros | | |
|---|---|---|
| `since_date` | string, obrigatório | Data ISO no formato YYYY-MM-DD (ex.: 2026-01-15) |

### Ligações

Faz uma ligação com objetivo definido para um lead, lê as ligações já realizadas e liga ou desliga as chamadas por conta ou por campanha.

#### `get_campaign_voice_calling_active` (leitura)

Lê o toggle de chamadas de voz de uma campanha. Um valor null significa que a campanha herda o toggle em nível de cliente.

- `POST /rest/v1/tools/get_campaign_voice_calling_active`
- `GET /rest/v1/call/get_campaign_voice_calling_active`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome da campanha |

#### `get_voice_call` (leitura)

Obtenha o status e o resultado de uma chamada telefônica orientada a objetivo feita com place_goal_driven_call: status do ciclo de vida, se uma pessoa atendeu, se o objetivo foi alcançado, o resumo do resultado e a transcrição completa.

- `POST /rest/v1/tools/get_voice_call`
- `GET /rest/v1/call/get_voice_call`

| Parâmetros | | |
|---|---|---|
| `voice_call_request_id` | integer, obrigatório | O voice_call_request_id retornado por place_goal_driven_call |

#### `get_voice_calling_active` (leitura)

Leia se as chamadas de voz de saída autônomas para leads estão ativas no nível do cliente.

- `POST /rest/v1/tools/get_voice_calling_active`
- `GET /rest/v1/call/get_voice_calling_active`

Parâmetros: —

#### `list_voice_calls` (leitura)

Lista as ligações telefônicas orientadas a objetivo do cliente (mais recentes primeiro) com status e resumo do desfecho. Use get_voice_call para a transcrição completa de uma ligação.

- `POST /rest/v1/tools/list_voice_calls`
- `GET /rest/v1/call/list_voice_calls`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `20` | Tamanho da página (padrão 20, máximo 100) |

#### `place_goal_driven_call` (escrita)

Faz uma ligação telefônica REAL para um número fornecido pelo cliente, para cumprir um objetivo declarado (por exemplo, 'ligue para este restaurante e pergunte se há mesa disponível hoje à noite'). Um assistente de voz em tempo real faz a ligação em segundo plano; isso apenas enfileira a solicitação — a ligação é feita pouco depois e não pode ser cancelada assim que a discagem começa. Faça polling de get_voice_call com o voice_call_request_id retornado para obter o resultado (status, goal_achieved, summary, transcript); o resultado também chega como uma notificação da plataforma.

- `POST /rest/v1/tools/place_goal_driven_call`

| Parâmetros | | |
|---|---|---|
| `phone_number` | string, obrigatório | O número de telefone para ligar, em formato internacional, ex.: +5511999999999 |
| `goal` | string, obrigatório | O objetivo da ligação em linguagem simples e no idioma do cliente — exatamente o que deve ser realizado ou descoberto |
| `context` | string, opcional | Histórico/contexto opcional: quem está sendo chamado e qualquer informação útil |

#### `set_campaign_voice_calling_active` (escrita)

Habilita ou desabilita ligações de voz ativas autônomas para uma campanha específica, sobrepondo a opção em nível de cliente apenas para essa campanha.

- `POST /rest/v1/tools/set_campaign_voice_calling_active`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome da campanha |
| `active` | boolean, obrigatório | True para ativar, false para desativar, para esta campanha |

#### `set_voice_calling_active` (escrita)

Habilita ou desabilita as chamadas de voz autônomas de saída para leads no nível do cliente. Independente da prospecção por e-mail.

- `POST /rest/v1/tools/set_voice_calling_active`

| Parâmetros | | |
|---|---|---|
| `active` | boolean, obrigatório | True para ativar, false para desativar |

### Linha de WhatsApp

Cadastra e consulta a linha de WhatsApp de prospecção, define os tetos de custo mensal e diário e atualiza o perfil comercial.

#### `get_whatsapp_line` (leitura)

Obtenha a linha de prospecção de WhatsApp do cliente — a leitura única de status/diagnóstico: se está ativa/pronta para enviar, seu número, classificação de qualidade, perfil comercial completo do WhatsApp, o link pendente de cadastro em um clique da Meta (quando o cliente ainda precisa conectar sua WhatsApp Business Account), qualquer PROBLEMA DE SAÚDE ATIVO com a correção exata que o cliente deve aplicar (forma de pagamento, link de reconexão, restrição da Meta) e o gasto de WhatsApp no dia e no mês até o momento em relação aos limites de custo diário e mensal do cliente. Atualiza o snapshot ao vivo da Meta primeiro.

- `POST /rest/v1/tools/get_whatsapp_line`
- `GET /rest/v1/call/get_whatsapp_line`

Parâmetros: —

#### `register_whatsapp_line` (escrita)

Registra uma linha dedicada de WhatsApp para prospecção (um número real de WhatsApp). O provisionamento é automático e leva alguns minutos. Se o cliente já tiver uma linha, retorna essa linha em vez de criar outra (uma linha por cliente). Requer um plano pago ativo que inclua prospecção por WhatsApp. Por padrão, a Eesier fornece um número novo; passe use_own_number=true quando o cliente quiser prospectar a partir do PRÓPRIO número de WhatsApp — nesse caso, ele recebe um link da Meta de um clique, cujo popup oficial conecta a WhatsApp Business Account dele (ou cria uma), permite escolher qual dos seus números usar, ou verifica um novo número na hora.

- `POST /rest/v1/tools/register_whatsapp_line`

| Parâmetros | | |
|---|---|---|
| `use_own_number` | boolean, opcional, padrão `false` | True quando o cliente quer usar o PRÓPRIO número de WhatsApp em vez de um novo fornecido pela Eesier. Padrão false. |

#### `set_whatsapp_daily_cost_cap` (escrita)

Define (ou remove) o limite diário de gastos com prospecção por WhatsApp do cliente, em BRL. A Meta cobra as taxas de conversas do WhatsApp diretamente na própria conta do cliente, então esse limite permite que o cliente decida o valor máximo que deseja gastar por dia. Quando o limite é atingido, as mensagens pagas de WhatsApp (que abrem conversa) são pausadas até o dia seguinte — respostas a leads que mandam mensagem primeiro continuam funcionando, e a prospecção por e-mail não é afetada. Passe 0 ou um valor negativo para remover o limite. O gasto atual e o limite ficam visíveis em get_whatsapp_line.

- `POST /rest/v1/tools/set_whatsapp_daily_cost_cap`

| Parâmetros | | |
|---|---|---|
| `daily_cap_brl` | number, obrigatório | Gasto diário máximo com WhatsApp em BRL (ex.: 20.00). 0 ou negativo remove o limite. |

#### `set_whatsapp_line_profile_picture` (escrita)

Define a foto de perfil da linha de WhatsApp a partir de uma URL de imagem pública ou de um arquivo do cliente já enviado. JPG/PNG quadrado, com no mínimo 192x192, abaixo de 5MB. A linha já precisa estar ativa.

- `POST /rest/v1/tools/set_whatsapp_line_profile_picture`

| Parâmetros | | |
|---|---|---|
| `image_url` | string, opcional | URL pública da imagem (JPG/PNG quadrada, >=192x192, <=5MB) |
| `customer_file_id` | integer, opcional | Id de um arquivo do cliente já enviado para usar como a foto. Preferível quando o usuário enviou uma imagem. |

#### `set_whatsapp_monthly_cost_cap` (escrita)

Define (ou remove) o limite mensal de gastos com prospecção por WhatsApp do cliente, em BRL. A Meta cobra as taxas de conversas do WhatsApp diretamente na própria conta do cliente, então esse limite permite que o cliente decida o valor máximo que deseja gastar por mês civil. Quando o limite é atingido, as mensagens pagas de WhatsApp (que abrem conversa) são pausadas até o dia 1º do mês seguinte — respostas a leads que mandam mensagem primeiro continuam funcionando, e a prospecção por e-mail não é afetada. Passe 0 ou um valor negativo para remover o limite. O gasto atual e o limite ficam visíveis em get_whatsapp_line.

- `POST /rest/v1/tools/set_whatsapp_monthly_cost_cap`

| Parâmetros | | |
|---|---|---|
| `monthly_cap_brl` | number, obrigatório | Gasto mensal máximo com WhatsApp em BRL (ex.: 150.00). 0 ou negativo remove o limite. |

#### `update_whatsapp_line_profile` (escrita)

Atualiza o perfil comercial da linha do WhatsApp. Somente os campos informados são alterados. A linha já deve estar ativa. O nome de exibição não é gerenciado aqui.

- `POST /rest/v1/tools/update_whatsapp_line_profile`

| Parâmetros | | |
|---|---|---|
| `about` | string, opcional | Texto curto de 'sobre' (máx. 139 caracteres) |
| `description` | string, opcional | Descrição do negócio (máx. 512 caracteres) |
| `address` | string, opcional | Endereço comercial (rua) |
| `email` | string, opcional | E-mail de contato comercial |
| `websites` | string, opcional | URLs do site do negócio, separadas por vírgula (o WhatsApp exibe no máximo 2) |
| `vertical` | string, opcional | Categoria do negócio (vertical do WhatsApp), ex.: PROF_SERVICES, RETAIL, EDU, HEALTH, FINANCE, RESTAURANT, OTHER |

### Perfil do negócio

O que a conta vende e para quem. Lê o perfil, lê a avaliação que o agente faz dele e reescreve.

#### `get_business` (leitura)

Retorna o perfil de negócio do cliente: nome, descrição, site, perfil de cliente ideal e URL de apresentação padrão.

- `POST /rest/v1/tools/get_business`
- `GET /rest/v1/call/get_business`

Parâmetros: —

#### `get_business_assessment` (leitura)

Lê a última avaliação de fundamentos de negócio que o consultor interno do Blue Button registrou para este cliente: veredito, probabilidade de resultados, o JSON completo da avaliação, quando foi feita, e os exemplos conhecidos de clientes pagantes do cliente. Dados somente leitura — traga sua própria análise em cima disso; não há ferramenta para reexecutar a avaliação.

- `POST /rest/v1/tools/get_business_assessment`
- `GET /rest/v1/call/get_business_assessment`

Parâmetros: —

#### `set_business` (escrita)

Atualiza o perfil de negócio do cliente. Passe apenas os campos que deseja alterar. Campos: business_name, business_description, business_website, ideal_customer_profile, paying_customer_examples. Para os arquivos que o agente de prospecção envia aos leads (apresentação, tabela de preços, ...), use as ferramentas de arquivo de prospecção (register_prospecting_file / list_prospecting_files).

- `POST /rest/v1/tools/set_business`

| Parâmetros | | |
|---|---|---|
| `business_name` | string, opcional | Nome do negócio |
| `business_description` | string, opcional | Descrição do negócio |
| `business_website` | string, opcional | URL do site do negócio |
| `ideal_customer_profile` | string, opcional | Texto do perfil de cliente ideal |
| `paying_customer_examples` | string, opcional | Exemplos reais de clientes pagantes a partir dos quais o ICP e o consultor de negócios raciocinam |

### Arquivos do negócio

O material de referência que o agente lê para entender o negócio — cadastra, lista e remove.

#### `list_business_files` (leitura)

Liste os arquivos de conhecimento do negócio registrados para este cliente, com o estado de indexação e o escopo de campanha de cada arquivo.

- `POST /rest/v1/tools/list_business_files`
- `GET /rest/v1/call/list_business_files`

Parâmetros: —

#### `register_business_file` (escrita)

Registra um texto (ou um arquivo do cliente já enviado) como conhecimento do negócio, para que os agentes de prospecção possam responder perguntas sobre o negócio (serviços, processos, preços, perguntas frequentes). O conteúdo é fragmentado + vetorizado em segundo plano e torna-se pesquisável em pouco tempo. Forneça text ou customer_file_id.

- `POST /rest/v1/tools/register_business_file`

| Parâmetros | | |
|---|---|---|
| `title` | string, obrigatório | Título curto e descritivo, ex.: 'Tabela de preços 2026' |
| `text` | string, opcional | Texto bruto para registrar como conhecimento do negócio (use quando o conteúdo foi colado diretamente) |
| `customer_file_id` | integer, opcional | Id de um arquivo de cliente existente para registrar (encontre-o com list_business_files ou na lista de arquivos) |
| `campaign` | string, opcional | Nome de campanha opcional para restringir este conhecimento a uma campanha. Deixe em branco para conhecimento em nível de cliente, compartilhado entre todas as campanhas. |

#### `remove_business_file` (destrutiva)

Remove um arquivo de conhecimento do negócio registrado e seus trechos indexados para que os agentes parem de responder com base nele. Encontre o id com list_business_files.

- `POST /rest/v1/tools/remove_business_file`

| Parâmetros | | |
|---|---|---|
| `business_file_id` | integer, obrigatório | Id do arquivo de conhecimento da empresa a ser removido |

### Perguntas frequentes

As perguntas que os leads sempre fazem: o FAQ já respondido do negócio e as que continuam em aberto esperando resposta.

#### `list_business_faq` (leitura)

Liste o FAQ do negócio — todo par de pergunta e resposta que a plataforma acumulou sobre este negócio (cada resposta dada via answer_lead_question chega aqui, e os agentes de prospecção o utilizam para responder aos leads). Leia antes de perguntar ao usuário algo que já possa ter sido respondido.

- `POST /rest/v1/tools/list_business_faq`
- `GET /rest/v1/call/list_business_faq`

Parâmetros: —

#### `list_open_lead_questions` (leitura)

Lista as perguntas que os LEADS fizeram e que o agente não conseguiu responder e que ainda estão aguardando a contribuição do dono do negócio. Loop de alto valor: apresente estas ao usuário, obtenha as respostas, depois registre cada uma via answer_lead_question (passando o open_question_id) — cada resposta melhora todas as conversas futuras com leads.

- `POST /rest/v1/tools/list_open_lead_questions`
- `GET /rest/v1/call/list_open_lead_questions`

Parâmetros: —

### Sugestões

Pede para a plataforma montar a segmentação: um perfil de cliente ideal, ou os CNAEs a incluir e a excluir.

#### `generate_cnae_exclusion_suggestion` (leitura)

Gera códigos de exclusão de CNAE sugeridos com base em um perfil de cliente ideal e na descrição do negócio. Esses códigos identificam concorrentes e setores incompatíveis a excluir da prospecção. Funciona apenas para clientes brasileiros. Retorna os códigos sem salvar — use set_targeting para salvar.

- `POST /rest/v1/tools/generate_cnae_exclusion_suggestion`
- `GET /rest/v1/call/generate_cnae_exclusion_suggestion`

| Parâmetros | | |
|---|---|---|
| `icp_text` | string, opcional | Texto do ICP para analisar. Se omitido, usa o ICP atual do cliente. |

#### `generate_cnae_suggestion` (leitura)

Gera códigos de inclusão de CNAE sugeridos com base em um perfil de cliente ideal. Os códigos CNAE são usados para direcionar setores específicos na prospecção de leads no Brasil. Funciona apenas para clientes brasileiros. Retorna os códigos sem salvar — use set_targeting para salvar.

- `POST /rest/v1/tools/generate_cnae_suggestion`
- `GET /rest/v1/call/generate_cnae_suggestion`

| Parâmetros | | |
|---|---|---|
| `icp_text` | string, opcional | Texto do ICP para analisar. Se omitido, usa o ICP atual do cliente. |

#### `generate_icp_suggestion` (leitura)

Gera uma sugestão de perfil de cliente ideal (ICP) com base nas informações do negócio do cliente. Usa IA para analisar o negócio e sugerir quem são os clientes ideais. Retorna a sugestão sem salvá-la — use set_business para salvar.

- `POST /rest/v1/tools/generate_icp_suggestion`
- `GET /rest/v1/call/generate_icp_suggestion`

Parâmetros: —

### Consultas de referência

Busca na base de conhecimento da própria plataforma antes de responder qualquer pergunta sobre como ela funciona, e resolve CNAEs e cidades.

#### `lookup_city` (leitura)

Consulta o código de uma cidade brasileira (código IBGE) a partir do nome da cidade. Funciona apenas para clientes brasileiros. Retorna as cidades correspondentes. Usado para filtros de prospecção baseados em cidade.

- `POST /rest/v1/tools/lookup_city`
- `GET /rest/v1/call/lookup_city`

| Parâmetros | | |
|---|---|---|
| `city_name` | string, obrigatório | Nome da cidade a ser buscada (ex.: 'São Paulo', 'Curitiba') |

#### `lookup_cnae` (leitura)

Consulta o nome e a descrição de um código CNAE. CNAE (Classificação Nacional de Atividades Econômicas) é o sistema brasileiro de classificação de atividades econômicas. Funciona apenas para clientes brasileiros. Forneça um código para obter seu nome no nível de divisão (2 dígitos), grupo (3 dígitos), classe (5 dígitos) ou subclasse (7 dígitos).

- `POST /rest/v1/tools/lookup_cnae`
- `GET /rest/v1/call/lookup_cnae`

| Parâmetros | | |
|---|---|---|
| `code` | string, obrigatório | Código CNAE (ex.: '62' para divisão de TI, '6201' para grupo de desenvolvimento de software, '6201501' para subclasse de desenvolvimento de software) |

#### `search_knowledge` (leitura)

Busca na base de conhecimento do Blue Button respostas oficiais sobre como a plataforma funciona — preços, planos, onboarding, capacidades de segmentação, envio de e-mail, assunção de controle, relatórios, privacidade, cancelamento, e toda outra pergunta específica da plataforma. Usa RAG semântico (similaridade de embeddings) sobre trechos de conhecimento curados, então a consulta pode ser uma pergunta em linguagem natural, uma palavra-chave, ou um tópico. SEMPRE chame esta ferramenta sempre que o usuário perguntar algo específico sobre o Blue Button — nunca improvise a partir de conhecimento geral. Retorna as melhores correspondências com título, conteúdo, e pontuação de similaridade.

- `POST /rest/v1/tools/search_knowledge`
- `GET /rest/v1/call/search_knowledge`

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | Consulta em linguagem natural descrevendo o que o usuário quer saber sobre o Blue Button (ex.: 'quanto custa', 'posso segmentar por tamanho da empresa', 'o que acontece quando eu assumo um lead', 'prospecção internacional'). |
| `top_k` | integer, opcional, padrão `3` | Número de melhores resultados a serem retornados. Padrão 3. Use um valor mais alto (até 10) quando a pergunta for ampla ou você quiser múltiplos ângulos. |
| `min_score` | number, opcional, padrão `0.7` | Limite mínimo de pontuação de similaridade (0.0–1.0). Padrão 0.7. Valores mais baixos retornam mais resultados, mas podem ser menos relevantes. |

### Lista de bloqueio

Nunca mais contatar: bloqueia e desbloqueia e-mails, domínios inteiros e telefones.

#### `add_blacklisted_domain` (escrita)

Adiciona um DOMÍNIO inteiro à lista negra. Todo e-mail nesse domínio (ex.: anyone@acme.com) é bloqueado. Não informe um endereço de e-mail completo — use add_blacklisted_email para isso.

- `POST /rest/v1/tools/add_blacklisted_domain`

| Parâmetros | | |
|---|---|---|
| `domain` | string, obrigatório | O domínio a ser colocado na lista negra, por exemplo, 'acme.com'. Subdomínios não são incluídos automaticamente. |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `add_blacklisted_email` (escrita)

Adiciona um único endereço de e-mail à lista negra. E-mails na lista negra nunca recebem mensagens de prospecção. Para bloquear uma empresa inteira, use add_blacklisted_domain.

- `POST /rest/v1/tools/add_blacklisted_email`

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail a ser colocado na lista negra |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `add_blacklisted_phone` (escrita)

Adiciona um NÚMERO DE TELEFONE à lista negra. O número nunca recebe mensagem de WhatsApp nem chamada de voz. Os dígitos são mantidos e todo o restante é removido, então qualquer formatação é aceita.

- `POST /rest/v1/tools/add_blacklisted_phone`

| Parâmetros | | |
|---|---|---|
| `phone` | string, obrigatório | O número de telefone a ser colocado na lista negra, em qualquer formato (por exemplo, '+55 11 99999-9999') |
| `reason` | string, opcional | Motivo: Competitor, Client, ou Other |

#### `list_blacklisted_emails` (leitura)

Liste as entradas bloqueadas (e-mails individuais, domínios inteiros e números de telefone) com seu motivo e a contagem de quantas vezes foi bloqueado. Paginado — 'total' reporta o tamanho completo da lista.

- `POST /rest/v1/tools/list_blacklisted_emails`
- `GET /rest/v1/call/list_blacklisted_emails`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `0` | Número da página (baseado em 0, padrão 0) |
| `page_size` | integer, opcional, padrão `50` | Entradas por página (padrão 50, máximo 200) |

#### `remove_blacklisted_domain` (destrutiva)

Remove um DOMÍNIO inteiro da blacklist, permitindo que os endereços desse domínio voltem a receber mensagens de prospecção.

- `POST /rest/v1/tools/remove_blacklisted_domain`

| Parâmetros | | |
|---|---|---|
| `domain` | string, obrigatório | O domínio a ser removido da blacklist, ex.: 'acme.com' |

#### `remove_blacklisted_email` (destrutiva)

Remove um único endereço de e-mail da blacklist, permitindo que ele volte a receber mensagens de prospecção.

- `POST /rest/v1/tools/remove_blacklisted_email`

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail a ser removido da blacklist |

#### `remove_blacklisted_phone` (destrutiva)

Remove um NÚMERO DE TELEFONE da blacklist, permitindo que ele volte a receber mensagens de WhatsApp e ligações de voz.

- `POST /rest/v1/tools/remove_blacklisted_phone`

| Parâmetros | | |
|---|---|---|
| `phone` | string, obrigatório | O número de telefone a ser removido da blacklist, em qualquer formato |

### Configurações da conta

Fuso horário, nome do usuário, preferências, permissão de ligação, e-mails de notificação, configurações de envio, domínio remetente e dados fiscais.

#### `get_email_settings` (leitura)

Obtém as configurações de e-mail do Blue Button do cliente: o endereço completo, o handle, o nome de exibição e as instruções de notificação.

- `POST /rest/v1/tools/get_email_settings`
- `GET /rest/v1/call/get_email_settings`

Parâmetros: —

#### `get_general_settings` (leitura)

Obtém as configurações gerais da conta do cliente: modo de voz, envio autônomo de mensagens, e-mail da conta e deslocamento de fuso horário.

- `POST /rest/v1/tools/get_general_settings`
- `GET /rest/v1/call/get_general_settings`

Parâmetros: —

#### `get_notification_emails` (leitura)

Obtenha os endereços de e-mail atualmente configurados para notificações de prospecção autônoma e relatórios diários.

- `POST /rest/v1/tools/get_notification_emails`
- `GET /rest/v1/call/get_notification_emails`

Parâmetros: —

#### `lookup_municipality_code` (leitura)

Consulta o código IBGE de 7 dígitos do município para uma cidade brasileira. Retorna todas as correspondências quando a cidade existe em mais de um estado. Use antes de update_tax_info.

- `POST /rest/v1/tools/lookup_municipality_code`
- `GET /rest/v1/call/lookup_municipality_code`

| Parâmetros | | |
|---|---|---|
| `city_name` | string, obrigatório | Nome da cidade brasileira (não diferencia acentos) |
| `state` | string, opcional | Estado opcional — UF de 2 letras (RS, SP...) ou nome completo em português — para desambiguar |

#### `set_agent_phone_call_permission` (escrita)

Obtém ou define se o agente pode fazer ligações telefônicas ativas para o cliente. Omita 'enabled' para ler o valor atual; passe true/false para alterá-lo.

- `POST /rest/v1/tools/set_agent_phone_call_permission`

| Parâmetros | | |
|---|---|---|
| `enabled` | boolean, opcional | True para permitir chamadas, false para bloquear. Omita para apenas ler o valor atual. |

#### `set_email_notification_instructions` (escrita)

Define as regras em texto livre que decidem quais e-mails recebidos merecem uma notificação imediata ao cliente. Passe uma string vazia para limpá-las e voltar ao comportamento padrão.

- `POST /rest/v1/tools/set_email_notification_instructions`

| Parâmetros | | |
|---|---|---|
| `instructions` | string, obrigatório | Regras que descrevem quais emails recebidos merecem um aviso imediato (vazio para limpar) |

#### `set_personal_email` (escrita)

Define o próprio endereço de e-mail pessoal da conta — o único endereço vinculado à própria conta, distinto da lista de e-mails de notificação de prospecção separada por vírgulas, gerenciada por update_notification_emails.

- `POST /rest/v1/tools/set_personal_email`

| Parâmetros | | |
|---|---|---|
| `email` | string, obrigatório | O endereço de e-mail pessoal do proprietário da conta |

#### `set_timezone` (escrita)

Define o fuso horário do cliente informando ao agente a hora local atual (0-23, formato 24h). O deslocamento é calculado a partir de UTC.

- `POST /rest/v1/tools/set_timezone`

| Parâmetros | | |
|---|---|---|
| `current_hour` | integer, obrigatório | Parte da hora do horário local atual do cliente, 0-23 (formato 24h) |

#### `setup_custom_domain` (escrita)

Configura, verifica ou remove um endereço de e-mail com domínio personalizado (ex.: sales@yourcompany.com). Requer um plano pago ativo. action: 'activate' (precisa de email_address), 'verify', ou 'remove'.

- `POST /rest/v1/tools/setup_custom_domain`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | 'activate' para definir um novo e-mail personalizado, 'verify' para verificar o DNS, 'remove' para removê-lo |
| `email_address` | string, opcional | O endereço de e-mail personalizado completo, ex.: 'sales@yourcompany.com'. Obrigatório para 'activate'. |

#### `setup_email_subdomain` (escrita)

Configura ou verifica um subdomínio de e-mail personalizado (ex.: yourcompany.eesiermail.com). Requer um plano pago ativo. action: 'activate' (precisa de subdomain) ou 'verify'.

- `POST /rest/v1/tools/setup_email_subdomain`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | 'activate' para definir um novo subdomínio, 'verify' para verificar o status de verificação do DNS |
| `subdomain` | string, opcional | O nome do subdomínio, ex.: 'mycompany'. Obrigatório para 'activate'. |

#### `update_email_settings` (escrita)

Atualiza o handle de e-mail do Blue Button (a parte antes do @, no máximo 20 caracteres, único) e/ou o nome de exibição mostrado nos e-mails enviados. Passe pelo menos um campo.

- `POST /rest/v1/tools/update_email_settings`

| Parâmetros | | |
|---|---|---|
| `handle` | string, opcional | Novo handle de e-mail (minúsculo, sem espaços, máx. 20 caracteres). Acentos/caracteres inválidos são removidos. |
| `display_name` | string, opcional | Novo nome de exibição para e-mails enviados (o nome 'De' que os destinatários veem) |

#### `update_notification_emails` (escrita)

Define o(s) endereço(s) de e-mail para notificações de prospecção autônoma e relatórios diários (separados por vírgula). O primeiro endereço também se torna o e-mail da conta.

- `POST /rest/v1/tools/update_notification_emails`

| Parâmetros | | |
|---|---|---|
| `emails` | string, obrigatório | Endereço(s) de email para notificações, separados por vírgula |

#### `update_preferences` (escrita)

Atualiza as preferências do cliente: idioma, se o negócio deve ser exibido no site do Blue Button, e notificações push. Informe pelo menos um campo.

- `POST /rest/v1/tools/update_preferences`

| Parâmetros | | |
|---|---|---|
| `language_key` | string, opcional | Chave de idioma, ex.: pt-BR, en-US, es-AR |
| `show_on_website` | boolean, opcional | Se a empresa deve ser exibida no site do Blue Button |
| `push_notifications` | boolean, opcional | Se as notificações push (console) estão ativadas |

#### `update_tax_info` (escrita)

Atualiza as informações fiscais/de nota fiscal. Informe os campos que precisam ser atualizados. O documento fiscal deve ser CPF (11 dígitos) ou CNPJ (14 dígitos); o CEP deve ter 8 dígitos; o código do município deve ser um código IBGE válido de 7 dígitos (use lookup_municipality_code primeiro).

- `POST /rest/v1/tools/update_tax_info`

| Parâmetros | | |
|---|---|---|
| `tax_name` | string, opcional | Nome registrado para fins fiscais (empresa ou pessoa) |
| `tax_document` | string, opcional | Documento fiscal, somente dígitos: CPF (11) ou CNPJ (14) |
| `street` | string, opcional | Nome da rua |
| `number` | string, opcional | Número do endereço |
| `neighborhood` | string, opcional | Bairro |
| `cep` | string, opcional | Código postal (CEP, 8 dígitos) |
| `municipality_code` | integer, opcional | Código de município do IBGE (7 dígitos) |

#### `update_user_name` (escrita)

Atualiza o nome de exibição do cliente.

- `POST /rest/v1/tools/update_user_name`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O novo nome do cliente |

### Membros da equipe

Quem mais está na conta — adiciona, lista e remove membros.

#### `add_member` (escrita)

Adiciona outra pessoa (um número de telefone adicional) a esta conta. Ela recebe sua própria conversa com o agente, mas com acesso total compartilhado à mesma empresa, configurações e prospecção. Falha se o número de telefone já pertencer a alguma conta.

- `POST /rest/v1/tools/add_member`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O nome da pessoa |
| `phone_number` | string, obrigatório | O número de telefone da pessoa em formato internacional, por exemplo, +5511999999999 |
| `email` | string, opcional | E-mail opcional — quando definido, a pessoa recebe cópias das notificações por e-mail (e-mails de lead interessado/confirmado) |

#### `list_members` (leitura)

Lista todos nesta conta: o proprietário da conta mais quaisquer pessoas adicionais que tenham sido adicionadas.

- `POST /rest/v1/tools/list_members`
- `GET /rest/v1/call/list_members`

Parâmetros: —

#### `remove_member` (destrutiva)

Remove uma pessoa adicional desta conta, identificada por nome ou número de telefone. O proprietário da conta não pode ser removido.

- `POST /rest/v1/tools/remove_member`

| Parâmetros | | |
|---|---|---|
| `name_or_phone` | string, obrigatório | O nome ou número de telefone da pessoa a ser removida |

### Tokens de acesso

Gerencia os tokens que autenticam esta conexão: lista, cria um novo, revoga.

#### `generate_mcp_token` (escrita)

Cria um novo token de acesso MCP para esta conta. O valor do token é retornado UMA VEZ e nunca mais — repasse-o imediatamente para quem chamou e diga para armazená-lo com segurança.

- `POST /rest/v1/tools/generate_mcp_token`

| Parâmetros | | |
|---|---|---|
| `label` | string, opcional | Um rótulo curto nomeando o que vai usar esse token, por exemplo 'n8n workflow' |

#### `list_mcp_tokens` (leitura)

Lista os tokens de acesso MCP da conta. Os valores dos tokens em si nunca são retornados — apenas o id, o label, a data de criação, a data de último uso e se o token foi revogado.

- `POST /rest/v1/tools/list_mcp_tokens`
- `GET /rest/v1/call/list_mcp_tokens`

Parâmetros: —

#### `revoke_mcp_token` (destrutiva)

Revoga um token de acesso MCP para que ele não possa mais se conectar. Use list_mcp_tokens para encontrar o token_id. Revogar o token com o qual quem está chamando está atualmente autenticado encerra imediatamente o próprio acesso.

- `POST /rest/v1/tools/revoke_mcp_token`

| Parâmetros | | |
|---|---|---|
| `token_id` | integer, obrigatório | O id do token a ser revogado, obtido em list_mcp_tokens |

### Eventos e webhooks

O feed de eventos da conta com cursor, mais as assinaturas de webhook de saída — cria, lista, testa e remove.

#### `create_webhook_subscription` (escrita)

Registra um endpoint de webhook HTTPS que recebe eventos da conta conforme eles acontecem (POSTs assinados) — para sistemas de automação que o cliente executa (apps do Agent SDK, n8n, Zapier, backends personalizados). O segredo de assinatura é retornado UMA VEZ nesta resposta — armazene-o com segurança. Observação: isso NÃO envia para esta sessão MCP; agentes que só conseguem fazer polling devem usar list_account_events.

- `POST /rest/v1/tools/create_webhook_subscription`

| Parâmetros | | |
|---|---|---|
| `url` | string, obrigatório | O endpoint HTTPS para o qual os eventos serão enviados via POST |
| `event_types` | string, opcional | Tipos de evento separados por vírgula a serem entregues (opcional; padrão = todos). Mesmos valores de list_account_events. |
| `description` | string, opcional | Um rótulo curto para esta assinatura (ex.: 'meu fluxo n8n') |

#### `delete_webhook_subscription` (destrutiva)

Exclui uma assinatura de webhook — as entregas para seu endpoint param imediatamente. Irreversível (crie uma nova assinatura para retomar; ela receberá um novo segredo).

- `POST /rest/v1/tools/delete_webhook_subscription`

| Parâmetros | | |
|---|---|---|
| `subscription_id` | integer, obrigatório | ID da assinatura (de list_webhook_subscriptions) |

#### `list_account_events` (leitura)

Faça polling no feed de eventos da conta — novas respostas de leads (e-mail/WhatsApp), leads sinalizados para revisão, leads se tornando interested/confirmed, reuniões marcadas/canceladas, chamadas de voz finalizadas, importações finalizadas, suporte respondido. Paginado por cursor: passe o next_cursor da chamada anterior para obter apenas o que aconteceu desde então. Isso é sobre ATIVIDADE DA CONTA — não eventos de calendário (list_calendar_events / list_calendly_upcoming_events) e não o histórico de um lead (list_lead_lifecycle_events).

- `POST /rest/v1/tools/list_account_events`
- `GET /rest/v1/call/list_account_events`

| Parâmetros | | |
|---|---|---|
| `since_cursor` | integer, opcional, padrão `0` | Retorna somente eventos com id maior que este valor (0 = desde o início do feed). Use o next_cursor da chamada anterior. |
| `event_types` | string, opcional | Tipos de evento separados por vírgula para incluir (opcional; padrão = todos). Válidos: lead_replied_email, lead_replied_whatsapp, lead_sent_for_human_review, lead_became_interested, lead_confirmed, meeting_booked, meeting_cancelled, voice_call_finished, import_finished, support_request_answered |
| `limit` | integer, opcional, padrão `50` | Máximo de eventos a retornar (padrão 50, máximo 200) |

#### `list_webhook_subscriptions` (leitura)

Lista as assinaturas de webhook da conta com a saúde de entrega (último sucesso/falha, falhas consecutivas, estado desabilitado). Os secrets nunca são exibidos novamente.

- `POST /rest/v1/tools/list_webhook_subscriptions`
- `GET /rest/v1/call/list_webhook_subscriptions`

Parâmetros: —

#### `test_webhook_subscription` (escrita)

Envia um evento de teste 'ping' assinado para o endpoint de uma assinatura de webhook, para que o cliente possa verificar o receptor e a checagem de assinatura. O resultado da entrega aparece em list_webhook_subscriptions (date_last_success / last_failure_reason) em cerca de 1 minuto.

- `POST /rest/v1/tools/test_webhook_subscription`

| Parâmetros | | |
|---|---|---|
| `subscription_id` | integer, obrigatório | ID da assinatura (de list_webhook_subscriptions) |

### Integrações de CRM

Conecta e desconecta um CRM, consulta o status de sincronização, força uma nova sincronização, mapeia campos personalizados e gerencia as integrações Apollo, Lusha e RD Station.

#### `connect_crm` (escrita)

Conecta uma integração de CRM. Cada CRM precisa de credenciais diferentes: Pipedrive (api_key), RdStation (marketing_api_key e/ou crm_token), HubSpot (access_token), Odoo (url + database + username + api_key), Omie (app_key + app_secret), Agendor/ExactSales/Piperun/Venttra (api_token), SystemeIo (api_key). Requer um plano pago ativo. A credencial é VERIFICADA AO VIVO junto ao provedor antes de ser armazenada (uma chave inválida retorna um erro e nada é armazenado); o campo 'verified' da resposta indica se a verificação foi possível — ExactSales, Piperun, Venttra e a chave marketing do RdStation são APIs somente de escrita e são armazenadas sem verificação.

- `POST /rest/v1/tools/connect_crm`

| Parâmetros | | |
|---|---|---|
| `crm_name` | string, obrigatório | Nome do CRM: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra |
| `api_key` | string, opcional | Chave de API (Pipedrive, Odoo, SystemeIo) |
| `api_token` | string, opcional | Token de API (Agendor, ExactSales, Piperun, Venttra) |
| `access_token` | string, opcional | Token de acesso (HubSpot) |
| `url` | string, opcional | URL (Odoo) |
| `database` | string, opcional | Nome do banco de dados (Odoo) |
| `username` | string, opcional | Nome de usuário (Odoo) |
| `app_key` | string, opcional | Chave do app (Omie) |
| `app_secret` | string, opcional | Segredo do app (Omie) |
| `marketing_api_key` | string, opcional | Chave de API de marketing (RdStation) |
| `crm_token` | string, opcional | Token do CRM (RdStation) |
| `pipeline_id` | integer, opcional | ID do pipeline em que os negócios são criados (Pipedrive) |
| `funnel_id` | integer, opcional | Id do funil em que os negócios são criados (Agendor) |

#### `disconnect_crm` (destrutiva)

Desconecta uma integração de CRM limpando suas credenciais.

- `POST /rest/v1/tools/disconnect_crm`

| Parâmetros | | |
|---|---|---|
| `crm_name` | string, obrigatório | Nome do CRM: Pipedrive, RdStation, HubSpot, Odoo, Omie, Agendor, ExactSales, Piperun, SystemeIo, Venttra |

#### `get_crm_sync_status` (leitura)

Mostra quantos leads foram sincronizados com cada CRM conectado: contagens de synced, pending e stuck, o horário da última sincronização, e alguns nomes de leads sincronizados recentemente.

- `POST /rest/v1/tools/get_crm_sync_status`
- `GET /rest/v1/call/get_crm_sync_status`

Parâmetros: —

#### `list_crm_integrations` (leitura)

Liste todas as integrações de CRM com seu status de conexão, o filtro de status mínimo de lead para sincronização com o CRM e os campos personalizados configurados.

- `POST /rest/v1/tools/list_crm_integrations`
- `GET /rest/v1/call/list_crm_integrations`

Parâmetros: —

#### `manage_apollo_integration` (escrita)

Conecta ou desconecta a integração da fonte de leads Apollo. Requer um plano pago ativo. action: 'connect' (precisa de api_key) ou 'disconnect'. A api_key é verificada em tempo real junto à Apollo antes de ser armazenada — uma chave inválida retorna um erro e não armazena nada.

- `POST /rest/v1/tools/manage_apollo_integration`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: connect ou disconnect |
| `api_key` | string, opcional | Chave de API do Apollo (obrigatória para connect) |
| `list_id` | string, opcional | Id da lista do Apollo para sincronizar leads (opcional) |

#### `manage_crm_custom_fields` (escrita)

Gerencia campos personalizados enviados com cada lead para as integrações de CRM. action: 'list', 'add' (precisa de field_name + field_value) ou 'remove' (precisa de field_id).

- `POST /rest/v1/tools/manage_crm_custom_fields`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: list, add, ou remove |
| `field_name` | string, opcional | Nome do campo (obrigatório para 'add') |
| `field_value` | string, opcional | Valor do campo (obrigatório para 'add') |
| `field_id` | integer, opcional | Id do campo (obrigatório para 'remove') |

#### `manage_lusha_integration` (escrita)

Conecta ou desconecta a integração da fonte de leads Lusha. Requer um plano pago ativo. action: 'connect' (precisa de api_key) ou 'disconnect'. A api_key é verificada em tempo real junto à Lusha antes de ser armazenada — uma chave inválida retorna um erro e não armazena nada.

- `POST /rest/v1/tools/manage_lusha_integration`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: connect ou disconnect |
| `api_key` | string, opcional | Chave de API do Lusha (obrigatória para connect) |
| `list_id` | string, opcional | ID da lista do Lusha para sincronizar leads (opcional) |

#### `manage_rd_station_crm_lead_source` (escrita)

Ativa ou desativa a importação de contatos do RD Station CRM como leads de prospecção. Requer um plano pago ativo e que o token do RD Station CRM já esteja conectado (use connect_crm). action: 'enable' (opcionalmente delimitado por pipeline_id e deal_stage_id para que apenas contatos vinculados a negócios ali sejam importados) ou 'disable'. Ativar verifica em tempo real o token armazenado junto ao RD Station CRM antes. Não afeta a sincronização de saída de leads para o CRM.

- `POST /rest/v1/tools/manage_rd_station_crm_lead_source`

| Parâmetros | | |
|---|---|---|
| `action` | string, obrigatório | Ação: enable ou disable |
| `pipeline_id` | string, opcional | ID do pipeline de negócios do RD Station CRM para limitar a importação (opcional; omita para importar todos os contatos) |
| `deal_stage_id` | string, opcional | ID da etapa do negócio do RD Station CRM dentro do pipeline para limitar a importação (opcional; requer pipeline_id) |

#### `resync_crm_leads` (escrita)

Recoloca manualmente na fila os leads elegíveis que ainda não foram enviados ao CRM para que a sincronização em segundo plano tente novamente. Leads já sincronizados nunca são reenviados (sem duplicatas). O envio acontece em segundo plano em poucos minutos.

- `POST /rest/v1/tools/resync_crm_leads`

Parâmetros: —

#### `update_crm_minimum_status` (escrita)

Define o status mínimo do lead exigido antes de o lead ser sincronizado com o CRM (Pending, Cold, Confirmed, Aware, NotInterested, Interested). Omita 'status' para limpar o filtro e sincronizar todos os leads.

- `POST /rest/v1/tools/update_crm_minimum_status`

| Parâmetros | | |
|---|---|---|
| `status` | string, opcional | Status mínimo do lead para sincronização com o CRM. Omitir para sincronizar todos os leads. |

### Calendly

Conecta o Calendly, escolhe o tipo de evento em que os leads são agendados e lê os próximos agendamentos.

#### `disconnect_calendly` (destrutiva)

Desconecta a conta do Calendly do cliente: exclui a assinatura de webhook do lado do Calendly, revoga o token de acesso e limpa todos os campos armazenados do Calendly. Passe user_has_confirmed=true somente quando o usuário tiver confirmado explicitamente que deseja desconectar.

- `POST /rest/v1/tools/disconnect_calendly`

| Parâmetros | | |
|---|---|---|
| `user_has_confirmed` | boolean, obrigatório | Deve ser true — o agente precisa ter confirmação explícita do usuário antes de desconectar. |

#### `get_calendly_connection_url` (leitura)

Retorna a URL em que o usuário deve clicar para conectar a conta do Calendly ao Eesier. Compartilhe essa URL com o usuário — ele a abre, faz login no Calendly, clica em Authorize, e a conexão é estabelecida no lado do servidor. Depois que o usuário concluir o fluxo, chame get_calendly_status novamente para confirmar. Idempotente: retorna a mesma URL independentemente de o Calendly já estar conectado ou não (para que o usuário possa reconectar com uma conta diferente).

- `POST /rest/v1/tools/get_calendly_connection_url`
- `GET /rest/v1/call/get_calendly_connection_url`

Parâmetros: —

#### `get_calendly_event` (leitura)

Retorna os detalhes completos de um evento agendado específico do Calendly, incluindo a lista de convidados com seus nomes, e-mails, status, e quaisquer respostas que tenham dado às perguntas de agendamento. Use isso para perguntas de acompanhamento sobre uma reunião específica depois de list_calendly_upcoming_events.

- `POST /rest/v1/tools/get_calendly_event`
- `GET /rest/v1/call/get_calendly_event`

| Parâmetros | | |
|---|---|---|
| `event_uri` | string, obrigatório | URI completa do evento agendado do Calendly (por exemplo 'https://api.calendly.com/scheduled_events/'). Obtenha em list_calendly_upcoming_events. |

#### `get_calendly_status` (leitura)

Retorna o status atual da conexão do Calendly para o cliente: se o OAuth está conectado, o e-mail da conta do Calendly conectada, e qual tipo de evento (se houver) está selecionado como padrão para os links de prospecção.

- `POST /rest/v1/tools/get_calendly_status`
- `GET /rest/v1/call/get_calendly_status`

Parâmetros: —

#### `list_calendly_event_types` (leitura)

Lista todos os tipos de evento ativos na conta Calendly do cliente (ex.: '15-min intro call', '30-min consultation'). Cada entrada inclui uri (use isto ao chamar set_calendly_default_event_type), name, slug, duration_minutes, scheduling_url e is_default. Obrigatório: o Calendly deve estar conectado primeiro.

- `POST /rest/v1/tools/list_calendly_event_types`
- `GET /rest/v1/call/list_calendly_event_types`

Parâmetros: —

#### `list_calendly_upcoming_events` (leitura)

Lista os eventos do Calendly agendados no calendário do cliente dentro de um intervalo de datas. Use isto para pedidos no estilo 'o que tenho na minha agenda' / 'tenho alguma reunião amanhã'. Os `start_utc`/`end_utc` retornados vêm em UTC — obtenha `timezone_offset_utc_hours` de `whoami` e converta antes de mostrá-los ao usuário. O Calendly impõe um intervalo máximo de 100 dias.

- `POST /rest/v1/tools/list_calendly_upcoming_events`
- `GET /rest/v1/call/list_calendly_upcoming_events`

| Parâmetros | | |
|---|---|---|
| `start_date` | string, opcional | Início da janela no formato YYYY-MM-DD (UTC, inclusive). O padrão é a data UTC de hoje, se omitido. |
| `end_date` | string, opcional | Fim da janela no formato YYYY-MM-DD (UTC, INCLUSIVE — eventos em qualquer horário deste dia são retornados). O padrão é 7 dias após start_date. |
| `status` | string, opcional, padrão `active` | Filtro de status: 'active' (padrão — reservas confirmadas) ou 'canceled'. |

#### `set_calendly_default_event_type` (escrita)

Define o tipo de evento padrão do Calendly. O padrão é o tipo de evento que o Blue Button usa ao gerar links de agendamento dentro das conversas com leads. Passe event_type_uri (preferido — obtenha-o com list_calendly_event_types) ou event_type_name (correspondência aproximada com os tipos de evento ativos). Passe event_type_uri vazio para limpar o padrão.

- `POST /rest/v1/tools/set_calendly_default_event_type`

| Parâmetros | | |
|---|---|---|
| `event_type_uri` | string, opcional | URI completa do tipo de evento do Calendly (preferencial). Passe uma string vazia para limpar o padrão atual. |
| `event_type_name` | string, opcional | Ou o nome de exibição do tipo de evento — comparado por correspondência aproximada com os tipos de evento ativos do cliente. Usado apenas quando event_type_uri não é fornecido. |

### Google Agenda

Conecta o Google Agenda e mexe na agenda: lista, cria, atualiza, exclui e responde a eventos.

#### `create_calendar_event` (escrita)

Cria um evento no Google Calendar. Os horários são em UTC — converta o horário local do cliente usando timezone_offset_utc_hours de whoami ANTES de chamar. Retorna o id do evento e um link do Meet quando um foi gerado.

- `POST /rest/v1/tools/create_calendar_event`

| Parâmetros | | |
|---|---|---|
| `summary` | string, obrigatório | Título do evento |
| `start_utc` | string, obrigatório | Início do evento em UTC, formato ISO (ex: 2026-07-10T14:00:00Z) |
| `end_utc` | string, obrigatório | Término do evento em UTC, formato ISO |
| `attendees` | string, opcional | E-mails dos participantes separados por vírgula |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `delete_calendar_event` (destrutiva)

Exclui um evento do Google Calendar. Isso cancela o evento para todos os participantes e não pode ser desfeito.

- `POST /rest/v1/tools/delete_calendar_event`

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `get_google_connection_url` (leitura)

Obtém a URL do OAuth para o cliente conectar a conta do Google (necessária para as ferramentas do Google Calendar). Compartilhe a URL com o usuário; a conexão é concluída no lado do servidor depois que ele autorizar. Idempotente — também funciona para reconectar.

- `POST /rest/v1/tools/get_google_connection_url`
- `GET /rest/v1/call/get_google_connection_url`

Parâmetros: —

#### `list_calendar_events` (leitura)

Liste os eventos do Google Calendar do cliente para um dia do calendário (UTC). Retorna start/end no formato ISO UTC.

- `POST /rest/v1/tools/list_calendar_events`
- `GET /rest/v1/call/list_calendar_events`

| Parâmetros | | |
|---|---|---|
| `date` | string, obrigatório | O dia a ser listado, yyyy-MM-dd (interpretado em UTC) |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `respond_calendar_event` (escrita)

Aceita ou recusa um convite de evento do Google Calendar em nome do cliente.

- `POST /rest/v1/tools/respond_calendar_event`

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `accept` | boolean, obrigatório | true para aceitar o convite, false para recusar |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

#### `update_calendar_event` (escrita)

Atualiza um evento do Google Calendar (título, horários, participantes). Passe apenas os campos a alterar. Os horários estão em UTC.

- `POST /rest/v1/tools/update_calendar_event`

| Parâmetros | | |
|---|---|---|
| `event_id` | string, obrigatório | ID do evento do calendário |
| `summary` | string, opcional | Novo título do evento |
| `start_utc` | string, opcional | Novo horário de início em UTC, formato ISO |
| `end_utc` | string, opcional | Novo horário de término em UTC, formato ISO |
| `attendees` | string, opcional | Novos e-mails dos participantes, separados por vírgula (substitui a lista atual) |
| `calendar_id` | string, opcional, padrão `primary` | ID do calendário (padrão 'primary') |

### Google Ads

O lado pago: campanhas, orçamentos, faturamento, relatórios de performance, diagnóstico, grupos de anúncios, palavras-chave, negativas, anúncios de busca e públicos.

#### `add_google_ads_keywords` (escrita)

Adiciona palavras-chave a um grupo de anúncios em uma campanha do Google Ads. Uma palavra-chave por linha no parâmetro keywords (as palavras-chave podem conter vírgulas). match_type: Broad, Phrase ou Exact (padrão Broad).

- `POST /rest/v1/tools/add_google_ads_keywords`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |
| `keywords` | string, obrigatório | As palavras-chave a serem adicionadas, UMA POR LINHA |
| `match_type` | string, opcional | Tipo de correspondência: Broad (padrão), Phrase, ou Exact |

#### `add_google_ads_negative_keywords` (escrita)

Adiciona palavras-chave negativas EM NÍVEL DE CAMPANHA a uma campanha do Google Ads (buscas por esses termos nunca acionarão anúncios). Uma palavra-chave por linha. match_type: Broad (padrão), Phrase ou Exact.

- `POST /rest/v1/tools/add_google_ads_negative_keywords`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `keywords` | string, obrigatório | As palavras-chave negativas a serem adicionadas, UMA POR LINHA |
| `match_type` | string, opcional | Tipo de correspondência: Broad (padrão), Phrase, ou Exact |

#### `create_google_ads_campaign_draft` (escrita)

Cria uma NOVA campanha do Google Ads como RASCUNHO. Ela NÃO veicula até que o cliente recarregue seu saldo através do recharge_url do console retornado — compartilhe esse link e nunca afirme que a campanha está no ar. channel_type: Search (padrão) ou PerformanceMax (recomende o PMax somente depois que uma campanha Search tiver dados reais de conversão).

- `POST /rest/v1/tools/create_google_ads_campaign_draft`

| Parâmetros | | |
|---|---|---|
| `name` | string, obrigatório | O nome da campanha como aparecerá no Google Ads |
| `daily_budget_brl` | number, obrigatório | Orçamento diário em BRL (positivo, ex.: 20) |
| `channel_type` | string, opcional | Tipo de canal: Search (padrão) ou PerformanceMax |

#### `create_google_ads_search_ad` (escrita)

Cria um Responsive Search Ad em um grupo de anúncios de uma campanha do Google Ads. Títulos com no máximo 30 caracteres cada, descrições com no máximo 90 caracteres cada — UM POR LINHA. Forneça pelo menos 3 títulos e 2 descrições.

- `POST /rest/v1/tools/create_google_ads_search_ad`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |
| `final_url` | string, obrigatório | A URL da página de destino para a qual o anúncio direciona |
| `headlines` | string, obrigatório | Os títulos do anúncio, UM POR LINHA, máximo de 30 caracteres cada |
| `descriptions` | string, obrigatório | As descrições do anúncio, UMA POR LINHA, máximo de 90 caracteres cada |

#### `diagnose_google_ads_campaign` (leitura)

Diagnostica por que uma campanha do Google Ads está (ou não está) veiculando: status de veiculação ao vivo, status primário com motivos, e status de aprovação/revisão por anúncio.

- `POST /rest/v1/tools/diagnose_google_ads_campaign`
- `GET /rest/v1/call/diagnose_google_ads_campaign`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `get_google_ads_audience_status` (leitura)

Obtém o status do público do Customer Match de uma campanha do Google Ads: quantos e-mails estavam no último upload, quando, e se a lista está anexada.

- `POST /rest/v1/tools/get_google_ads_audience_status`
- `GET /rest/v1/call/get_google_ads_audience_status`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `get_google_ads_billing` (leitura)

Lê os dados de cobrança/financiamento do Google Ads da conta de uma campanha. section: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices (precisa de year+month), ou CampaignBudgets.

- `POST /rest/v1/tools/get_google_ads_billing`
- `GET /rest/v1/call/get_google_ads_billing`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `section` | string, obrigatório | Seção: AccountInfo, AccountBudgets, BillingSetups, Proposals, Invoices, CampaignBudgets |
| `year` | integer, opcional | Ano de emissão da fatura (somente Invoices) |
| `month` | integer, opcional | Mês de emissão da fatura 1-12 (somente Invoices) |

#### `get_google_ads_campaign` (leitura)

Obtém o detalhe completo de uma campanha do Google Ads: status do ciclo de vida, motivo da suspensão, saldo de financiamento, o snapshot de desempenho armazenado (spend, impressions, clicks, conversions, CTR, CPC), e o link de gerenciamento/recarga do console. Passe o nome ou o id da campanha.

- `POST /rest/v1/tools/get_google_ads_campaign`
- `GET /rest/v1/call/get_google_ads_campaign`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha (de list_google_ads_campaigns) |

#### `get_google_ads_keyword_ideas` (leitura)

Obtém ideias de palavras-chave com volume de busca do Keyword Planner do Google para uma campanha. Forneça palavras-chave semente (uma por linha) e/ou uma URL de página para extrair ideias.

- `POST /rest/v1/tools/get_google_ads_keyword_ideas`
- `GET /rest/v1/call/get_google_ads_keyword_ideas`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `seed_keywords` | string, opcional | Palavras-chave iniciais, UMA POR LINHA |
| `page_url` | string, opcional | Uma URL de página para extrair ideias de palavras-chave |
| `max_results` | integer, opcional, padrão `50` | Número máximo de resultados (padrão 50) |

#### `get_google_ads_performance_report` (leitura)

Extrai um relatório de desempenho AO VIVO do Google Ads para uma campanha. report_type: Campaign (totais), AdGroup, Keyword (com pontuação de qualidade), Ad, SearchTerms (o que os usuários realmente pesquisaram), Daily, Device, Conversion, ImpressionShare (parcela de impressões + % perdida por orçamento vs. classificação), AdAssets (rótulos LOW/GOOD/BEST por título/descrição), Hourly, Geographic, Demographics. Custos em BRL.

- `POST /rest/v1/tools/get_google_ads_performance_report`
- `GET /rest/v1/call/get_google_ads_performance_report`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `report_type` | string, obrigatório | Tipo de relatório: Campaign, AdGroup, Keyword, Ad, SearchTerms, Daily, Device, Conversion, ImpressionShare, AdAssets, Hourly, Geographic, Demographics |
| `date_range` | string, opcional | Intervalo de datas: um predefinido (LAST_7_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_MONTH, LAST_MONTH) ou uma janela personalizada 'yyyy-MM-dd AND yyyy-MM-dd'. Padrão LAST_30_DAYS. |

#### `list_google_ads_ad_groups` (leitura)

Liste os grupos de anúncios de uma campanha do Google Ads (id, name, status, CPC bid). Os ids de grupo de anúncios são necessários para as ferramentas de palavra-chave e anúncio.

- `POST /rest/v1/tools/list_google_ads_ad_groups`
- `GET /rest/v1/call/list_google_ads_ad_groups`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `list_google_ads_campaigns` (leitura)

Lista as campanhas do Google Ads do cliente com status, tipo de canal, orçamento diário, motivo da retenção, e saldo (recarregado, gasto, restante) — tudo em BRL. O ponto de entrada: chame esta primeiro, depois passe um name ou id retornado para as outras ferramentas google_ads.

- `POST /rest/v1/tools/list_google_ads_campaigns`
- `GET /rest/v1/call/list_google_ads_campaigns`

Parâmetros: —

#### `list_google_ads_keywords` (leitura)

Lista as palavras-chave de um grupo de anúncios em uma campanha do Google Ads (texto, tipo de correspondência, status, lance de CPC, índice de qualidade).

- `POST /rest/v1/tools/list_google_ads_keywords`
- `GET /rest/v1/call/list_google_ads_keywords`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `ad_group_id` | integer, obrigatório | O id do grupo de anúncios (de list_google_ads_ad_groups) |

#### `nudge_google_ads_provisioning` (escrita)

Executa novamente o gate de provisionamento de go-live de uma campanha do Google Ads que parece travada após ser financiada (empurra a máquina de estados de provisionamento adiante).

- `POST /rest/v1/tools/nudge_google_ads_provisioning`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome ou id da campanha |

#### `refresh_google_ads_audience` (escrita)

Reenvia o público do Customer Match da campanha do Google Ads a partir dos e-mails atuais dos leads do cliente (mantém a lista de remarketing atualizada). Retorna o número de e-mails enviados.

- `POST /rest/v1/tools/refresh_google_ads_audience`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | Nome ou id da campanha |

#### `set_google_ads_campaign_status` (destrutiva)

Pausa, retoma, ou ENCERRA uma campanha do Google Ads. Retomar depende do saldo restante + pelo menos um anúncio habilitado (e uma palavra-chave para Search). ENCERRAR É IRREVERSÍVEL — isso remove a campanha no Google Ads; obtenha a confirmação explícita do cliente antes de encerrar.

- `POST /rest/v1/tools/set_google_ads_campaign_status`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `action` | string, obrigatório | Ação: Pause, Resume ou End (End é irreversível) |

#### `sync_google_ads_spend` (escrita)

Atualiza o gasto de uma campanha do Google Ads a partir da API ao vivo do Google (atualiza o snapshot armazenado e os cálculos de financiamento). Chame isso antes de informar números de gasto ou saldo ao cliente.

- `POST /rest/v1/tools/sync_google_ads_spend`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |

#### `update_google_ads_campaign_budget` (escrita)

Atualiza o orçamento diário de uma campanha do Google Ads (BRL). Retorna o valor efetivo após o ajuste de limites da plataforma.

- `POST /rest/v1/tools/update_google_ads_campaign_budget`

| Parâmetros | | |
|---|---|---|
| `campaign` | string, obrigatório | O nome ou id da campanha |
| `new_daily_budget_brl` | number, obrigatório | O novo orçamento diário em BRL |

### Sites

Cadastra um site e altera por conversa: configurações, subdomínio, código-fonte, snapshots e restaurações, capturas de tela e rastreamento.

#### `archive_website` (destrutiva)

Arquiva (remove) um site.

- `POST /rest/v1/tools/archive_website`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site a ser arquivado |

#### `cancel_website_change` (destrutiva)

Cancela a solicitação de alteração em andamento (não concluída) de um site.

- `POST /rest/v1/tools/cancel_website_change`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `change_website` (escrita)

Solicita uma alteração em um site. A alteração é enfileirada e renderizada em segundo plano — isso retorna imediatamente com um code id; consulte get_website para verificar a conclusão.

- `POST /rest/v1/tools/change_website`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site a ser alterado |
| `prompt` | string, obrigatório | Prompt descrevendo a alteração desejada |
| `data_storage_required` | boolean, opcional, padrão `false` | True se a alteração exigir armazenamento de dados (um banco de dados) |
| `ignore_existing_code` | boolean, opcional, padrão `false` | True para ignorar o código existente e reconstruir do zero (reformulação completa) |
| `reasoning_mode` | string, opcional | Raciocínio do agente de código: Fast (alterações simples, padrão) ou Thinking (alterações complexas) |
| `generation_type` | string, opcional | Tipo de geração: Fast (padrão) ou Quality |

#### `change_website_subdomain` (escrita)

Altera o subdomínio de um site (a parte antes de .eesier.website).

- `POST /rest/v1/tools/change_website_subdomain`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |
| `new_subdomain` | string, obrigatório | Nova parte do subdomínio sem o sufixo .eesier.website (apenas letras, números e hífens) |

#### `crawl_website` (leitura)

Busca o HTML bruto de uma página da web, dividido em blocos de 1000 caracteres navegáveis por índice.

- `POST /rest/v1/tools/crawl_website`
- `GET /rest/v1/call/crawl_website`

| Parâmetros | | |
|---|---|---|
| `url` | string, obrigatório | URL da página web a ser buscada |
| `chunk_index` | integer, opcional, padrão `0` | Índice do trecho a ser retornado (começando em 0) |

#### `create_website_snapshot` (escrita)

Cria um snapshot do código atual de um site, marcado com uma descrição, para que possa ser restaurado depois.

- `POST /rest/v1/tools/create_website_snapshot`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |
| `snapshot_description` | string, obrigatório | Descrição para o snapshot |

#### `export_website_code` (escrita)

Exporta o código atual de um site para um arquivo HTML e o envia por e-mail para o endereço fornecido.

- `POST /rest/v1/tools/export_website_code`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do website |
| `email_address` | string, obrigatório | Endereço de email de destino |

#### `get_website` (leitura)

Obtenha informações completas sobre um site: título, URL, tipo, idioma, status de geração e link do editor de código.

- `POST /rest/v1/tools/get_website`
- `GET /rest/v1/call/get_website`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `get_website_code` (leitura)

Obtenha o código HTML de uma entrada específica de código do site.

- `POST /rest/v1/tools/get_website_code`
- `GET /rest/v1/call/get_website_code`

| Parâmetros | | |
|---|---|---|
| `website_code_id` | integer, obrigatório | Id da entrada de código do site |

#### `get_website_settings` (leitura)

Obtenha as configurações configuráveis de um site (título, idioma, restrição, diretrizes do agente).

- `POST /rest/v1/tools/get_website_settings`
- `GET /rest/v1/call/get_website_settings`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_website_code` (leitura)

Lista as gerações de código bem-sucedidas para um site (sem o HTML em si), mais recentes primeiro.

- `POST /rest/v1/tools/list_website_code`
- `GET /rest/v1/call/list_website_code`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_website_snapshots` (leitura)

Lista os snapshots de um site (versões salvas do código), mais recentes primeiro.

- `POST /rest/v1/tools/list_website_snapshots`
- `GET /rest/v1/call/list_website_snapshots`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do site |

#### `list_websites` (leitura)

Lista todos os sites do cliente com seu status de geração, URL, e link do editor de código.

- `POST /rest/v1/tools/list_websites`
- `GET /rest/v1/call/list_websites`

Parâmetros: —

#### `register_website` (escrita)

Registra um novo site gerado por IA. A geração roda em segundo plano — isso retorna imediatamente com um id; faça polling de get_website / list_websites para a URL final e o status.

- `POST /rest/v1/tools/register_website`

| Parâmetros | | |
|---|---|---|
| `description` | string, obrigatório | Descrição concisa mas completa do site: propósito, principais funcionalidades, público-alvo, estilo e o que vende/promove |
| `language` | string, obrigatório | Código de idioma no formato xx-xx, ex.: pt-br, en-us |
| `application_type` | string, opcional | Tipo de aplicação: Website (padrão) ou LeadCapturePage. Para um site interativo com logins/dashboards, mantenha Website e defina data_storage_required=true. |
| `generation_type` | string, opcional | Tipo de geração: Fast (padrão, sites mais simples) ou Quality (mais lento, melhor para sites complexos) |
| `data_storage_required` | boolean, opcional, padrão `false` | True se o site precisar de armazenamento de dados persistente (contas, pedidos, dashboards); false para sites estáticos. Padrão false. |
| `restricted` | boolean, opcional, padrão `false` | True para restringir o site atrás de uma página de login; false para público. Padrão false. |
| `copy_from_website_id` | integer, opcional | Id opcional de outro site deste cliente para copiar o código |
| `business_or_brand_name` | string, opcional | Nome opcional da empresa/marca existente para a qual o site é destinado (aciona pesquisa online para conteúdo e branding) |

#### `restore_website_snapshot` (destrutiva)

Restaura um snapshot (ou qualquer entrada de código anterior) como o código atual do site.

- `POST /rest/v1/tools/restore_website_snapshot`

| Parâmetros | | |
|---|---|---|
| `website_code_id` | integer, obrigatório | Id da entrada de código do site a ser restaurada |

#### `screenshot_website` (escrita)

Tira um screenshot de qualquer URL pública e o analisa com IA. Salva o screenshot como um arquivo do cliente e retorna a análise + URL pública da imagem. Opcionalmente, envia o screenshot por e-mail.

- `POST /rest/v1/tools/screenshot_website`

| Parâmetros | | |
|---|---|---|
| `url` | string, obrigatório | URL pública a ser capturada |
| `prompt` | string, obrigatório | Prompt/instruções para a análise de IA |
| `viewport_width` | integer, opcional, padrão `1366` | Largura do viewport em px (padrão 1366) |
| `viewport_height` | integer, opcional, padrão `768` | Altura do viewport em px (padrão 768) |
| `send_to_email` | string, opcional | Endereço de e-mail opcional para enviar a captura de tela |
| `screenshot_file_name` | string, opcional | Nome de arquivo opcional de uma palavra para a captura de tela |

#### `set_website_settings` (escrita)

Atualiza as configurações de um site. Passe apenas os campos que deseja alterar.

- `POST /rest/v1/tools/set_website_settings`

| Parâmetros | | |
|---|---|---|
| `website_id` | integer, obrigatório | Id do website |
| `title` | string, opcional | Título do website (máx. 60 caracteres) |
| `language_key` | string, opcional | Chave de idioma, ex.: pt-BR, en-US |
| `restricted` | boolean, opcional | Se o website é restrito por login |
| `guidelines` | string, opcional | Diretrizes persistentes de como o agente deve trabalhar neste website |

### Páginas de captura

O lado inbound: cria páginas de captura, altera, lista e arquiva.

#### `archive_lead_capture_page` (destrutiva)

Arquiva (remove) uma página de captura de leads.

- `POST /rest/v1/tools/archive_lead_capture_page`

| Parâmetros | | |
|---|---|---|
| `lead_capture_page_id` | integer, obrigatório | Id da página de captura de leads |

#### `change_lead_capture_page` (escrita)

Solicita uma alteração em uma página de captura de leads. A alteração é enfileirada e renderizada em segundo plano — isso retorna imediatamente com um code id.

- `POST /rest/v1/tools/change_lead_capture_page`

| Parâmetros | | |
|---|---|---|
| `lead_capture_page_id` | integer, obrigatório | Id da página de captura de leads |
| `prompt` | string, obrigatório | Prompt descrevendo a alteração desejada |

#### `create_lead_capture_page` (escrita)

Cria uma página de captura de leads. A geração é executada em segundo plano — isso retorna imediatamente com um id; consulte list_lead_capture_pages para obter a URL finalizada.

- `POST /rest/v1/tools/create_lead_capture_page`

| Parâmetros | | |
|---|---|---|
| `description` | string, obrigatório | Descrição concisa, porém completa: quais informações capturar, público-alvo, a oferta/proposta de valor e quaisquer preferências de design |
| `language` | string, obrigatório | Código de idioma no formato xx-xx, ex.: pt-br, en-us |

#### `list_lead_capture_pages` (leitura)

Lista todas as páginas de captura de leads do cliente com seu status de geração e URL.

- `POST /rest/v1/tools/list_lead_capture_pages`
- `GET /rest/v1/call/list_lead_capture_pages`

Parâmetros: —

### Mídia

Gera imagens, desenhos e vídeos, edita um vídeo e lê tudo que já foi gerado.

#### `create_video` (escrita)

Gera um vídeo curto de IA a partir de um prompt de texto e de uma imagem de referência opcional do primeiro frame. É renderizado em segundo plano — isso retorna imediatamente com um id; consulte list_videos para obter o video_url finalizado.

- `POST /rest/v1/tools/create_video`

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | O prompt do vídeo |
| `model` | string, opcional | Mecanismo: SeedancePro, SeedanceProFast (padrão), Grok |
| `reference_image_url` | string, opcional | URL opcional da imagem do primeiro frame (https absoluto). O vídeo anima a partir dessa imagem. |
| `duration` | integer, opcional | Duração em segundos (limitada de acordo com o mecanismo) |
| `aspect_ratio` | string, opcional | Proporção da imagem, ex.: 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, opcional | Resolução: 480p, 720p ou 1080p |

#### `edit_video` (escrita)

Gera um novo vídeo que itera sobre um gerado anteriormente. Quando nenhum reference_image_url é fornecido, a estratégia de frame inicial decide como o frame inicial é produzido.

- `POST /rest/v1/tools/edit_video`

| Parâmetros | | |
|---|---|---|
| `video_id` | integer, obrigatório | Id do vídeo gerado anteriormente sobre o qual iterar |
| `prompt` | string, obrigatório | O novo prompt do vídeo |
| `model` | string, opcional | Mecanismo: SeedancePro, SeedanceProFast (padrão), Grok |
| `reference_image_url` | string, opcional | URL opcional da nova imagem do primeiro frame (https absoluto). Substitui a estratégia. |
| `first_frame_strategy` | string, opcional | Como lidar com o primeiro frame: KeepPreviousFirstFrame (padrão), EditPreviousFirstFrame, GenerateBrandNewFirstFrame |
| `duration` | integer, opcional | Duração em segundos (limitada de acordo com o mecanismo) |
| `aspect_ratio` | string, opcional | Proporção da imagem, ex.: 16:9, 9:16, 1:1, 4:3 |
| `resolution` | string, opcional | Resolução: 480p, 720p ou 1080p |

#### `generate_drawing` (escrita)

Gera um desenho (formas, wireframes, layouts de página, diagramas, tabelas, gráficos, grids, formas vetoriais, mapas). É executado em segundo plano — isso retorna imediatamente com um id; consulte list_drawings para obter o image_url finalizado.

- `POST /rest/v1/tools/generate_drawing`

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | Descrição do drawing a ser gerado |
| `caption` | string, opcional | Legenda opcional para acompanhar a imagem entregue |
| `reference_image_url` | string, opcional | URL https absoluta opcional de uma imagem de referência para enviar com o prompt |
| `drawing_id` | integer, opcional | Id opcional de um drawing existente para editar/iterar |

#### `generate_image` (escrita)

Gera uma imagem a partir de um prompt de texto (ou edita imagens existentes passando URLs de referência). A geração é executada em segundo plano — isso retorna imediatamente com um id; consulte list_images para obter o image_url finalizado.

- `POST /rest/v1/tools/generate_image`

| Parâmetros | | |
|---|---|---|
| `prompt` | string, obrigatório | Prompt descrevendo a imagem a ser gerada |
| `aspect_ratio` | string, opcional | Formato da imagem: Square (1:1), Landscape (mais larga), ou Portrait (mais alta). Padrão Square. |
| `transparent` | boolean, opcional, padrão `false` | Fundo transparente (padrão false) |
| `reference_image_urls` | string, opcional | URLs https absolutas separadas por vírgula de imagens de referência para enviar com o prompt |
| `profile` | string, opcional | Perfil de otimização: None, SocialMediaInstagramPostFeed, SocialMediaInstagramPostStories. Padrão None. |
| `model` | string, opcional | Modelo de geração: OpenAI (padrão), BytePlus. Não altere a menos que o usuário peça. |

#### `get_drawing` (leitura)

Obtém um desenho gerado pelo id — o alvo do polling para generate_drawing. Mostra o status da geração e, quando finalizado, a image_url.

- `POST /rest/v1/tools/get_drawing`
- `GET /rest/v1/call/get_drawing`

| Parâmetros | | |
|---|---|---|
| `drawing_id` | integer, obrigatório | O drawing_id retornado por generate_drawing |

#### `get_image` (leitura)

Obtém uma imagem gerada pelo id — o alvo do polling para generate_image. Mostra o status da geração e, quando finalizada, a image_url.

- `POST /rest/v1/tools/get_image`
- `GET /rest/v1/call/get_image`

| Parâmetros | | |
|---|---|---|
| `image_id` | integer, obrigatório | O image_generation_id retornado por generate_image |

#### `get_video` (leitura)

Obtenha um vídeo gerado pelo id — o alvo de polling para create_video/edit_video (list_videos só mostra vídeos FINISHED, portanto faça polling neste para os que estão em andamento). is_finished=true com um video_url significa concluído; is_finished=true sem uma URL significa que a renderização falhou.

- `POST /rest/v1/tools/get_video`
- `GET /rest/v1/call/get_video`

| Parâmetros | | |
|---|---|---|
| `video_id` | integer, obrigatório | O video_id retornado por create_video ou edit_video |

#### `list_drawings` (leitura)

Liste os desenhos gerados (mais recentes primeiro, paginado). Inclui o status de geração de cada desenho e, uma vez finalizado, seu image_url.

- `POST /rest/v1/tools/list_drawings`
- `GET /rest/v1/call/list_drawings`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

#### `list_images` (leitura)

Lista as imagens geradas (mais recentes primeiro, paginado). Inclui o status de geração de cada imagem e, uma vez concluída, o seu image_url.

- `POST /rest/v1/tools/list_images`
- `GET /rest/v1/call/list_images`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

#### `list_videos` (leitura)

Lista os vídeos gerados anteriormente (mais recentes primeiro, paginado). Somente vídeos concluídos com sucesso e com uma URL são retornados.

- `POST /rest/v1/tools/list_videos`
- `GET /rest/v1/call/list_videos`

| Parâmetros | | |
|---|---|---|
| `page` | integer, opcional, padrão `1` | Número da página (1 = primeira página) |
| `page_size` | integer, opcional, padrão `10` | Tamanho da página (padrão 10, máximo 50) |

### Pesquisa online

Agenda uma pesquisa na web aberta e lê o resultado quando fica pronta.

#### `get_online_search` (leitura)

Obtenha o status e o resultado de uma busca online.

- `POST /rest/v1/tools/get_online_search`
- `GET /rest/v1/call/get_online_search`

| Parâmetros | | |
|---|---|---|
| `online_search_id` | integer, obrigatório | Id da busca online |

#### `list_online_searches` (leitura)

Lista as buscas online mais recentes do cliente (até 10, mais recentes primeiro) com seu status.

- `POST /rest/v1/tools/list_online_searches`
- `GET /rest/v1/call/list_online_searches`

Parâmetros: —

#### `register_online_search` (escrita)

Registra uma tarefa de pesquisa on-line. Ela roda em segundo plano — isso retorna imediatamente com um id; faça polling de get_online_search para obter o resultado. Opcionalmente, envia o resultado por e-mail quando terminar.

- `POST /rest/v1/tools/register_online_search`

| Parâmetros | | |
|---|---|---|
| `query` | string, obrigatório | A consulta a ser pesquisada online |
| `send_to_email` | string, opcional | Endereço(s) de email opcional(is), separados por vírgula, para enviar o resultado quando finalizado |
| `type` | string, opcional | Profundidade da busca: Fast, Standard (padrão) ou Deep |

### Suporte

A linha direta com o time da eesier — abre um chamado e lê os que já estão abertos.

#### `create_support_request` (escrita)

Abre uma linha direta com a equipe de suporte da Blue Button. Este é VOCÊ, o agente conectado, falando diretamente com a equipe de suporte e engenharia — use isso para fazer uma pergunta ou relatar um problema por iniciativa própria em segundo plano (o usuário final NÃO é notificado), ou quando o usuário pedir explicitamente que você entre em contato com o suporte. Especifique o type (technical, sales, human ou question) e a severity (low/medium/high/critical). A resposta da equipe volta para você — leia-a depois com list_support_requests.

- `POST /rest/v1/tools/create_support_request`

| Parâmetros | | |
|---|---|---|
| `message` | string, obrigatório | O que você quer perguntar ou relatar à equipe do Blue Button |
| `type` | string, obrigatório | Tipo de solicitação: 'technical' (problema de produto/técnico), 'sales' (comercial, cobrança, plano — o cliente quer que um representante de vendas entre em contato), 'human' (o cliente pede um contato humano, sem motivo específico), ou 'question' (uma solicitação simples de informação que você não consegue responder sozinho) |
| `severity` | string, obrigatório | Qual o nível de urgência: 'low', 'medium', 'high' ou 'critical' |

#### `list_support_requests` (leitura)

Lista as solicitações de suporte do cliente — sua thread com a equipe do Blue Button — com status, type, severity de cada solicitação, e a resposta da equipe (null até que respondam). Filtre por status: pending, answered, closed, ou all (padrão all).

- `POST /rest/v1/tools/list_support_requests`
- `GET /rest/v1/call/list_support_requests`

| Parâmetros | | |
|---|---|---|
| `status` | string, opcional, padrão `all` | Filtro de status: pending, answered, closed, ou all (padrão all) |

### Incidentes

Lê os incidentes da plataforma que afetam esta conta.

#### `list_incidents` (leitura)

Lista os incidentes da plataforma (interrupções / degradações / instabilidades) reportados pela equipe do Blue Button, cada um com sua linha do tempo pública de atualizações. Retorna incidentes em andamento (ativos) e incidentes passados resolvidos recentemente. Chame esta ferramenta quando o usuário perguntar se a plataforma está com problemas, ou quando chamadas de ferramentas estiverem falhando inesperadamente — um incidente ativo geralmente explica as falhas.

- `POST /rest/v1/tools/list_incidents`
- `GET /rest/v1/call/list_incidents`

| Parâmetros | | |
|---|---|---|
| `scope` | string, opcional | Quais incidentes retornar: 'active' (somente em andamento), 'past' (somente resolvidos) ou 'all' (padrão) |
| `limit` | integer, opcional | Número máximo de incidentes passados a retornar (padrão 10, máximo 50) |

## Perguntas frequentes

**Isso é um produto diferente do servidor MCP?**

Não. É o mesmo servidor e as mesmas ferramentas, alcançadas por HTTP puro em vez do protocolo MCP. As chamadas caem no mesmo código, então resultados, limites e registro são idênticos.

**Preciso de um agente de IA para usar?**

Não. É exatamente esse o propósito desta superfície. Um script de shell, um cron, um passo de n8n ou Zapier, ou o seu próprio backend chamam com nada além de curl.

**Posso usar REST e MCP ao mesmo tempo?**

Sim, com o mesmo token. Seu agente pode manter uma sessão MCP enquanto o seu backend faz POST nos endpoints REST; os dois escrevem na mesma conta.

**O que o status HTTP me diz?**

Exatamente o que aconteceu: 200 deu certo, 403 significa que o seu plano não inclui aquela ferramenta, 404 que a ferramenta ou o objeto não existe, 422 que a ferramenta recusou a requisição, 500 é uma falha permanente e 503 uma transitória que vale repetir. O corpo sempre traz o motivo legível por máquina.

**Existe limite de requisições?**

Não há limite por endpoint. Algumas ferramentas de escrita exigem plano ativo e dizem isso em uma mensagem clara, em vez de falhar em silêncio.

**Como acompanho as ferramentas novas?**

GET /rest/v1/tools é gerado pelo servidor em execução, então ferramenta nova aparece assim que entra no ar. Esta página vem do mesmo registro.