Mensajes

Los fallos REST se entregan como errores de ejecución; consulta Errores MCP .

send_message

Envía un mensaje personalizado dentro de una conversación existente. La herramienta resuelve la conversación por conversationId y channelId; si hay varias conversaciones para el mismo teléfono, usa la más reciente que coincide con el canal. canSendDirectMessage solo puede ser false en WhatsApp, Instagram y Messenger/Facebook y se calcula desde el último mensaje del usuario.

Argumentos

Ejemplo de invocación

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

Ejemplo con media

{
  "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"
      }
    }
  }
}

Ejemplo de instrucción al agente

Una instrucción no llega al cliente: se aplica sobre el agente que opera la conversación. Usa mode: "wait" para que el agente espere al próximo mensaje del cliente con la instrucción registrada como contexto, o mode: "resume" para reanudar al agente para que continúe el flujo.

{
  "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

Envía un mensaje basado en una plantilla aprobada de WhatsApp al cliente identificado por conversationId (número de teléfono internacional). Crea la conversación y/o el cliente si no existen. Se puede enviar inmediatamente, con delay (de 3000 ms a 24 horas) o con scheduleTime (ISO 8601, máximo 30 días después de la solicitud; hora de México si no incluye zona).

Argumentos

Ejemplo de invocación

{
  "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"
    }
  }
}

Si omites responderAgentId con un canal canónico, la conversación nueva queda initiated y sin agente. El default del canal no se hereda. Un input legacy (teléfono del agente) sí conserva ese agente. Un contacto con status: "blocked" devuelve CONTACT_BLOCKED y no recibe el mensaje.

Cuando send_message o send_template_message recibe delay o scheduleTime, su resultado HTTP 202 incluye messageId, kind, status, executeAt en UTC, timestamp y delayMs o scheduledTime. Ese messageId basta para usar las cuatro herramientas siguientes; no necesitas campaignId, runId ni un ID interno de tarea.

list_scheduled_messages

Lista mensajes de servicio y plantillas programadas. Sin status, devuelve los activos: creating, delayed, scheduled y processing.

Argumentos

Ejemplo de invocación

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

Resultado

{
  "messages": [
    {
      "messageId": "msg_01JQ91AB7C4D8E2F6G0H",
      "kind": "template",
      "status": "scheduled",
      "channelId": "wb-12345",
      "conversationId": "5215512345678",
      "campaignId": "api",
      "messageType": null,
      "templateName": "recordatorio_cita",
      "preview": "Hola Ana, te recordamos tu cita...",
      "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"
}

Para continuar, conserva los filtros y pasa nextPageToken como pageToken. Si no aparece, no hay más páginas.

get_scheduled_message

Obtiene un mensaje programado por su identificador público.

Argumentos

¹ Obligatorio cuando la credencial tiene acceso a varios workspaces.

Ejemplo de invocación

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

El resultado es un recurso con los mismos campos públicos que un elemento de list_scheduled_messages. conversationId, campaignId, messageType, templateName, preview, phoneNumber, name, cancelledAt, sentAt, failedAt y error pueden ser null. Nunca incluye el payload completo ni taskId.

reschedule_scheduled_message

Cambia la ejecución de un mensaje que todavía tiene reschedulable: true. Envía exactamente uno de scheduleTime o delay.

Argumentos

¹ Envía exactamente uno. ² Obligatorio para credenciales multi-workspace.

Ejemplo de invocación

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

El resultado devuelve el recurso actualizado. Con scheduleTime queda scheduled; con delay, delayed. Las fechas públicas, incluido executeAt, siempre están normalizadas a UTC. Un mensaje processing, sent, cancelled o failed ya no se puede reprogramar; el error REST 409 se entrega como error de ejecución MCP.

cancel_scheduled_message

Cancela un mensaje antes de que empiece a procesarse.

Argumentos

¹ Obligatorio para credenciales multi-workspace.

Ejemplo de invocación

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

La herramienta devuelve el recurso con status: "cancelled", cancelledAt y reschedulable: false. Es idempotente: repetirla devuelve el mismo recurso cancelado. Los estados processing, sent y failed producen 409.

Consulta el contrato completo, los estados y todos los campos en Mensajes Programados .