Skip to main content
POST
Envía una plantilla de WhatsApp en nombre del negocio, identificándola por el id interno obtenido en el listado de plantillas. No requiere un chat_id ni un contacto_id preexistentes: si el número no tiene contacto o conversación registrada, ambos se crean automáticamente. Es el endpoint indicado para disparos externos, integraciones de CRM y flujos donde el negocio inicia el contacto sin intervención de un agente.

​
Autenticación

Requiere el encabezado x-api-key con el App Key del negocio. Consulta Autenticación.

​
Encabezados

​
string
required
App Key del negocio. Consulta Autenticación.

​
Cuerpo de la solicitud

​
number
required
ID del negocio que envía la plantilla. Debe ser numérico.
​
string
required
Número de WhatsApp del destinatario. Se aceptan formatos con separadores (guiones, espacios, +): el sistema conserva únicamente los dígitos. +52 155 1234 5678 y 5215512345678 son equivalentes.
​
number
required
ID interno de la plantilla, tomado del campo id del listado. Debe pertenecer a empresa_id; de lo contrario responde 404.
​
string[]
default:"[]"
Valores que sustituyen los marcadores {{1}}, {{2}}, … del cuerpo de la plantilla, en orden posicional: el primer elemento reemplaza {{1}}, el segundo {{2}}, y así sucesivamente.Cada elemento debe ser un string. El sistema los envuelve automáticamente como { type: "text", text: "..." } dentro de un componente body antes de enviarlos a Meta.
Debe ser un arreglo; cualquier otro tipo se rechaza con 400. Consulta cómo saber cuántos parámetros requiere una plantilla.
​
string
Nombre del contacto, usado solo si se crea en esta llamada. Si se omite, se usa el número. Debe ser texto; otro tipo se rechaza con 400.
​
string
URL pública https:// que reemplaza, solo para este envío, la imagen/video/documento del encabezado. Solo aplica si la plantilla tiene encabezado multimedia (type ≠ text) y empieza con https://; si no, 400.Si se omite, se usa el archivo de la plantilla. Para un archivo local, súbelo primero con Subir Media.
Reemplazar la imagen
Usar la imagen ya guardada
El número de elementos en parameters debe coincidir exactamente con el número de marcadores del cuerpo de la plantilla — ni de más ni de menos. Si mandas parámetros de más (incluida una plantilla sin marcadores, con parameters no vacío) o de menos, Meta rechaza el mensaje y la respuesta será 400 Error al enviar la plantilla. Este endpoint no valida la cantidad antes de llamar a Meta.

​
Comportamiento

1

Validación

Se verifican los tipos de todos los campos, y que la empresa y la plantilla existan y estén relacionadas entre sí.
2

Resolución del contacto

Se normaliza phone_number a solo dígitos y se busca el contacto. Si no existe, se crea con name (o el número) como nombre.
3

Resolución del chat

Se busca una conversación del contacto en esa empresa. Si no existe, se crea con estado bot, bot disponible y proveedor fb-apicloud.
4

Envío y registro

Se envía la plantilla por WhatsApp Cloud API y se registra el mensaje en la conversación, con los marcadores ya sustituidos por los valores de parameters, atribuido al nombre del negocio.

​
Respuesta

​
boolean
true cuando la plantilla fue enviada y registrada correctamente.
La respuesta exitosa no incluye el identificador del mensaje (wamid). Para dar seguimiento al estado de entrega, consulta la conversación del contacto.
Antes de probar el curl, no adivines plantilla_id ni cuántos parameters lleva: llama a Listar Plantillas, busca en la respuesta el objeto cuyo id es tu plantilla_id, y cuenta el marcador {{n}} más alto en su descripcion (o en template.components tipo BODY, si está disponible). Ese número es la cantidad de elementos que debe traer parameters, en ese mismo orden.

​
Errores comunes

​
Imagen (u otro medio) del encabezado

Si la plantilla tiene un encabezado multimedia (type distinto de text), por defecto se envía el archivo subido al crear la plantilla (dashboard → Plantillas → Crear plantilla → encabezado tipo Medios). Para usar un archivo distinto sin crear una plantilla nueva, manda media_url con la URL pública del archivo que quieres usar en su lugar — aplica solo a ese envío, la plantilla guardada no se modifica. Si el archivo que quieres usar está en tu equipo o servidor local (no tiene una URL pública todavía), súbelo primero con Subir Media y usa la media_url que te devuelve.