API Cloud (Templates)
Las plantillas se usan en mensajes de plantillas para abrir conversaciones de marketing, utilidad y autenticación con los clientes. A diferencia de los mensajes de formato libre, las plantillas de mensajes son el único tipo de mensaje que se puede enviar a los clientes que todavía no han iniciado una conversación contigo o que no te han enviado ningún mensaje en las últimas 24 horas.
Para más información de todos los endpoints que tenemos a continuación es bueno consultar: https://developers.facebook.com/docs/whatsapp/message-templates/guidelines/
Los endpoints que se ponen a continuación se pueden consultar con varias versiones de Meta, es importante en cada url establecer la versión (VERSION) de meta que se utilizará.
La variable VERSION de debe expresar con la letra ‘v’ y sus valores serán: v16.0, v17.0, v18.0, v19.0
Crear nueva plantilla
Plantillas de solo texto
Path:
POST /message_templates/VERSION/{did}
-
Request
-
Body
{
"name": "pedido_cancelado_reembolso",
"language": "es",
"category": "UTILITY",
"allow_category_change": true,
"components": [
{
"type": "BODY",
"text": "Su pedido ha sido cancelado; su reembolso se procesará en 7-10 días"
}
]
}
Descripcion de propiedades
| Fields | Type | Comentario |
|---|---|---|
| name | String | Nombre de la plantilla. Máximo 512 caracteres. |
| category | Enum | Categoría de la plantilla. Consulta Categorías de plantillas a continuación |
| allow_category_change | boolean | Se establece en verdadero para permitirnos asignar automáticamente una categoría. Si se omite, es posible que la plantilla se rechace a causa de una categorización incorrecta. |
| language | Enum | Código de idioma y configuración regional de la plantilla. |
| components | Object | Componentes que conforman la plantilla. Consulta Componentes de la plantilla a continuación. |
Response
Status Code 200
{
"id": "<ID>",
"status": "<STATUS>",
"category": "<CATEGORY>"
}
Descripcion de propiedades
| Fields | Type | Comentario |
|---|---|---|
| id | String | Identificador de la plantilla. |
| status | Enum | Estado de la plantilla. |
| category | Enum | Categorías de plantillas |
Creación de template de con header de imagen y body de texto
Path:
POST /message_templates/VERSION/{did}
-
Request
-
Body
{
"name": "isv_template",
"language": "es_ES",
"category": "MARKETING",
"components": [
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": [
"4::aW1h" // este valor se obtiene unos puntos mas abajo en el momento de cargar la imagen a meta
]
}
},
{
"type": "BODY",
"text": "Shop now through {{1}} and use code {{2}} to get {{3}} off of all merchandise.",
"example": {
"body_text": [
[
"the end of August","25OFF","25%"
]
]
}
},
{
"type": "FOOTER",
"text": "Use the buttons below to manage your marketing subscriptions"
},
{
"type":"BUTTONS",
"buttons": [
{
"type": "QUICK_REPLY",
"text": "Unsubscribe from Promos"
},
{
"type":"QUICK_REPLY",
"text": "Unsubscribe from All"
}
]
}
]
}
Response
Status Code 200
{
"id": "<ID>",
"status": "<STATUS>",
"category": "<CATEGORY>"
}
Descripcion de propiedades
| Fields | Type | Comentario |
|---|---|---|
| id | String | Identificador de la plantilla. |
| status | Enum | Estado de la plantilla. |
| category | Enum | Categorías de plantillas |
Editar plantilla
Path:
PUT /message_templates/VERSION/{did}/{message_template_id}
Limitaciones
- Solo se pueden editar las plantillas con uno de los siguientes estados: APPROVED, REJECTED o PAUSED.
- Solo puedes editar las propiedades category o components de una plantilla.
- No puedes editar la propiedad category de una plantilla aprobada.
- Las plantillas aprobadas se pueden editar un máximo de diez veces en un periodo de 30 días o una vez cada 24 horas. Las plantillas rechazadas o en pausa se pueden editar un número ilimitado de veces.
- Después de editar una plantilla aprobada o en pausa, se aprobará automáticamente a menos que no supere la revisión.
Request
- Body
{
"category": "<CATEGORY>",
"components": [{
"type": "HEADER",
"format": "TEXT",
"text": "Hola y bienvenido"
}]
}
Descripcion de propiedades
| Fields | Type | Comentario |
|---|---|---|
| category | Enum | Categoría de la plantilla. Consulta Categorías de plantillas a continuación |
| components | Object | Componentes que conforman la plantilla. Consulta Componentes de la plantilla a continuación. |
Response
Status Code 200
{
"success": true
}
Obtener Plantilla
Obtener lista de plantillas
Path:
GET /message_templates/VERSION/{did}?fields=format,rejected_reason,quality_score,status,name,language,components,category,previous_category&limit=5
Response
Status Code 200
{
"data": [
{
"id": "2606927862810126",
"name": "un_template",
"components": [
{
"type": "BODY",
"text": "this is"
}
],
"language": "es",
"status": "REJECTED",
"category": "UTILITY",
"rejected_reason": "INCORRECT_CATEGORY",
"quality_score": {
"score": "UNKNOWN"
}
},
{
"id": "402086912569912",
"name": "test_template_dev",
"components": [
{
"type": "BODY",
"text": "this is a test"
}
],
"language": "es",
"status": "APPROVED",
"category": "MARKETING",
"rejected_reason": "NONE",
"quality_score": {
"score": "UNKNOWN"
}
}
],
"paging": {
"cursors": {
"before": "MAZDZD",
"after": "MQZDZD"
},
"next": "https://login.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v19.0/56940581384?fields=format,rejected_reason,quality_score,status,name,language,components,category,previous_category&limit=2&after=MQZDZD"
}
}
Obtener sumario de plantillas
Path:
GET /message_templates/VERSION/{did}?fields=id&limit=1&summary=total_count,message_template_count,message_template_limit,are_translations_complete
Response
Status Code 200
{
"data": [
{
"id": "2606927862810126"
}
],
"paging": {
"cursors": {
"before": "MAZDZD",
"after": "MAZDZD"
},
"next": "https://login.chattigo.com/bsp-cloud-chattigo-isv/message_templates/v19.0/56940581384?limit=1&summary=total_count,message_template_count,message_template_limit,are_translations_complete&fields=id&after=MAZDZD"
},
"summary": {
"total_count": 169,
"message_template_count": 148,
"message_template_limit": 6000,
"are_translations_complete": false
}
}
Obtener plantilla por nombre o contenido
Path:
GET /message_templates/VERSION/{did}?name_or_content=tpl_flow_demo_preview&limit=1
Response
Status Code 200
{
"data": [
{
"id": "210800678688659",
"name": "tpl_flow_demo_preview",
"components": [
{
"type": "BODY",
"text": "Hola y bienvenido a la demo de flow.\nPuedes responder a continuación las preguntas iniciales."
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "FLOW",
"text": "Responder",
"flow_id": 2033644160334325,
"flow_action": "NAVIGATE",
"navigate_screen": "REGISTER"
}
]
}
],
"language": "es",
"status": "APPROVED",
"category": "MARKETING"
}
],
"paging": {
"cursors": {
"before": "MAZDZD",
"after": "MAZDZD"
}
}
}
Obtener plantilla por nombre
Path:
GET /message_templates/VERSION/{did}?name=tpl_flow_demo_preview&limit=1
Response
Status Code 200
{
"data": [
{
"id": "210800678688659",
"name": "tpl_flow_demo_preview",
"components": [
{
"type": "BODY",
"text": "Hola y bienvenido a la demo de flow.\nPuedes responder a continuación las preguntas iniciales."
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "FLOW",
"text": "Responder",
"flow_id": 2033644160334325,
"flow_action": "NAVIGATE",
"navigate_screen": "REGISTER"
}
]
}
],
"language": "es",
"status": "APPROVED",
"category": "MARKETING"
}
],
"paging": {
"cursors": {
"before": "MAZDZD",
"after": "MAZDZD"
}
}
}
Cargar Multimedia
Para cargar una imagen nueva a meta se envía consulta el siguiente endpoint.
POST /VERSION/{did}/uploads
En el header se debe incluir el token obtenido luego de la autenticación.
["Authorization" : "<JWT>"]
En el Body será necesario introducir un form-data con la imagen a cargar, será introducido con el nombre file:
Definición de Objeto
| Fields | Type | Mandatory | Descripción |
|---|---|---|---|
| file | File | yes | Imagen a cargar |
Response
StatusCode 200
{
"h": "4::aW1hZ2............."
}
Métricas de las Plantillas
Path:
GET /message_templates/VERSION/{did}/analytics?granularity=DAILY&metric_types=[“CLICKED”,“DELIVERED”,“READ”,“SENT”]&start=1709769600&end=1709841600&template_ids=[776614587250474]
Response
Status Code 200
{
"data": [
{
"granularity": "DAILY",
"data_points": [
{
"template_id": "776614587250474",
"start": 1709769600,
"end": 1709856000,
"sent": 2,
"delivered": 2,
"read": 2,
"clicked": [
{
"type": "url_button",
"button_content": "Visitar el sitio web",
"count": 1
},
{
"type": "url_button",
"button_content": "Visitar el sitio web 2",
"count": 1
},
{
"type": "quick_reply_button",
"button_content": "Si",
"count": 1
}
]
}
]
}
],
"paging": {
"cursors": {
"before": "MAZDZD",
"after": "MjQZD"
}
}
}
Eliminar una plantilla
Eliminar una plantilla por nombre
Path:
DELETE /message_templates/VERSION/{did}?name=test_name
Response
Status Code 200
{
"success": true
}
Eliminar una plantilla por ids y nombre
Path:
DELETE /message_templates/VERSION/{did}?hsm_id=1723223958184989&name=test_name
Response
Status Code 200
{
"success": true
}
Habilitar analitica una plantilla
Debes confirmar los análisis de plantillas en la cuenta de WhatsApp Business para poder obtener los datos. Puedes confirmar los análisis de plantillas con el Administrador de WhatsApp o la API. Para confirmar los análisis con la API, envía la siguiente solicitud:
Path:
POST /message_templates/VERSION/{did}/enable_analytics
Una vez confirmados, meta comienza a capturar los análisis de plantillas de la cuenta de WhatsApp Business. Tras su confirmación, los análisis de plantillas no se pueden desactivar.
Si la operación se realiza correctamente, la API responderá con el identificador de tu cuenta de WhatsApp Business. Por ejemplo:
Response
Status Code 200
{
"id": 102290129340398
}
Deshabilitar el análisis de clics en botones
Puede desactivar button clic tracking en una plantilla individual configurando su campo cta_url_link_tracking_opted_out en true. Una vez deshabilitada, la API ya no devolverá la propiedad en la que se hizo clic en el análisis de la plantilla ni mostrará la interacción/clics del botón en el Administrador de WhatsApp al ver las estadísticas de la plantilla.
Path:
POST /message_templates/VERSION/{did}/{message_template_id}?cta_url_link_tracking_opted_out=true&category=marketing
- Request
Descripción de query parameters
| Fields | Type | Comentario |
|---|---|---|
| cta_url_link_tracking_opted_out | boolean | Indica si el seguimiento de clics en el botón de plantilla está deshabilitado. Configúrelo en verdadero para deshabilitar el button click tracking en los botones en la plantilla, o en falso para habilitarlo. Este valor se establece en falso al crear la plantilla. |
| category | timestamp | Si configura la categoría de la plantilla en un valor diferente a su categoría actual, el estado de la plantilla se establecerá en PENDIENTE y la plantilla tendrá que someterse a una revisión de la plantilla para ser aprobada. |
Response
Status Code 200
{
"id": 102290129340398
}
Recuperar namespace de una plantilla
El espacio de nombres de la plantilla de mensaje se necesita para enviar mensajes con las plantillas de mensajes.
Para obtener el espacio de nombres de una plantilla, envía una solicitud GET como la siguiente:
Path:
GET /message_templates/VERSION/{did}/message_template_namespace
Una vez confirmados, meta comienza a capturar los análisis de plantillas de la cuenta de WhatsApp Business. Tras su confirmación, los análisis de plantillas no se pueden desactivar.
Si la operación se realiza correctamente, la API responderá con el identificador de tu cuenta de WhatsApp Business. Por ejemplo:
Response
Status Code 200
{
"id": "1972385232742141",
"message_template_namespace": "12abcdefghijk_34lmnop"
}
Migración de una plantilla
Path:
POST /message_templates/VERSION/{did}/migrate_message_templates?source_waba_id=102290129340398&page_number=0
- Request
Descripción de query parameters
| Fields | Type | Comentario |
|---|---|---|
| source_waba_id | String | Source WhatsApp Business Account ID. |
| page_number | timestamp | Indica la cantidad de plantillas para migrar como conjuntos de 2500. Indexado a cero. Por ejemplo, para migrar 5000 plantillas, envíe una solicitud con este valor establecido en 0 y otra solicitud con este valor establecido en 1, en paralelo. |
Response
Status Code 200
{
"migrated_templates": [
"1473688840035974",
"6162904357082268",
"6147830171896170"
],
"failed_templates": {
"1019496902803242": "Incorrect category",
"259672276895259": "Formatting error - dangling parameter",
"572279198452421": "Incorrect category"
}
}
Comparación de plantillas
Path:
GET /message_templates/VERSION/{did}/{message_template_id}/compare?template_ids=[776614587250474]&start=1709742142450&end=1709749918450
- Request
Descripción de query parameters
| Fields | Type | Comentario |
|---|---|---|
| template_ids | String | El ID de la plantilla de mensaje de WhatsApp con el que puedes comparar. |
| start | timestamp | UNIX timestamp indicando el inicio del timeframe. Ver Timeframes. |
| end | timestamp | UNIX timestamp indicando el final del timeframe. Ver Timeframes. |
Response
Status Code 200
{
"data": [
{
"metric": "BLOCK_RATE",
"type": "RELATIVE",
"order_by_relative_metric": [
"1533406637136032",
"5289179717853347"
]
},
{
"metric": "MESSAGE_SENDS",
"type": "NUMBER_VALUES",
"number_values": [
{
"key": "5289179717853347",
"value": 1273
},
{
"key": "1533406637136032",
"value": 1042
}
]
},
{
"metric": "TOP_BLOCK_REASON",
"type": "STRING_VALUES",
"string_values": [
{
"key": "5289179717853347",
"value": "UNKNOWN_BLOCK_REASON"
},
{
"key": "1533406637136032",
"value": "UNKNOWN_BLOCK_REASON"
}
]
}
]
}
Quitar la pausa de plantillas
Path:
POST /message_templates/VERSION/{did}/{message_template_id}/unpause
Response
Status Code 200
{
"success": true
}