Send message to agent

Send a turn to the agent immediately or schedule it for later. The endpoint starts a conversation or continues an existing one.

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

Request body

To start a conversation:

{
  "message": "Help me choose the right plan for my team.",
  "agentId": "agent_01JABCDEF23456789"
}

Each new request without conversationId creates an independent thread with a chat_<uuid> conversationId, even when it reuses the same client. clientId identifies the client, not the thread.

¹ Send message, attachments, or both.

Attachments

Attachments are sent through public or signed URLs that the agent can access. Binary files are not uploaded directly to this endpoint.

{
  "agentId": "agent_01JABCDEF23456789",
  "message": "Analyze these documents",
  "attachments": [
    {
      "url": "https://cdn.example.com/front-photo.jpg",
      "mimeType": "image/jpeg",
      "filename": "front-photo.jpg"
    },
    {
      "url": "https://cdn.example.com/policy.pdf",
      "mimeType": "application/pdf",
      "filename": "policy.pdf"
    }
  ]
}

Rules:

• Maximum 10 attachments per message.
• Each URL must point to a file smaller than 20 MB.
• Images are sent as visual content; other MIME types are treated as files.
• Multiple attachments are processed together as one multimedia message.

Identify the client

To attribute the chat to a specific client, send a stable ID and their details:

{
  "message": "I want to review my policy.",
  "agentId": "agent_01JABCDEF23456789",
  "client": {
    "id": "client_123",
    "name": "Ana López",
    "firstname": "Ana",
    "lastname": "López",
    "email": "ana@example.com",
    "phoneNumber": "5215512345678",
    "customFields": {
      "policy_number": "GNP-123456",
      "policy_type": "medical_expenses"
    }
  }
}

When starting a conversation, client must include id, email, or phoneNumber. Platica:

1. Looks for a client with those identifiers.
2. Reuses the matching document, or creates one when none exists.
3. Stops the request when the identifiers point to different clients.

You may omit client on later turns. When sent again, the provided fields update the original client; you cannot replace it with another client.id.

client.customFields accepts active custom fields defined in the workspace. Values are merged with existing data and only the submitted keys are replaced.

Continue a conversation

Save the conversationId from the first response and send it in the next turn:

{
  "message": "We are 25 people and need WhatsApp.",
  "conversationId": "chat_01JCHAT23456789"
}

You can change the principal agent by sending another agentId. The conversation keeps its history and internal channel; active delegation resets and future subagents start from the new principal:

{
  "message": "Compare the two best options.",
  "agentId": "agent_01JOTHERAGENT1234",
  "conversationId": "chat_01JCHAT23456789",
  "additionalInstructions": "Answer with a short table."
}

Schedule a turn

Use delay to run the turn between 3 seconds and 24 hours later:

{
  "message": "Remind me about the plan options.",
  "agentId": "agent_01JABCDEF23456789",
  "delay": 5000
}

Use scheduleAt for a future date, up to 1 year ahead:

{
  "message": "Prepare a summary before the meeting.",
  "agentId": "agent_01JABCDEF23456789",
  "scheduleAt": "2026-08-01T15:00:00-06:00"
}

delay and scheduleAt are mutually exclusive. You can also schedule turns with attachments, client, and additionalInstructions.

Reactivate a closed or expired thread

Any closed or expired thread is reactivated automatically when you send it a message with its conversationId: the conversation keeps its history and the response returns reactivated: true. There is no endpoint to close chats from this API; closing is done as the business with PATCH /v1/conversations/{id} .

Immediate response

Without delay or scheduleAt, the response keeps the existing synchronous contract:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "client_123",
  "agentId": "agent_01JOTHERAGENT1234",
  "status": "completed",
  "requestMessageId": "msg_user_01JCHAT98765432",
  "messages": [
    {
      "id": "msg_assistant_01JCHAT98765433",
      "role": "assistant",
      "content": "For a team of 25 people using WhatsApp, these are the best options...",
      "contentType": "text"
    }
  ],
  "reactivated": false,
  "agentChanged": true,
  "timestamp": "2026-07-20T18:30:00.000Z"
}

Scheduled response

With delay or scheduleAt, Platica creates a fire-and-forget Cloud Task and returns HTTP 202 without waiting for it to run:

{
  "id": "conversation_doc_01JCHAT",
  "conversationId": "chat_01JCHAT23456789",
  "clientId": "client_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"
}