Chat

Las herramientas de Chat permiten actuar como el cliente que conversa con un agente. Para administrar owners, estado, etiquetas o enviar mensajes desde el negocio, usa las herramientas de Conversaciones y Mensajes.

Consulta el contrato completo en la API de Chat . Los fallos REST se entregan como errores de ejecución MCP; consulta Errores MCP .

Tool	Endpoint REST	Anotaciones
`list_chats`	`GET /v1/chat`	lectura, idempotente
`get_chat`	`GET /v1/chat/{id}`	lectura, idempotente
`send_chat_message`	`POST /v1/chat`	escritura, no destructiva

`list_chats`

Lista todos los chats con source: "api_chat" de los workspaces autorizados, sin filtrar por el usuario que los creó.

Campo	Tipo	Default	Descripción
`clientId`	`string`	—	Filtra por cliente atribuido.
`agentId`	`string`	—	Filtra por agente principal.
`limit`	`1-200`	`50`	Máximo de resultados.
`offset`	`≥ 0`	`0`	Offset de paginación.

Cada resultado incluye el resumen completo de Conversaciones sin messages: id, conversationId, clientId, agentId, canSendDirectMessage, workspaceId, channelId, contactName, phoneNumber, topic, platform, source, status, operation, messageCount, owners, tags, creationDate y lastUpdate. En estos chats internos, canSendDirectMessage siempre es true.

`get_chat`

Obtiene el estado y el historial normalizado de un chat.

Campo	Tipo	Requerido	Descripción
`id`	`string`	sí	ID único y canónico del documento.

Como fallback deprecado, id también acepta el conversationId chat_*. La respuesta es plana e incluye el resumen completo anterior más messages; el acceso exige workspace autorizado y source: "api_chat".

`send_chat_message`

Inicia o continúa una conversación inmediata o programada con un agente.

Campo	Tipo	Requerido	Descripción
`message`	`string`	sí¹	Texto del cliente.
`attachments`	`object[]`	sí¹	Hasta 10 URLs de imágenes/archivos, cada uno menor a 20 MB.
`conversationId`	`string`	al continuar	Chat `chat_*` existente.
`agentId`	`string`	al crear	Agente inicial; al continuar puede cambiar el respondedor.
`additionalInstructions`	`string`	no	Instrucciones aplicadas solo a ese turno.
`client`	objeto	no	Cliente atribuido; si se omite al crear, usa el usuario de la API key.
`delay`	`integer`	no	Retraso de `3000` a `86400000` ms. No se combina con `scheduleAt`.
`scheduleAt`	`string`	no	Fecha ISO 8601 futura, hasta 1 año. No se combina con `delay`.

¹ Envía message, attachments o ambos. Cada attachment requiere url y mimeType; filename es opcional.

Una conversación cerrada se reactiva automáticamente al enviar otro mensaje. Sin conversationId, cada invocación crea un hilo nuevo con otro chat_<uuid>, aunque use el mismo cliente. clientId nunca sustituye a conversationId.

{
  "name": "send_chat_message",
  "arguments": {
    "agentId": "agent_123",
    "message": "Ayúdame a revisar mi póliza",
    "attachments": [
      {
        "url": "https://cdn.example.com/poliza.pdf",
        "mimeType": "application/pdf",
        "filename": "poliza.pdf"
      }
    ],
    "client": {
      "email": "ana@example.com",
      "customFields": {
        "numero_poliza": "GNP-123"
      }
    }
  }
}

Para programar el turno:

{
  "name": "send_chat_message",
  "arguments": {
    "agentId": "agent_123",
    "message": "Prepara un resumen antes de la reunión",
    "scheduleAt": "2026-08-01T15:00:00-06:00"
  }
}

attachments, client y additionalInstructions también pueden incluirse en un turno programado.

Respuesta inmediata

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "cliente_123",
  "agentId": "agent_123",
  "status": "completed",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [],
  "reactivated": false,
  "agentChanged": false,
  "timestamp": "2026-07-20T18:30:00.000Z"
}

Respuesta programada

Con delay o scheduleAt, la tool crea una Cloud Task fire-and-forget y devuelve el resultado HTTP 202:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "cliente_123",
  "agentId": "agent_123",
  "status": "scheduled",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [],
  "schedule": {
    "taskId": "task_01JTASK23456789",
    "scheduleAt": "2026-08-01T21:00:00.000Z"
  },
  "timestamp": "2026-07-20T18:30:00.000Z"
}

schedule.scheduleAt siempre está normalizado a UTC. Cuando programas con delay, schedule también incluye delayMs.

El resultado no incluye la respuesta del agente. Después de scheduleAt, usa get_chat con el id. El id está preasignado, pero el documento puede devolver 404 hasta que se ejecute la tarea.

Una conversación nueva puede no aparecer hasta que la tarea se ejecute.

Anterior Catálogo de herramientas Siguiente Mensajes