Chat Jurídico

Consulta a Meta e atualiza o status de um template enviado (`PENDING` → `APPROVED`, `REJECTED`...). Também resolve um envio que ficou sem resposta (`QUEUED`, ou o 202 de `enviarTemplateParaAprovacao`): se a Meta tem o template, ele é vinculado; se o envio comprovadamente não chegou à Meta, o template volta a `DRAFT` com `rejected_reason` e pode ser enviado de novo. Não altera nada na Meta. Requer o escopo `messages:send` e uma **chave de API**. Quando usar: cerca de 1 minuto depois de um 202 / `submission_in_progress` de `enviarTemplateParaAprovacao`, ou mais tarde para ver se a Meta aprovou (a análise leva de minutos a horas; não consulte em laço). `APPROVED` → próximo passo `criarCampanha`. `REJECTED` → veja `rejected_reason` e crie outro template com um nome novo. Respostas: **200** com o template atualizado; **202** quando a Meta não respondeu a tempo ou o envio ainda está em andamento (tente de novo em cerca de 1 minuto); **404** `template_not_found`; **422** `provider_not_supported` / `instance_not_connected` / `instance_reconnect_required`; **429** `meta_rate_limited` ou o limite de 10 requisições por minuto desta chave; **503** indisponível. Não use `Idempotency-Key` aqui: uma resposta repetida da chave congelaria o status.

atualizarStatusTemplate

Atualiza os dados de uma tag existente. Envie apenas os campos que deseja alterar. Requer o escopo `tags:write`.

atualizarTag

Atualiza `client_polo`, `status_operacional` e/ou `advogado_user_id` do vínculo do processo (identificado pelo CNJ) com o escritório. Para limpar o responsável, envie `advogado_user_id: "__LIMPAR__"` (via MCP, onde null é ignorado) ou `null` (via REST). Requer `lawsuits:write`.

atualizarProcessoEscritorio

Endpoint de busca estruturada para consultas avançadas que não podem ser expressas com os parâmetros GET. Aceita filtros com operadores, ordenação multi-campo e paginação por cursor. Campos permitidos: unique_id, contact_id, instance_id, last_message_at, last_message_text, last_message_type, is_archived, office_stage_id, tags_ids, unread_messages_count, phone_id, created_at, accountable_id, agent_is_active_local, is_waiting_human, is_ctwa_origin, customer_service_window_status. Operadores: eq, neq, gt, gte, lt, lte, in, overlaps, ilike, is_null.

buscarConversasAvancado

Busca conversas por texto (nome OU telefone DO CONTATO). Um `query` livre casa APENAS nome/telefone do contato (ILIKE) — NÃO busca no CONTEÚDO das mensagens e NÃO casa o NOME de um número/instância. Para busca estruturada por campo, passe `filters` como ARRAY `[{field, operator, value}]` (ex: last_message_text, instance_id, office_stage_id, tags_ids) — só então usa o endpoint avançado. NÃO serve para: (a) achar um NÚMERO pelo nome (ex: 'Julie - Suporte') → use `status_integracao`, que lista cada número conectado com seu `instance_id`; (b) ler o que um número ENVIA → resolva o `instance_id` e use `listarConversas(instance_id, has_unread=true)` + `listarMensagens(from_me=true)` (ordenar por recência traz cascas vazias importadas de formulário, sem mensagem). Cada conversa traz `instance` = o NÚMERO DO ESCRITÓRIO que a atende (id/name/phone). Não confunda com `contact_phone`, que é o número do cliente. ATENÇÃO: um escritório pode ter vários números, e a mesma pessoa costuma ter UMA CONVERSA POR NÚMERO — com o mesmo nome e o mesmo `contact_phone`. Elas só se distinguem por `instance`. NUNCA escolha a primeira da lista para enviar mensagem: confirme o número com o usuário, ou use `enviar_para_numero`.

busca_inteligente

Retorna os dados de um atalho específico. Requer o escopo `shortcuts:read`.

buscarAtalho

Retorna os dados completos de uma campanha específica, incluindo contadores de envio e entrega, horários também no fuso de Brasília (`*_local`), `readiness` (rascunho) e `status_reason` (por que uma campanha pausou ou falhou). Um rascunho já agendado pela API é arquivado: consultá-lo responde 404 `code: "draft_scheduled"` com o `campaign_id` da campanha criada.

buscarCampanha

Retorna os dados completos de um contato específico.

buscarContato

Identifica contatos potencialmente duplicados no escritório. Detecta variantes do 9º dígito brasileiro, telefones idênticos em contatos diferentes e colisões de BSUID. Retorna pares agrupados com sugestão de qual contato manter. Requer o escopo `contacts:read`.

buscarContatosDuplicados

Retorna os dados completos de uma conversa específica, incluindo última mensagem e contagem de não lidas.

buscarConversa

Busca processos cadastrados no escritório por nome de parte (`parte`), status operacional (`status`) e/ou advogado responsável (`advogadoId`). Retorna lista paginada com `next_cursor`.

buscar_processos_escritorio

Retorna os dados de um template específico. Requer o escopo `messages:read`.

buscarTemplate

Cancela uma mensagem agendada que ainda está esperando o horário: status `pending` (agendada por pessoa, API ou lembrete) ou `automation_pending` (deixada para depois por uma automação). Qualquer outro status devolve 409 com o status atual e o motivo, inclusive quando o status muda entre a leitura e a gravação (o enviador pegou a linha, ou alguém cancelou antes). Nunca cancela `processing` nem `automation_sending`: a mensagem já está saindo. Numa linha de automação o cancelamento grava `cancel_reason` `manual` e `canceled_at`, e o registro de entrega da automação passa a cancelado na mesma transação. Cancela só esta linha: para parar a sequência inteira, cancele também as outras linhas `automation_pending` com o mesmo `automation_batch_id` (veja `listarMensagensAgendadas`). A resposta traz o status como gravado (`canceled`).

cancelarMensagemAgendada

Cancela (desativa) um agendamento de rotina pelo seu id. Use listar_rotinas_agendadas para obter o id.

cancelar_rotina_agendada

Resumo de carga de trabalho da equipe: contagem exata de conversas abertas e não lidas por membro da equipe.

carga_equipe

Classifica e atribui uma conversa em uma chamada: aplica tag, etapa do funil e/ou membro responsável. Opcionalmente adiciona uma anotação. Retorna o estado anterior e atualizado para confirmação. Equivalente em chat: "Classificar a conversa {id} como {tag} e atribuir a {membro}" ou "Mover a {nome do contato} para a etapa {etapa}".

classificar_e_atribuir

Lista todas as cobranças vencidas não reconhecidas, agrupadas por cliente, com dias de atraso.

cobrancas_vencidas

Altera o perfil de ferramentas ativas para economizar tokens. Perfis disponíveis: - essencial (~15 ferramentas): briefing, busca, envio, classificação - vendas (~25 ferramentas): essencial + funil, tags, contatos, financeiro básico - atendimento (~25 ferramentas): essencial + mensagens, anotações, atalhos - financeiro (~30 ferramentas): essencial + cobranças, dashboard, Asaas - completo (~100 ferramentas): todas as ferramentas (padrão) Sugira 'essencial' para economizar tokens quando o usuário só precisar das ferramentas principais.

configurar_perfil

Retorna um caso do escritório com suas partes (`parties[]`) e conversas vinculadas (`chats_id[]`). Requer `cases:read`.

consultarCaso

Um convite deste escritório, com o mesmo conteúdo da listagem. Convite de outro escritório responde 404. Requer `partner_invites:read`.

buscarConviteParceiro

Consulta UM processo já cadastrado no escritório pelo número CNJ, retornando metadados (partes, tribunal, classe, assunto, situação, valor) e as movimentações mais recentes. Diferente de consultar_processo_publico, que consulta a base pública do CNJ (DataJud). Aceita CNJ formatado ou 20 dígitos.

consultar_processo_escritorio

Quantos casos o escritório tem em cada coluna do kanban (`novo`, `em_andamento`, `aguardando`, `concluido`, `arquivado`). Opcionalmente filtrado por `source`. Requer `cases:read`.

contagemCasos

Retorna a contagem exata de conversas que correspondem aos filtros informados. Usa `SELECT COUNT(*)` diretamente no banco, sem limite de paginação — ideal para dashboards, resumos de pipeline e métricas em tempo real. Aceita os mesmos filtros de `listarConversas` (exceto `cursor`, `limit`, `sort_by` e `search`).

contarConversas

Retorna a contagem exata de registros de contatos não excluídos no escritório e nas instâncias permitidas pela chave. Use contact_status=lead para Leads, customer para Clientes ou unclassified para não classificados. Sem filtro conta todos. Não depende de paginação, não conta pessoas únicas e não confunde null com Lead. Requer contacts:read.

contarContatos

Contexto completo de uma conversa: detalhes da conversa, contato, mensagens recentes, tags, etapa do funil e anotações em uma chamada. Equivalente em chat: "Mostrar contexto da conversa {id}" ou "Resumir o histórico de {nome do contato}".

contexto_conversa

Contexto completo de conversa com leitura inline das imagens recentes. Use quando houver mensagens do tipo image/sticker e o usuário pedir para interpretar conteúdo visual. Limita a 3 imagens pequenas por padrão. Equivalente em chat: "Mostrar conversa {id} com as imagens" ou "Analisar as fotos enviadas por {nome}".

contexto_conversa_com_midias

Contexto enriquecido de TODAS as conversas de uma etapa do funil, tag ou filtro — em uma única chamada. Retorna sinais de priorização para follow-up: dias na etapa, última mensagem, contagem de não lidas, responsável, janela de atendimento, última sessão do agente IA (classificação do lead, resumo, motivo de conclusão), follow-ups pendentes, e opcionalmente as N últimas mensagens de cada conversa. Use primeiro com include_last_messages=0 para ranquear (até 500 conversas), depois com conversation_ids + include_last_messages para aprofundar nos top leads. Exige ao menos um filtro: stage_id, conversation_ids, tag_ids, has_unread, responsible_id, is_waiting_human ou instance_id (is_archived sozinho não conta). Para todas as conversas de um número, use instance_id.

contexto_lote_conversas

Controle do agente IA em uma conversa: verifica status atual, ativa ou desativa o agente, e retorna histórico de sessões. Ação: 'status' (padrão), 'activate' ou 'deactivate'. Equivalente em chat: "Verificar agente IA da conversa {id}", "Pausar o agente nesta conversa" ou "Reativar o agente em {id}".

controle_agente_conversa

Cria uma nova anotação interna em uma conversa. Requer o escopo `conversations:write`. Para mencionar colegas, informe os `mentions` (uuid dos membros) e/ou embuta `@[uuid|Nome]` no `text` (até 50 destinatários distintos). A entrega depende das preferências e da ativação do produtor de notificações. Menções podem gerar e-mail para os colegas.

criarAnotacao

Cria uma campanha em rascunho (status `draft`), como o rascunho salvo no app. Informe o público por `recipient_tag_ids` (contatos com qualquer uma das etiquetas) ou por `recipient_contact_ids` (lista de contatos do número), não os dois. Grave também o que o envio precisa: `template_variables` (origem de cada `{{n}}`, guardada no formato do app), `header_media_url` (link https público da mídia do cabeçalho) e `description`. Campos desconhecidos são ignorados e listados em `ignored_fields`. A resposta traz `readiness` (o que falta para agendar). Para agendar: `previsualizarAgendamento` e depois `agendarCampanha` (escritórios habilitados), ou confirme o rascunho no app. A campanha fica no nome do usuário que criou a chave de API (ele precisa ser usuário do escritório; chaves internas não criam campanhas). A resposta traz `total_recipients` (contagem esperada) e `recipients_materialized: false`: os destinatários só passam a existir quando o rascunho é agendado. Requer o escopo `campaigns:write`.

criarCampanha

Cria um campo personalizado no PAINEL DO CONTATO (o mesmo de Configurações → Propriedades). Depois de criado, grave os valores por contato com `PUT /v1/contacts/{id}/properties` usando a `key`. Requer o escopo `contacts:write`. - `key` é opcional: sem ela, é gerada a partir do `name` (ex.: "Tipo de desconto" → `tipo_de_desconto`). Não pode ser alterada depois. - Para `select`/`multi_select`, envie `options` como lista de rótulos (ex.: `["Aposentadoria", "Auxílio-doença"]`). O valor de cada opção é gerado a partir do rótulo inteiro (`aposentadoria`, `auxilio_doenca`) e é esse valor que se grava no contato. - Se a `key` ou o `name` pertencerem a um campo excluído, ele é REATIVADO como estava, com os valores (`reactivated: true`), em vez de criar outro. - O campo criado (ou reativado) entra no FIM da lista do painel. Para colocá-lo em outro lugar, use depois `atualizarPropriedadeContato` com `position`. NÃO confundir com `criarPropriedadeCustomizada` (tag Documentos), que cria campo do gerador de documentos e NÃO aparece no painel do contato.

criarPropriedadeContato

Cria um caso manual no escritório. Requer `cases:write`. Não consulta nenhuma base externa e não tem custo. - `contact_id` = "este contato é o cliente": adiciona o contato como parte `cliente` e vincula **todas** as conversas dele (uma por número do escritório). - `conversation_id` vincula uma conversa específica. - `parties[]` adiciona as demais partes na mesma chamada (nome e papel; `contact_id` opcional preenche o nome a partir do contato). - `responsible_user_id` deve ser membro do escritório (`listarMembros`). - Boas práticas do escritório: título com o nome do cliente, `tags` para a tese e a origem ("contrato fechado por ia"), `status: aguardando` enquanto falta assinatura.

criarCaso

Cria um novo contato no seu escritório. O campo `phone` deve estar no formato internacional sem caracteres especiais (ex: `5511999998888`). **Semântica por instância**: a unicidade do contato é por par `(phone, instance_id)`. O mesmo telefone pode existir como contatos distintos em instâncias diferentes do mesmo escritório. - Se sua chave de API tem escopo em **uma única instância** e você omitir `instance_id`, o contato é criado nessa instância (default transparente). - Se sua chave abrange **múltiplas instâncias** e você omitir `instance_id`, a operação retorna `400` com `code: instance_required` — informe a instância explicitamente. - Se você informar um `instance_id` **fora do escopo** da sua chave, a operação retorna `400` com `code: instance_out_of_scope`. - Se já existir um contato ativo com o mesmo telefone **na mesma instância**, a operação retorna `409 Conflict` com `code: duplicate_resource`.

criarContato

Abre a conversa de um contato no número de WhatsApp ao qual ele pertence. **CONTATO ≠ PESSOA — não confunda:** - Um **contato** está vinculado a **UM único número** (`contacts` é `UNIQUE(phone, instance_id)`) e tem no máximo **UMA** conversa (`chats` é `UNIQUE(contact_id)`). - A mesma **pessoa** (mesmo telefone) tem **um contato — e uma conversa — POR NÚMERO** do escritório. Isso é normal e esperado. - Para falar com essa pessoa por **outro** número, use o **contato daquele número**. **NÃO** reutilize o mesmo `contact_id` trocando o `instance_id`: o contato não muda de número. Portanto `instance_id` deve ser o número ao qual o contato **já pertence**: - Conversa já existe para o contato: ela é retornada (idempotente). - `instance_id` **diferente** do número do contato: `409 Conflict` com `code: contact_bound_to_other_instance`. A mensagem indica o número real do contato e, quando existe, o `contact_id` **irmão** no número solicitado — use esse. - Conversa existe mas em um número **fora do escopo da chave de API**: `409 Conflict` com `code: conversation_exists_other_instance`.

criarConversa

Cria uma nova etapa no funil de vendas. Requer o escopo `funnel:write`.

criarEtapaFunil

Cria uma nova tag no seu escritório. Requer o escopo `tags:write`. O campo `name` deve ter entre 1 e 100 caracteres.

criarTag

Dashboard de conversas pendentes: agrupa conversas não lidas e aguardando humano por membro responsável, com duração de inatividade. Inclui bucket de conversas sem responsável e contagem exata total. Use 'limit' para restringir o número de conversas retornadas (ex: top 10 mais antigas). Equivalente em chat: "Listar conversas pendentes" ou "Mostrar a fila de atendimento".

conversas_pendentes

Define este processo como o **ativo** da conversa — o que a IA usa ao responder sobre andamento. Requer `lawsuits:write`.

definirProcessoAtivo

Descobre ferramentas disponíveis por categoria (categoria). Categorias: contacts, conversations, messages, pipeline, tags, scheduling, campaigns, automations, templates, webhooks, team, analytics, composite, shortcuts, annotations, drafts, routines, skills, media, instances, usage, agent_sessions, simulations, signatures, integrations, payments. Use sem parâmetros para ver todas as categorias.

descobrir_ferramentas

Remove a conversa do caso. O caso continua existindo (diferente de `desvincularProcessoConversa`, aqui nada é arquivado). Requer `cases:write`.

desvincularCasoConversa