Enviar Mensaje Personalizado

Envía un mensaje a un cliente dentro de una conversación que ya está abierta. A diferencia de Enviar Plantilla — que sirve para iniciar la conversación — este endpoint asume que el cliente ya inició una conversación o respondió recientemente a una plantilla, por lo que la ventana de servicio sigue activa.

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

Cuerpo de la solicitud

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "content": "¡Hola! ¿En qué puedo ayudarte?",
  "client": {
    "name": "José",
    "customFields": {
      "placas": "ABC123"
    }
  }
}

Parámetros del cuerpo

Tipos de mensaje

content puede ser un texto simple o un objeto estructurado. Cuando es objeto, debes especificar type y la forma de content depende del tipo.

Texto

Forma corta:

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "content": "¡Hola! ¿En qué puedo ayudarte?"
}

Forma explícita:

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "text",
  "content": { "text": "¡Hola! ¿En qué puedo ayudarte?" }
}

Imagen

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "image",
  "content": {
    "image": {
      "url": "https://cdn.assets.com/foto.jpg",
      "caption": "Aquí está la foto que me pediste"
    }
  }
}

Video

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "video",
  "content": {
    "video": {
      "url": "https://cdn.assets.com/video.mp4",
      "caption": "Mira este video"
    }
  }
}

Documento / archivo

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "file",
  "content": {
    "file": {
      "url": "https://cdn.assets.com/factura.pdf",
      "filename": "factura-2025-09.pdf",
      "caption": "Tu factura del mes"
    }
  }
}

Audio

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "audio",
  "content": {
    "audio": {
      "url": "https://cdn.assets.com/nota.ogg"
    }
  }
}

Mensajes interactivos

Los mensajes interactivos (botones, listas y flows) están disponibles únicamente en WhatsApp.

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "interactive",
  "content": {
    "type": "button",
    "body": { "text": "¿Quieres confirmar tu cita?" },
    "action": {
      "buttons": [
        { "id": "confirmar", "title": "Sí, confirmar" },
        { "id": "reagendar", "title": "Reagendar" },
        { "id": "cancelar", "title": "Cancelar" }
      ]
    }
  }
}

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "interactive",
  "content": {
    "type": "list",
    "body": { "text": "Elige el horario que prefieras" },
    "action": {
      "button": "Ver horarios",
      "sections": [
        {
          "title": "Esta semana",
          "rows": [
            { "id": "lun-10", "title": "Lunes 10:00", "description": "Disponible" },
            { "id": "mar-12", "title": "Martes 12:00", "description": "Disponible" }
          ]
        }
      ]
    }
  }
}

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "interactive",
  "content": {
    "type": "flow",
    "body": { "text": "Completa tu registro en menos de un minuto" },
    "action": {
      "parameters": {
        "flow_id": "1234567890",
        "flow_cta": "Empezar"
      }
    }
  }
}

Instrucción al agente

Una instrucción no se envía al cliente: actúa sobre el agente que opera la conversación. Es útil cuando estás supervisando el chat desde la API y quieres que el agente espere o retome el control. El campo mode define el comportamiento.

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "type": "instruction",
  "content": {
    "text": "Espera a que el cliente confirme la cita antes de continuar.",
    "mode": "wait"
  }
}

Comportamiento por modo

• wait: registra la instrucción como mensaje de sistema en el historial y deja la conversación esperando al próximo mensaje del cliente. El agente no responde de inmediato; cuando entre el siguiente mensaje del cliente, leerá la instrucción como contexto.
• resume: marca la conversación como reanudada y dispara al agente para que continúe el flujo usando la instrucción como guía. El agente puede decidir responder al cliente o no según su propia lógica.

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

Programación

Igual que en Enviar Plantilla , puedes enviar el mensaje inmediatamente, con un retraso, o en una fecha específica. Después puedes consultarlo, reprogramarlo o cancelarlo por messageId .

Respuesta

La respuesta varía según si el mensaje se envía de forma inmediata, diferida o programada.

Envío inmediato:

{
  "messageId": "msg_123xyz",
  "status": "sent",
  "timestamp": "2026-09-20T20:00:00Z"
}

Con delay (HTTP 202):

{
  "messageId": "msg_123xyz",
  "kind": "service",
  "status": "delayed",
  "timestamp": "2026-09-20T20:00:00Z",
  "executeAt": "2026-09-20T20:00:05.000Z",
  "delayMs": 5000
}

Con scheduleTime (HTTP 202):

{
  "messageId": "msg_123xyz",
  "kind": "service",
  "status": "scheduled",
  "timestamp": "2026-09-20T20:00:00Z",
  "executeAt": "2026-10-16T00:40:00.000Z",
  "scheduledTime": "2026-10-15T18:40:00"
}

Los envíos con delay o scheduleTime quedan aceptados, pero todavía no enviados. Consulta Mensajes Programados para conocer sus estados y reglas de ejecución.

Reglas por canal

WhatsApp

• Plantillas obligatorias para iniciar conversación. Una vez que el cliente responde, la ventana de servicio queda abierta 24 horas y puedes enviar cualquier tipo de mensaje hasta que se cierre.
• Cada mensaje del cliente reinicia la ventana.
• Soporta texto, imágenes, videos, archivos, audio, botones, listas y flows.

Instagram y Facebook

• Soporta texto, imágenes, videos, archivos y audio. Los mensajes interactivos (botones, listas, flows) no están disponibles fuera de WhatsApp.
• La ventana se calcula desde el último mensaje del usuario; valida canSendDirectMessage antes de enviar.

Canales internos (chats con agentes)

POST /v1/messages también funciona sobre las conversaciones internas creadas por la API de Chat . Identifica el hilo con el conversationId del chat (chat_*) o con su channelId interno:

{
  "channelId": "workspace-ws_001-agent-agent_001",
  "conversationId": "chat_01JCHAT23456789",
  "content": "Un asesor revisará tu caso en unos minutos."
}

• Tipos soportados: text, image, video, file, audio e instruction. Los mensajes interactive, email y las plantillas son exclusivos de canales externos y devuelven 422 en un canal interno.
• Las instrucciones al agente (wait / resume) funcionan exactamente igual que en canales externos.
• No hay ventana de servicio en canales internos: canSendDirectMessage siempre es true.

Matriz de compatibilidad por canal

¹ email solo está disponible en canales de correo conectados; en un canal interno devuelve 422.

Consultar estado

Verifica si tu mensaje fue entregado:

1. Desde la bandeja de entrada de la plataforma.
2. Usando el endpoint Obtener Conversación .