MCP: Conversas
Listar, ler, mover e atualizar as conversas do workspace pelo MCP. 7 ferramentas.
Ferramentas desta área, geradas do código do servidor. As descrições vêm desse código, em português. Para conectar, veja o MCP da XBASE.
change-thread-responsible
Troca o responsável de uma thread (usuário ou agente). Remove responsável atual e adiciona novo responsável. Use para redistribuir threads entre agentes ou usuários.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
threadId | sim | ID da thread que terá o responsável alterado |
newResponsibleId | sim | ID do novo responsável que irá responder as mensagens da thread (usuário ou agente) |
responsibleType | sim | Tipo do novo responsável: USER (usuário) ou AGENT (agente de IA) |
app | não | Aplicativo de origem do responsável: WHATSAPP_WEB (WhatsApp Web) ou WABA (WhatsApp Business API) |
sendInitialMessage | não | Se verdadeiro, envia uma mensagem inicial para o agente assim que a troca for concluída |
initialMessage | não | Mensagem inicial a ser enviada ao agente quando sendInitialMessage for verdadeiro |
count-attended-conversations
Conta CONVERSAS (threads distintas) atendidas em um período. Uma conversa conta quando a thread recebeu pelo menos 1 mensagem real no período: template enviado (que abre a conversa), mensagem do cliente ou resposta do agente/atendente. NÃO contam: eventos internos de lifecycle (mudança de stage/tag) nem threads do tipo WORKFLOW (containers de execução de flow). ATENÇÃO ao conferir: "é sempre >= AWBs com sucesso" é uma DESIGUALDADE e não detecta inflação do indicador — confira por decomposição que fecha, nunca por limite.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID do workspace |
createdAtFrom | não | Data/hora mínima de criação dos dialogs de atendimento (ISO 8601, ex: 2026-06-22T03:00:00.000Z) |
createdAtTo | não | Data/hora máxima de criação dos dialogs de atendimento (ISO 8601, ex: 2026-06-23T03:00:00.000Z) |
excludeThreadContextKey | não | GENÉRICO — chave de thread.context que marca a thread como NÃO atendida. Quem chama decide qual é; a tool não conhece vocabulário de cliente. Ex.: no CODCAGE da UPS, "imp_phone_valid". Deve vir junto com excludeThreadContextValue. |
excludeThreadContextValue | não | Valor da chave acima que marca a exclusão (ex.: "false"). Deve vir junto com excludeThreadContextKey. |
keepWhenEngaged | não | Padrão true: mesmo marcada para exclusão, a thread CONTA se houve comunicação real (mensagem DELIVERED/READ, ou mensagem enviada pelo contato). Use false para excluir de forma incondicional. |
threadCreatedAtFrom | não | MODO COORTE: com threadCreatedAtFrom/To, conta threads CRIADAS no período [from, to) — não conversas com mensagem no período. Exige createdAtTo (o corte: nenhum dialog depois dele conta) e não aceita createdAtFrom nem os filtros de contexto acima. |
threadCreatedAtTo | não | MODO COORTE: fim exclusivo da criação da thread (ISO 8601). |
threadType | não | MODO COORTE: tipo da thread (ex.: SHIPMENT). |
onlyWorkflowTemplate | não | MODO COORTE: só threads que receberam template enviado pelo workflow (ex.: remessa notificada). |
reachedStageIds | não | MODO COORTE: a thread entrou em algum destes estágios até o corte. |
notReachedStageIds | não | MODO COORTE: a thread não entrou em nenhum destes estágios até o corte. |
deadlineContextKey | não | MODO COORTE: chave de thread.context com a data-limite (ex.: nd_prazoDevolucao). Usar com deadlineMode ou deadlineFallbackOnly. |
deadlineFallbackDays | não | MODO COORTE: data-limite quando a chave não existe = criação (Brasília) + N dias. |
deadlineMode | não | MODO COORTE: within = a PRIMEIRA entrada em reachedStageIds foi até o fim do dia da data-limite (Brasília) ou houve dispensa; after = o contrário. |
deadlineWaiverStageIds | não | MODO COORTE: dispensa do prazo — entrar num destes estágios até o corte conta como dentro do prazo. |
deadlineWaiverTagNames | não | MODO COORTE: dispensa do prazo por tag adicionada até o corte. |
deadlineFallbackOnly | não | MODO COORTE: conta só as threads sem a chave deadlineContextKey. |
count-dialogs
Conta mensagens (dialogs) de um workspace em um período. Usa endpoint dedicado no backend com filtro nested via thread.workspaceId. Sem where, conta todas as mensagens. Com where, aceita qualquer filtro Prisma sobre o dialog — ex.: templates de WhatsApp efetivamente enviados: {"content":{"path":["type"],"equals":"TEMPLATE"},"status":{"in":["SENT","DELIVERED","READ"]}}.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID do workspace |
createdAtFrom | não | Data/hora mínima de criação dos dialogs (ISO 8601, ex: 2026-06-22T03:00:00.000Z) |
createdAtTo | não | Data/hora máxima de criação dos dialogs (ISO 8601, ex: 2026-06-23T03:00:00.000Z) |
where | não | Filtro Prisma adicional sobre o dialog, serializado em JSON. Combina com o filtro de workspace/período (AND). |
get-or-create-thread
Busca thread ativa do contato ou cria nova automaticamente. Adiciona contato como membro e opcionalmente associa agente. Use para iniciar conversas.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
contactId | sim | ID do contato para buscar ou criar thread |
workspaceId | sim | ID do contato para buscar ou criar thread |
agentId | não | ID do agente para associar à thread (opcional) |
title | não | Título da thread (usado apenas na criação) |
context | não | Contexto da thread (usado apenas na criação) |
get-thread-dialogs
Busca todos os diálogos de uma thread. Retorna lista completa de mensagens ordenadas cronologicamente. Use para analisar histórico de conversas.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
threadId | sim | ID da thread para buscar os diálogos |
list-threads
Lista ou conta threads de um workspace com filtros por data de criação, data de atualização e stage do board. Use onlyCount=true para obter apenas a contagem (ideal para relatórios). Use boardStageId para filtrar threads em um stage específico.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
workspaceId | sim | ID do workspace |
createdAtFrom | não | Data/hora mínima de criação (ISO 8601, ex: 2026-06-22T03:00:00.000Z) |
createdAtTo | não | Data/hora máxima de criação (ISO 8601, ex: 2026-06-23T03:00:00.000Z) |
updatedAtFrom | não | Data/hora mínima de atualização (ISO 8601) |
updatedAtTo | não | Data/hora máxima de atualização (ISO 8601) |
boardStageId | não | ID do stage do board para filtrar threads nesse stage |
status | não | Status da thread para filtrar (ex: ACTIVE, FAILED). Use para buscar AWBs com sucesso ou com falha. |
tagName | não | Nome exato da tag para filtrar threads (ex: "Pago em até 72h"). Usa junction table _TagToThread. |
onlyCount | não | true = retorna apenas a contagem total (mais rápido) |
limit | não | Máximo de threads a retornar (padrão: 50) |
skip | não | Número de threads a pular (para paginação) |
rename-thread
Renomeia uma thread alterando seu título. Use para organizar e identificar melhor as conversas.
| Parâmetro | Obrigatório | Descrição |
|---|---|---|
threadId | sim | ID da thread que será renomeada |
newTitle | sim | Novo título da thread |