Enviar mensaje al agente

Envía un turno al agente de inmediato o prográmalo para después. El endpoint sirve tanto para iniciar una conversación como para continuar una existente.

POST https://api.platica.mx/v1/chat

Cuerpo de la solicitud

Para iniciar una conversación:

{
  "message": "Ayúdame a elegir el plan adecuado para mi equipo.",
  "agentId": "agent_01JABCDEF23456789"
}

Cada solicitud nueva sin conversationId crea un hilo independiente con un conversationId chat_<uuid>, incluso si reutiliza el mismo cliente. clientId identifica al cliente, no al hilo.

¹ Debes enviar message, attachments o ambos.

Adjuntos

Los adjuntos se envían mediante URLs públicas o firmadas accesibles por el agente. No se sube el binario directamente a este endpoint.

{
  "agentId": "agent_01JABCDEF23456789",
  "message": "Analiza estos documentos",
  "attachments": [
    {
      "url": "https://cdn.example.com/foto-frente.jpg",
      "mimeType": "image/jpeg",
      "filename": "foto-frente.jpg"
    },
    {
      "url": "https://cdn.example.com/poliza.pdf",
      "mimeType": "application/pdf",
      "filename": "poliza.pdf"
    }
  ]
}

Reglas:

• Máximo 10 adjuntos por mensaje.
• Cada URL debe apuntar a un archivo menor a 20 MB.
• Las imágenes se envían como contenido visual; los demás MIME types se tratan como archivos.
• Varios adjuntos se procesan juntos como un solo mensaje multimedia.

Identificar al cliente

Para atribuir el chat a un cliente específico, envía un ID estable y sus datos:

{
  "message": "Quiero revisar mi póliza.",
  "agentId": "agent_01JABCDEF23456789",
  "client": {
    "id": "cliente_123",
    "name": "Ana López",
    "firstname": "Ana",
    "lastname": "López",
    "email": "ana@example.com",
    "phoneNumber": "5215512345678",
    "customFields": {
      "numero_poliza": "GNP-123456",
      "tipo_poliza": "gastos_medicos"
    }
  }
}

Al iniciar una conversación, client debe incluir id, email o phoneNumber. Platica:

1. Busca un cliente con esos identificadores.
2. Reutiliza el documento encontrado, o crea uno si no existe.
3. Detiene la solicitud si los identificadores apuntan a clientes distintos.

En los turnos siguientes puedes omitir client. Si vuelves a incluirlo, los campos enviados actualizan el cliente original; no puedes sustituirlo por otro client.id.

client.customFields acepta los campos personalizados activos del workspace. Los valores se combinan con los existentes y solo reemplazan las claves enviadas.

Continuar una conversación

Guarda el conversationId de la primera respuesta y envíalo en el siguiente turno:

{
  "message": "Somos 25 personas y necesitamos WhatsApp.",
  "conversationId": "chat_01JCHAT23456789"
}

Puedes cambiar el agente principal enviando otro agentId. La conversación conserva su historial y su canal interno; la delegación activa se reinicia y los siguientes subagentes parten del nuevo principal:

{
  "message": "Compara las dos mejores opciones.",
  "agentId": "agent_01JOTROAGENTE1234",
  "conversationId": "chat_01JCHAT23456789",
  "additionalInstructions": "Responde con una tabla breve."
}

Programar un turno

Usa delay para ejecutar el turno entre 3 segundos y 24 horas después:

{
  "message": "Recuérdame las opciones del plan.",
  "agentId": "agent_01JABCDEF23456789",
  "delay": 5000
}

Usa scheduleAt para indicar una fecha futura, hasta 1 año:

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

delay y scheduleAt son mutuamente exclusivos. También puedes programar turnos con attachments, client y additionalInstructions.

Reactivar un hilo cerrado o expirado

Cualquier hilo cerrado o expirado se reactiva automáticamente al enviarle un mensaje con su conversationId: la conversación conserva su historial y la respuesta devuelve reactivated: true. No existe un endpoint para cerrar chats desde esta API; el cierre se hace como negocio con PATCH /v1/conversations/{id} .

Respuesta inmediata

Sin delay ni scheduleAt, la respuesta mantiene el contrato síncrono existente:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "cliente_123",
  "agentId": "agent_01JOTROAGENTE1234",
  "status": "completed",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [
    {
      "id": "msg_assistant_01JCHAT98765433",
      "role": "assistant",
      "content": "Para un equipo de 25 personas con WhatsApp, estas son las mejores opciones...",
      "contentType": "text"
    }
  ],
  "reactivated": false,
  "agentChanged": true,
  "timestamp": "2026-07-20T18:30:00.000Z"
}

Respuesta programada

Con delay o scheduleAt, Platica crea una Cloud Task fire-and-forget y responde HTTP 202 sin esperar su ejecución:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "cliente_123",
  "agentId": "agent_01JABCDEF23456789",
  "status": "scheduled",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [],
  "schedule": {
    "taskId": "task_01JTASK23456789",
    "scheduleAt": "2026-07-20T18:30:05.000Z",
    "delayMs": 5000
  },
  "timestamp": "2026-07-20T18:30:00.000Z"
}