> For the complete documentation index, see [llms.txt](https://help.1msg.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.1msg.io/docs/es/api-documentation/api-crear-y-enviar-plantilla.md).
# API Crear y enviar plantilla
## Crear plantilla
La creación de plantillas se describe en la [documentación de la AP](https://docs.1msg.io/)I en el método [`/addTemplate`](https://docs.1msg.io/#tag/Templates/operation/addTemplate).
También puede crear una plantilla desde la sección "Dev Toolkit" → "Test Requests" en su cuenta personal.
**Parte general de la solicitud:**
| Campo | Descripción |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **name** | Nombre de la plantilla. Solo puede contener letras minúsculas, dígitos y guiones bajos. |
| **allow\_category\_change** | Casilla "Permitir cambio de categoría". En lugar de rechazar la plantilla, cambiaremos automáticamente su tipo de categoría. |
| **category** | Tipo de plantilla: `MARKETING`, `UTILITY` o `AUTHENTICATION` |
| **language** | Idioma de la plantilla. El idioma seleccionado debe coincidir con el texto de la plantilla. De lo contrario, Meta puede rechazar la plantilla. |
| **components** | Matriz de componentes de la plantilla |
**Ejemplo:**
```json
{
"token": "{{token}}",
"name": "test_marketing_2024",
"allow_category_change": false,
"category": "MARKETING",
"language": "ru",
"components": [
// objetos del cuerpo de la plantilla
]
}
```
A continuación se describe la estructura de cada categoría de plantilla.
***
### Plantillas de Marketing y Servicios
#### HEADER
Los encabezados son componentes opcionales que aparecen en la parte superior del mensaje de plantilla.
Admiten `TEXT` o medios (`IMAGE`, `VIDEO` o `DOCUMENT`). Las plantillas están limitadas a un solo componente de encabezado.
| Tipo | Descripción |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TEXT** | Establezca `"format": "TEXT"` para definir el encabezado como texto. Reglas: máx. 60 caracteres; solo una variable; si hay variable, indique un ejemplo en `header_text`. |
| **IMAGE** | Establezca `"format": "IMAGE"` para una imagen. Incluya el objeto `"example"` con el enlace en `"header_handle"`. |
| **VIDEO** | Establezca `"format": "VIDEO"` para un vídeo. Incluya el objeto `"example"` con el enlace en `"header_handle"`. |
| **DOCUMENT** | Establezca `"format": "DOCUMENT"` para un documento. Incluya el objeto `"example"` con el enlace en `"header_handle"`. |
**Ejemplo — encabezado de texto sin variable:**
```json
{
"type": "HEADER",
"format": "TEXT",
"text": "Hello"
}
```
**Ejemplo — encabezado de texto con variable:**
```json
{
"type": "HEADER",
"format": "TEXT",
"text": "Our {{1}} is on!",
"example": {
"header_text": ["Summer Sale"]
}
}
```
**Ejemplo — encabezado IMAGE:**
```json
{
"type": "HEADER",
"format": "IMAGE",
"example": {
"header_handle": ["https://img-example-link.com/delicious-orange-23.jpg"]
}
}
```
**Ejemplo — encabezado VIDEO:**
```json
{
"type": "HEADER",
"format": "VIDEO",
"example": {
"header_handle": ["https://video-example-link.com/banner.mp4"]
}
}
```
**Ejemplo — encabezado DOCUMENT:**
```json
{
"type": "HEADER",
"format": "DOCUMENT",
"example": {
"header_handle": ["https://doc-example-link.com/reyshi.pdf"]
}
}
```
***
#### BODY
El cuerpo es solo texto y **es obligatorio** en todas las plantillas. La plantilla puede tener un solo componente BODY.
**Reglas del BODY:**
* Obligatorio.
* `text`: máx. 1024 caracteres.
* Si hay variables en `text`, indique ejemplos en `"example"` → `"body_text"`. El número de elementos debe coincidir con el de variables.
* Meta no limita el número de variables.
* El texto no puede ser solo una variable; Meta no acepta `"text": "{{1}}"`.
**Ejemplo:**
```json
{
"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%"]
]
}
}
```
*(Omita `example` si no hay variables en `text`.)*
***
#### FOOTER
El pie es un texto opcional que aparece justo después del cuerpo. Máx. un componente FOOTER.
**Ejemplo:**
```json
{
"type": "FOOTER",
"text": "text for footer"
}
```
***
#### BUTTONS
Los botones son componentes opcionales que realizan acciones al pulsar. Las plantillas pueden tener hasta 10 botones en total, con límites por tipo y por combinación.
**Tipos de botones:**
* **Quick Reply** — Botón de texto que envía al instante ese texto en el chat. Cualquier texto.
* **URL** — Abre la URL indicada en el navegador.
* **Phone Number** — Realiza una llamada al número indicado.
* **Catalog** (solo Marketing) — Al pulsar "View catalog" se abre el catálogo de productos en WhatsApp.
Los botones **URL** y **Phone** no envían respuesta en el chat como Quick Reply.
**Límites:**
* Quick Reply: hasta 10
* URL: hasta 2
* Phone Number: 1
* En la plantilla Catalog solo se puede usar el botón Catalog.
* Máximo 10 botones en total.
**Combinaciones válidas / no válidas:**
| Válidas | No válidas |
| ------------------------------------------------- | ----------------------------- |
| Quick Reply, Quick Reply, Quick Reply | Quick Reply, URL, Quick Reply |
| Quick Reply, Quick Reply, Quick Reply, URL, Phone | URL, Quick Reply, URL |
| URL, Phone, Quick Reply, Quick Reply | |
Hay que respetar el orden y la cantidad de cada tipo.
**QUICK\_REPLY:**
```json
{
"type": "QUICK_REPLY",
"text": "Yes"
}
```
Máx. 25 caracteres en `text`.
**URL:**
```json
{
"type": "URL",
"text": "Shop Now",
"url": "https://www.luckyshrub.com/shop?promo={{1}}",
"example": ["summer2023"]
}
```
`url`: máx. 2000 caracteres. La API no acepta caracteres cirílicos en las URL. Si hay variable, indique `example`.
**PHONE\_NUMBER:**
```json
{
"type": "PHONE_NUMBER",
"text": "my number",
"phone_number": "77777777777"
}
```
`phone_number` y `text` son obligatorios. Máx. 25 caracteres en `text`, 20 en `phone_number`.
**CATALOG:**
```json
{
"type": "CATALOG",
"text": "View catalog"
}
```
Solo un botón en la plantilla Catalog. En `text` debe figurar "View catalog"; se traducirá según el idioma de la plantilla.
***
#### Ejemplo completo: plantilla de Marketing
Plantilla con: encabezado de texto con variable, cuerpo con variables, pie de texto y dos botones Quick Reply.
```json
{
"token": "{{token}}",
"name": "test_marketing_2024",
"allow_category_change": false,
"category": "MARKETING",
"language": "ru",
"components": [
{
"type": "HEADER",
"format": "TEXT",
"text": "Our {{1}} is on!",
"example": { "header_text": ["Summer Sale"] }
},
{
"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" }
]
}
]
}
```
***
### Plantilla de autenticación
Las plantillas de autenticación incluyen opciones como aviso de seguridad y advertencia de caducidad. Además, deben tener un botón de contraseña de un solo uso (copiar código o one-tap).
El valor `components` debe ser un array de objetos. La plantilla de autenticación debe tener:
* un **body**
* un **footer** (opcional)
* un **botón OTP**
**BODY:**
* Texto fijo: *\ is your verification code.* No rellene la propiedad `"text"`.
* Aviso de seguridad opcional: "For your security, do not share this code". Para añadirlo: `"add_security_recommendation": true`; `false` para omitirlo.
* El idioma mostrado depende del idioma de la plantilla.
```json
{
"type": "BODY",
"add_security_recommendation": true
}
```
**FOOTER:**
* Opcional.
* Advertencia de caducidad: "This code expires in \ minutes". Use `"code_expiration_minutes"` (entero de 1 a 90). Si se omite, no se muestra.
```json
{
"type": "FOOTER",
"code_expiration_minutes": 5
}
```
**BUTTONS:**
* Debe incluir botón de copiar código o one-tap. Tipo: `"OTP"`.
* `"otp_type"`: `"COPY_CODE"` o `"ONE_TAP"`.
* Solo un botón.
* `"text"`: texto del botón. **Incluso con ONE\_TAP debe indicarse**; si Meta no valida el one-tap, se mostrará el botón de copiar con este texto. Máx. 25 caracteres.
Para `ONE_TAP` también: `autofill_text`, `package_name`, `signature_hash` (consulte la documentación de Meta).
**Ejemplo botón copiar código:**
```json
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "COPY_CODE",
"text": "Copy Code"
}
]
}
```
**Ejemplo botón one-tap:**
```json
{
"type": "BUTTONS",
"buttons": [
{
"type": "OTP",
"otp_type": "ONE_TAP",
"text": "Copy Code",
"autofill_text": "Autofill",
"package_name": "com.example.myapplication",
"signature_hash": "K8a%2FAINcGX7"
}
]
}
```
**Ejemplo completo de plantilla de autenticación:**
```json
{
"name": "auth_2024",
"allow_category_change": false,
"category": "AUTHENTICATION",
"language": "ru",
"components": [
{ "type": "BODY", "add_security_recommendation": true },
{ "type": "FOOTER", "code_expiration_minutes": 5 },
{
"type": "BUTTONS",
"buttons": [
{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }
]
}
]
}
```
***
## Enviar plantilla por API
El envío se describe en el método [`/sendTemplate`.](https://docs.1msg.io/#tag/Templates/operation/sendTemplate)
También puede enviar desde "Dev Toolkit" → "Test Requests".
Necesita **namespace**, **name** y **language** de la plantilla. Obténgalos con el método "Get list of templates" (`/templates`).
**Propiedades relevantes en `/sendTemplate`:**
| Propiedad | Descripción |
| ------------------------ | ------------------------------------------------------------------------------------------------- |
| **template** | Nombre de la plantilla |
| **language** | `policy`: "deterministic"; `code`: código de `/templates` |
| **Objeto type "body"** | Mensaje de texto. Omita si el cuerpo no tiene variables. |
| **Objeto type "button"** | En el cuerpo solo se envían botones con `sub_type` "url" o "catalog". Los demás se pueden omitir. |
***
### Enviar plantillas Marketing o Utility
Envíe solo los objetos definidos en la plantilla. Omita:
* `header` si no existe en la plantilla
* `header` si es de tipo Text y no tiene variable
* `body` si no tiene variables
* Botones Quick Reply y Phone — siempre omitir
* Botón URL si no tiene variable
En encabezados `IMAGE`, `VIDEO` o `DOCUMENT` envíe siempre la URL completa. La URL debe incluir el formato del archivo.
**Ejemplo: documento con botón URL**
* Encabezado tipo document
* Cuerpo con 2 variables
* Dos botones URL; el segundo tiene variable. Si un botón URL no tiene variable, omítalo. El índice del segundo botón es 1.
```json
{
"namespace": "{{namespace}}",
"template": "delivery_tracking",
"language": { "policy": "deterministic", "code": "ru" },
"params": [
{
"type": "header",
"parameters": [
{
"type": "document",
"document": { "link": "https://test.com/reyshi.pdf" }
}
]
},
{
"type": "body",
"parameters": [
{ "type": "text", "text": "Andrey" },
{ "type": "text", "text": "№003478" }
]
},
{
"type": "button",
"sub_type": "url",
"index": 1,
"parameters": [{ "type": "text", "text": "/reyshi" }]
}
],
"phone": "{{phone}}"
}
```
**Ejemplo: encabezado de texto con todos los tipos de botones**
* Encabezado Text con una variable
* Cuerpo sin variables → omitido en la solicitud
* 4 botones: Quick Reply, Phone, URL con variable, URL sin variable
```json
{
"namespace": "{{namespace}}",
"template": "utility_all_buttons_2024_05",
"language": { "policy": "deterministic", "code": "en" },
"params": [
{
"type": "header",
"parameters": [{ "type": "text", "text": "Anna" }]
},
{
"type": "button",
"sub_type": "url",
"index": 2,
"parameters": [{ "type": "text", "text": "inbox" }]
}
],
"phone": "{{phone}}"
}
```
***
### Enviar plantilla de autenticación
**Ejemplo con botón copiar código:**
```json
{
"namespace": "{{namespace}}",
"template": "auth_2",
"language": { "policy": "deterministic", "code": "ru" },
"params": [
{
"type": "body",
"parameters": [{ "type": "text", "text": "05425" }]
},
{
"type": "button",
"sub_type": "url",
"index": 0,
"parameters": [{ "type": "text", "text": "05425" }]
}
],
"phone": "+556123122026"
}
```