Messages

REST failures are returned as execution errors; see MCP Errors .

send_message

Sends a personalized message inside an existing conversation. The tool resolves the conversation via conversationId and channelId; if there are several conversations for the same phone number, it uses the most recent one that matches the channel. canSendDirectMessage can only be false on WhatsApp, Instagram, and Messenger/Facebook and is calculated from the latest user message.

Arguments

Invocation example

{
  "name": "send_message",
  "arguments": {
    "channelId": "wb-12345",
    "conversationId": "+521234567890",
    "content": "Hola, te escribo desde Platica API",
    "client": {
      "name": "Ana López",
      "customFields": {
        "placas": "ABC123"
      }
    }
  }
}

Media example

{
  "name": "send_message",
  "arguments": {
    "channelId": "wb-12345",
    "conversationId": "+521234567890",
    "type": "image",
    "content": {
      "image": {
        "url": "https://cdn.assets.com/foto.jpg",
        "caption": "Aquí está la foto"
      }
    }
  }
}

Agent instruction example

An instruction does not reach the customer: it is applied to the agent operating the conversation. Use mode: "wait" to have the agent wait for the next customer message with the instruction recorded as context, or mode: "resume" to resume the agent so it continues the flow.

{
  "name": "send_message",
  "arguments": {
    "channelId": "wb-12345",
    "conversationId": "+521234567890",
    "type": "instruction",
    "content": {
      "text": "Continúa con el flujo de venta y ofrece un descuento del 10%.",
      "mode": "resume"
    }
  }
}

send_template_message

Sends a message based on an approved WhatsApp template to the customer identified by conversationId (international phone number). Creates the conversation and/or the customer if they don't exist. It can be sent immediately, with delay (from 3000 ms to 24 hours), or with scheduleTime (ISO 8601, no more than 30 days after the request; Mexico time if no zone is included).

Arguments

Invocation example

{
  "name": "send_template_message",
  "arguments": {
    "channelId": "wb-12345",
    "conversationId": "+521234567890",
    "template": {
      "name": "bienvenida_v1",
      "params": ["Ana", "10%"]
    },
    "client": {
      "name": "Ana López",
      "email": "ana@example.com"
    }
  }
}

When responderAgentId is omitted with a canonical channel, the new conversation starts initiated and unassigned. The channel default is not inherited. A legacy agent-phone identifier still preserves that agent. A contact with status: "blocked" receives CONTACT_BLOCKED and no message is sent.

When send_message or send_template_message receives delay or scheduleTime, its HTTP 202 result includes messageId, kind, status, UTC executeAt, timestamp, and either delayMs or scheduledTime. That messageId is enough to use the next four tools; you do not need campaignId, runId, or an internal task ID.

list_scheduled_messages

Lists scheduled service messages and templates. Without status, it returns active messages: creating, delayed, scheduled, and processing.

Arguments

Invocation example

{
  "name": "list_scheduled_messages",
  "arguments": {
    "status": "scheduled,processing",
    "kind": "template",
    "from": "2026-10-01T00:00:00Z",
    "to": "2026-11-01T00:00:00Z",
    "limit": 50
  }
}

Result

{
  "messages": [
    {
      "messageId": "msg_01JQ91AB7C4D8E2F6G0H",
      "kind": "template",
      "status": "scheduled",
      "channelId": "wb-12345",
      "conversationId": "5215512345678",
      "campaignId": "api",
      "messageType": null,
      "templateName": "appointment_reminder",
      "preview": "Hi Ana, this is a reminder for your appointment...",
      "phoneNumber": "5215512345678",
      "name": "Ana López",
      "executeAt": "2026-10-15T15:45:00.000Z",
      "createdAt": "2026-09-20T20:00:00.000Z",
      "updatedAt": "2026-09-20T20:00:00.000Z",
      "cancelledAt": null,
      "sentAt": null,
      "failedAt": null,
      "error": null,
      "reschedulable": true
    }
  ],
  "count": 1,
  "nextPageToken": "eyJleGVjdXRlQXQiOiIyMDI2LTEwLTE1VDE1OjQ1OjAwLjAwMFoifQ"
}

To continue, keep the same filters and pass nextPageToken as pageToken. When it is absent, there are no more pages.

get_scheduled_message

Retrieves a scheduled message by its public identifier.

Arguments

¹ Required when the credential can access multiple workspaces.

Invocation example

{
  "name": "get_scheduled_message",
  "arguments": {
    "messageId": "msg_01JQ91AB7C4D8E2F6G0H"
  }
}

The result is one resource with the same public fields as an item from list_scheduled_messages. conversationId, campaignId, messageType, templateName, preview, phoneNumber, name, cancelledAt, sentAt, failedAt, and error can be null. It never includes the full payload or taskId.

reschedule_scheduled_message

Changes the execution time of a message that still has reschedulable: true. Send exactly one of scheduleTime or delay.

Arguments

¹ Send exactly one. ² Required for multi-workspace credentials.

Invocation example

{
  "name": "reschedule_scheduled_message",
  "arguments": {
    "messageId": "msg_01JQ91AB7C4D8E2F6G0H",
    "scheduleTime": "2026-10-16T10:30:00-06:00"
  }
}

The result is the updated resource. With scheduleTime, status becomes scheduled; with delay, delayed. Public dates, including executeAt, are always normalized to UTC. A message in processing, sent, cancelled, or failed can no longer be rescheduled; the REST 409 is returned as an MCP execution error.

cancel_scheduled_message

Cancels a message before it starts processing.

Arguments

¹ Required for multi-workspace credentials.

Invocation example

{
  "name": "cancel_scheduled_message",
  "arguments": {
    "messageId": "msg_01JQ91AB7C4D8E2F6G0H"
  }
}

The tool returns the resource with status: "cancelled", cancelledAt, and reschedulable: false. It is idempotent: repeating it returns the same cancelled resource. processing, sent, and failed states produce 409.

See Scheduled Messages for the complete contract, states, and fields.