Iniciar Conversación

Envía una plantilla de WhatsApp aprobada para iniciar una conversación con un cliente. Si ya existe una conversación abierta, el mensaje se añade a ella; si no, se crea una nueva.

Nota

Actualmente, este endpoint solo es compatible con el canal de WhatsApp.

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

Cuerpo de la solicitud

{
  "channelId": "521234567890",
  "conversationId": "521234567890",
  "template": {
    "name": "bienvenida_cliente",
    "params": ["Juan", "Premium"],
    "type": "image",
    "file": "https://cdn.assets.com/welcome_image.jpg"
  },
  "client": {
    "name": "José",
    "customFields": {
      "placas": "ABC123",
      "id_recepcion": "REC001"
    }
  }
}

Parámetros del cuerpo

Campo	Tipo	Descripción	Requerido
`channelId`	string	ID interno del canal O número de teléfono del agente (formato E.164 sin `+`)	✓
`conversationId`	string	ID público de la conversación (Hash o número de teléfono del usuario en formato E.164 sin `+`)	✓
`template.name`	string	Nombre de la plantilla a utilizar	✓
`template.params`	array	Variables para la plantilla	—
`template.type`	enum	Tipo de encabezado: `image`, `document`, `video`	—
`template.file`	string	URL del archivo para el encabezado	—
`template.buttons`	map	Botones contenidos en la plantilla	—
`delay`	number	Retraso en milisegundos (3,000 - 86,400,000)	—
`scheduleTime`	string	Fecha/hora de envío programado (ISO 8601)	—
`client`	object	Información del cliente a actualizar (Upsert)	—

Consejo

Si se envía el objeto client, se actualizará la información del perfil del cliente (o se creará si no existe), permitiendo al agente de IA tener acceso inmediato a los nuevos datos.

Envío con retraso (delay):

Mínimo: 3000 ms (3 segundos)
Máximo: 86400000 ms (24 horas)
Ejemplo: "delay": 5000 envía el mensaje en 5 segundos

Envío programado (scheduleTime):

Formato ISO 8601
Ejemplos:
- "2025-07-01T18:40:00" — Hora de México (UTC-6)
- "2025-07-01T18:40:00Z" — Hora UTC
- "2025-07-01T18:40:00-06:00" — Con zona horaria específica

Advertencia

No puedes usar delay y scheduleTime en la misma solicitud.

Campo	Tipo	Descripción
`client.name`	string	Nombre completo del cliente
`client.firstname`	string	Primer nombre
`client.lastname`	string	Apellido
`client.email`	string	Correo electrónico
`client.birthdate`	string	Fecha de nacimiento (dd/mm/yyyy)
`client.gender`	enum	Género: `male` o `female`
`client.company`	string	Nombre de la compañía
`client.country`	enum	Código ISO 3166-1 alpha-2 (ej: `MX`, `US`)
`client.state`	string	Estado de residencia
`client.city`	string	Ciudad de residencia
`client.address`	string	Dirección completa
`client.postalCode`	string	Código postal
`client.customFields`	map	Objeto con pares clave-valor de los campos personalizados definidos en el workspace. Consulta Campos Personalizados para ver los disponibles.
`client.owners`	array	Correos de usuarios responsables

Respuesta

{
  "messageId": "msg_123xyz",
  "status": "sent",
  "timestamp": "2025-02-14T12:00:00Z"
}

Reglas de WhatsApp

Plantillas obligatorias

Para iniciar una conversación debes usar una plantilla pre-aprobada. No puedes enviar mensajes de texto libre hasta que el cliente responda.

Ventana de 24 horas

Las conversaciones permanecen activas durante 24 horas desde el último mensaje del cliente.

Si el cliente NO responde:

Envías la plantilla
El cliente no responde
No puedes enviar más mensajes hasta que responda

Si el cliente SÍ responde:

Envías la plantilla
El cliente responde
Puedes enviar mensajes libremente durante 24 horas
La ventana se reinicia con cada mensaje del cliente

Limitaciones de entrega

WhatsApp puede bloquear mensajes por:

Restricciones del país del cliente
Números en experimentos de WhatsApp
Clientes que desactivaron notificaciones de marketing

Consultar estado

Verifica si tu mensaje fue entregado:

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

Anterior Introducción Siguiente Enviar Mensaje Personalizado