WhatsApp Template API

API para desarrolladores

Envíe plantillas de WhatsApp aprobadas desde sus propios sistemas con una sola llamada de API; la conversación continúa después en MonoChat.

• WhatsApp
• API REST
• Solo API

Instalar desde MonoStoreVerlo en monochat.ai

Descripción general

WhatsApp Template API permite que su CRM, ERP, tienda online o cualquier backend envíe un mensaje de plantilla de WhatsApp aprobado a un cliente a través de MonoChat. Una sola solicitud indica el número de WhatsApp desde el que enviar, el teléfono del cliente, la plantilla y sus variables.

Cuando el cliente responde, la conversación llega a su bandeja de entrada de MonoChat como cualquier otra. La app no tiene pantallas propias: todo ocurre a través de tres endpoints de API.

Aspectos destacados

• Una llamada de API. Envíe una plantilla por nombre e idioma, con las variables de encabezado, cuerpo, botón y carrusel rellenadas con sus datos.
• Directo al chat. Cada envío devuelve el id de la conversación y un enlace directo a ella en MonoChat.
• Los clientes nuevos son bienvenidos. Si el número de teléfono aún no es un cliente, se crea el cliente con el nombre que envíe.

Instalación y configuración

1. Conecte su número de WhatsApp Business a MonoChat y asegúrese de que esté verificado y tenga plantillas aprobadas por Meta.
2. Instale WhatsApp Template API desde Configuración › MonoStore › Aplicaciones, o abra el enlace de instalación app.monochat.ai/apps/K6u29LpbwCHBozZ8o. Si no tiene una cuenta de MonoChat, el enlace le permite registrarse primero e instala la app por usted.
3. Cree un token de API en Perfil › Tokens de API. El token se muestra una sola vez, así que cópielo de inmediato.
4. Llame a template/list.js para ver sus plantillas aprobadas y sus variables.
5. Llame a template/send.js con el número del cliente y los valores de las variables para enviar su primera plantilla.

nota

• Cada mensaje se factura como cualquier mensaje de plantilla enviado desde MonoChat.
• Las URL de los archivos multimedia deben seguir accesibles hasta que WhatsApp haya descargado el archivo.
• Envíe solo a clientes que aceptaron recibir sus mensajes: WhatsApp puede limitar los números cuyos mensajes se bloquean o se denuncian.

Funciones

Listar plantillas

Las plantillas aprobadas de un número de WhatsApp, con su idioma, categoría, estado y variables, para que su sistema sepa qué puede enviar.

Enviar una plantilla

Por nombre de plantilla e idioma, con variables de encabezado, cuerpo, botón y carrusel. Si falta un valor, el envío se detiene, así que nada a medio rellenar llega al cliente.

Asignar a un agente

Indique el correo electrónico de un agente y la conversación se abre a su nombre.

Encabezados multimedia

Obtenga credenciales de subida de corta duración, suba una imagen, un vídeo o un documento al almacenamiento de MonoChat y use su URL como encabezado de la plantilla.

Enlace a la conversación

Cada envío devuelve el id de sesión, el id del mensaje y un enlace que abre la conversación en MonoChat.

Errores claros

Una llamada fallida indica qué salió mal, por ejemplo “Channel not found” o “Variable missing”.

Antes de empezar

• Su número de WhatsApp Business está conectado a MonoChat y verificado. Consulte Canales.
• Las plantillas que desea enviar están aprobadas por Meta. Las plantillas son la forma de escribir primero o de contactar con un cliente fuera de la ventana de 24 horas. Consulte Mensajes de plantilla.
• Tiene un token de API de Perfil › Tokens de API. Consulte Tokens de API.
• Conoce su tenant slug: la parte posterior a /tenants/ en su dirección de MonoChat. En https://app.monochat.ai/tenants/mybusiness el slug es mybusiness.

Referencia de la API

La app no tiene pantallas propias. Todo ocurre a través de tres endpoints, cada uno un POST con un cuerpo JSON:

POST https://app.monochat.ai/api/<slug>/custom-functions/template-app/api/<endpoint>
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

Endpoint	Qué hace
template/list.js	Lista las plantillas de uno de sus números de WhatsApp, con sus variables.
template/send.js	Envía una plantilla a un cliente y devuelve un enlace a la conversación.
upload/get-token.js	Proporciona credenciales de subida de corta duración para una imagen, un vídeo o un documento de encabezado.

Los números de teléfono se escriben siempre con el prefijo de país y sin +, por ejemplo 905334445566. Una llamada correcta responde 200 con los datos del endpoint en result.

1. Listar plantillas

POST /api/<slug>/custom-functions/template-app/api/template/list.js

Lista todas las plantillas del número de WhatsApp Business indicado: nombre, código de idioma, categoría, componentes (encabezado, cuerpo, pie, botones), tipos de variables y estado de aprobación.

Campo	Obligatorio	Descripción
phoneNumber	sí	Su número de WhatsApp Business en MonoChat, con prefijo de país, sin +.
options	no	Paginación y filtros, por ejemplo { "pagination": { "currentPage": 1, "pageItems": 50 } }.

POST /api/<slug>/custom-functions/template-app/api/template/list.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566"
}

Respuesta (abreviada):

{
  "result": {
    "templateMessages": [
      {
        "name": "new_product_announcement",
        "languageCode": "tr-TR",
        "category": "MARKETING",
        "components": [
          {
            "type": "HEADER",
            "format": "IMAGE",
            "variables": [
              { "type": "IMAGE", "value": null, "exampleValue": "https://.../sample-image.png" }
            ]
          },
          {
            "type": "BODY",
            "text": "Merhaba {{1}}, yeni ürünümüz {{2}} çıktı!",
            "sampleText": "Merhaba [Ayşe], yeni ürünümüz [XYZ Telefon] çıktı.",
            "variables": [
              { "type": "TEXT", "value": null, "exampleValue": "[Ayşe]" },
              { "type": "TEXT", "value": null, "exampleValue": "[XYZ Telefon]" }
            ]
          },
          {
            "type": "FOOTER",
            "text": "Teşekkürler",
            "sampleText": "Teşekkürler"
          }
        ],
        "status": "APPROVED"
      }
    ],
    "options": {
      "pagination": { "totalCount": 12, "currentPage": 1, "pageItems": 12, "totalPages": 1 }
    }
  }
}

Cómo leerla:

• name: el nombre de sistema con el que envía la plantilla.
• languageCode: el idioma en el que se envía.
• category: la categoría de WhatsApp (MARKETING, UTILITY, AUTHENTICATION).
• components: las partes de las que se compone la plantilla.

Componente	Contenido	Descripción
HEADER	IMAGE, VIDEO, DOCUMENT o texto	Para contenido multimedia se indica el format; las variables aparecen en variables.
BODY	Texto con variables	El cuerpo del mensaje, con marcadores como {{1}}, {{2}}.
FOOTER	Texto	Normalmente no tiene variables.
BUTTONS	URL, respuesta rápida…	Textos de los botones y sus variables, si las hay.

La plantilla de ejemplo anterior necesita una imagen para el encabezado y dos textos para el cuerpo (nombre del cliente y nombre del producto). El pie es fijo ("Teşekkürler") y no hay botones.

2. Enviar una plantilla

POST /api/<slug>/custom-functions/template-app/api/template/send.js

Envía una plantilla aprobada a un cliente. Si el número de teléfono aún no es un cliente, se crea el cliente; la conversación se abre (o se reutiliza) y la plantilla se envía en ella.

Campo	Obligatorio	Descripción
phoneNumber	sí	El número de WhatsApp Business desde el que enviar. Debe estar conectado a MonoChat y verificado.
templateMessageName	sí	El name de la plantilla, tal como lo devuelve la lista.
languageCode	sí	El idioma de la plantilla, tal como lo devuelve la lista (por ejemplo tr-TR).
customerPhoneNumber	sí	El número de WhatsApp del cliente.
variables	cuando la plantilla tenga alguna	Los valores de las variables de la plantilla (véase más abajo).
customerFirstName, customerLastName	no	Se usan cuando el cliente es nuevo en MonoChat.
agentEmailAddress	no	Asigna la conversación al agente con este correo electrónico.

Variables. Cada elemento del array variables tiene un type y una lista de parameters, indicados en el orden de los marcadores de la plantilla:

type	parameters
HEADER	La variable de texto del encabezado, o la URL pública de la imagen, el vídeo o el documento del encabezado.
BODY	Los {{1}}, {{2}}, … del cuerpo, en orden.
BUTTONS	Un valor por cada botón que tenga una variable (por ejemplo la parte dinámica de un botón de URL o un código de cupón), en el orden de los botones.
CAROUSEL	En lugar de parameters, un array cards con una entrada por cada tarjeta del carrusel, cada una con sus propios components.

{ "type": "CAROUSEL", "cards": [ { "components": [ { "type": "HEADER", "parameters": ["https://…/1.jpg"] }, { "type": "BODY", "parameters": ["…"] } ] } ] }

Si falta un valor, el envío se detiene con Variable missing, así que nada a medio rellenar llega al cliente. FOOTER rara vez tiene variables.

POST /api/<slug>/custom-functions/template-app/api/template/send.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "phoneNumber": "905334445566",
  "templateMessageName": "new_product_announcement",
  "languageCode": "tr-TR",
  "customerPhoneNumber": "905306667788",
  "customerFirstName": "Ayşe",
  "agentEmailAddress": "sarah@yourcompany.com",
  "variables": [
    { "type": "HEADER", "parameters": ["https://…/product.jpg"] },
    { "type": "BODY", "parameters": ["Ayşe", "XYZ Phone"] }
  ]
}

Respuesta:

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "…",
    "messageId": "…"
  }
}

• url: abre la conversación en MonoChat, para las personas que han iniciado sesión y tienen permiso para verla.
• sessionId: el id de la conversación.
• messageId: el id del mensaje en MonoChat. Su estado de entrega y lectura aparece en el chat como el de cualquier otro mensaje.

Contenido multimedia en las plantillas. WhatsApp descarga el contenido multimedia del encabezado desde la URL que usted indica, por lo que la URL debe ser válida y de acceso público. Los enlaces que requieren iniciar sesión no funcionan. Si subió el archivo con upload/get-token.js, use la URL del archivo construida a partir de esa respuesta.

3. Subir contenido multimedia para un encabezado

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js

Cuando el encabezado de una plantilla es una imagen, un vídeo o un documento, el archivo necesita una dirección pública desde la que WhatsApp pueda descargarlo. Este endpoint le da un permiso de corta duración para colocar el archivo en el almacenamiento de MonoChat.

Campo	Obligatorio	Descripción
fileName	sí	El nombre del archivo con su extensión, por ejemplo product.jpg o promo.pdf.

Los archivos se guardan siempre en la carpeta chat-assets de su espacio de trabajo; los ejemplos antiguos que envían un campo key siguen funcionando, el valor no es necesario.

POST /api/<slug>/custom-functions/template-app/api/upload/get-token.js
Content-Type: application/json
Authorization: Bearer <API_TOKEN>

{
  "fileName": "product.jpg"
}

La respuesta indica dónde colocar el archivo y proporciona las credenciales para hacerlo:

Campo	Descripción
bucket, region, path	Dónde va el archivo.
temporaryCredentials	Credenciales solo de subida para esa única ruta, válidas durante 15 minutos.
baseUrl	La dirección pública del almacenamiento. La URL del archivo es baseUrl + / + path.

Suba el archivo de inmediato con cualquier cliente S3 usando estas credenciales y, después, pase su URL como parámetro HEADER al enviar la plantilla. Los archivos muy grandes o los formatos que WhatsApp no admite (acepta los formatos habituales de imagen, vídeo y PDF) fallan.

Ejemplo: una plantilla con encabezado de imagen

Supongamos que tiene una plantilla aprobada new_product_announcement con un encabezado de imagen y dos variables en el cuerpo (nombre del cliente y nombre del producto), y desea enviarla a un cliente.

1. Liste las plantillas. Llame a template/list.js con su número de WhatsApp y busque new_product_announcement. Sus componentes muestran una variable IMAGE en el encabezado y dos variables TEXT en el cuerpo.
2. Suba la imagen. Llame a upload/get-token.js con { "fileName": "urun.jpg" }, suba el archivo con las credenciales devueltas y construya su URL a partir de baseUrl y path.
3. Envíe la plantilla. Llame a template/send.js con la URL del archivo como parámetro HEADER y ["Ayşe", "XYZ Telefon"] como parámetros BODY ({{1}} → Ayşe, {{2}} → XYZ Telefon). Si la plantilla tuviera variables en los botones, añadiría un elemento BUTTONS de la misma manera.
4. Abra el chat. La url de la respuesta abre la conversación; cuando el cliente responde, esta continúa en su bandeja de entrada de MonoChat.

Errores

Una llamada fallida responde con un estado de error y un mensaje que indica qué salió mal. Registre estos mensajes en su sistema y muestre un mensaje comprensible a sus usuarios cuando sea necesario.

Mensaje	Causa
phoneNumber field is required	Se llamó a template/list.js sin phoneNumber.
phoneNumber, templateMessageName, customerPhoneNumber fields are required	Falta un campo obligatorio de template/send.js.
Channel not found	El phoneNumber no es un número de WhatsApp de su espacio de trabajo.
Channel is not verified	El número de WhatsApp está conectado, pero no verificado.
Template message not found	No hay ninguna plantilla aprobada con ese nombre e idioma en el número. Compruebe la ortografía y el languageCode.
Template message is not approved	La plantilla existe, pero no está aprobada por Meta.
Variable missing: …	variables no coincide con la plantilla, por ejemplo la plantilla necesita dos valores en el cuerpo y usted envió uno.
Agent user not found	No hay ningún agente con el correo electrónico indicado en agentEmailAddress.
Customer Channel not found	No se pudo crear ni encontrar la identidad de WhatsApp del cliente.

Códigos de estado HTTP que puede ver:

• 401 Unauthorized: falta la cabecera Authorization: Bearer <API_TOKEN>, o el token es incorrecto o ha caducado. Use un token válido de su cuenta.
• 403 Forbidden: el token no tiene acceso a este espacio de trabajo o app, por ejemplo por un tenant slug incorrecto.
• 404 Not Found: la dirección del endpoint es incorrecta. Compruebe la ruta completa /api/<slug>/custom-functions/template-app/api/....
• 500 Internal Server Error: un problema inesperado en MonoChat o en el proveedor de WhatsApp, o un rechazo por parte de WhatsApp (el número no está en WhatsApp, el cliente le ha bloqueado, límites de calidad o de frecuencia). Inténtelo de nuevo más tarde y contacte con el soporte de MonoChat si persiste.

Capturas de pantalla

Envío de una plantilla de WhatsApp aprobada desde un CRM, ERP o sistema de comercio electrónico con una sola llamada de API a través de MonoChatLa lista de plantillas de WhatsApp aprobadas con sus variablesEnviar una plantilla a un número nuevo crea el cliente automáticamenteUna plantilla enviada en varios idiomasPlantillas con encabezados de imagen, vídeo, documento y PDF

Preguntas frecuentes

¿Tiene WhatsApp Template API una interfaz de usuario?

No. Es una app solo de API con tres endpoints: listar plantillas, enviar una plantilla y obtener credenciales de subida para encabezados multimedia.

¿Qué necesito antes de poder usarla?

Un número de WhatsApp Business conectado a MonoChat y verificado, plantillas aprobadas por Meta y un token de API de Perfil › Tokens de API.

¿Qué pasa cuando el cliente responde?

La conversación llega a su bandeja de entrada de MonoChat como cualquier otra. Cada envío devuelve además un enlace directo a la conversación, y puede asignarla a un agente por correo electrónico.

¿Puedo enviar a un número que aún no es cliente?

Sí. Si el número de teléfono aún no es un cliente, se crea el cliente con el nombre que envíe.

¿Cuánto cuestan los mensajes de plantilla?

Cada mensaje se factura como cualquier mensaje de plantilla enviado desde MonoChat. Meta fija el precio de las plantillas según la categoría y el país del destinatario; use la calculadora de costes de mensajería masiva de WhatsApp para estimar un envío.

Relacionado

• Session Link
• Bulk Template Message API
• Mensajes de plantilla
• Apps de MonoStore