# Plantilla Carrusel

## Descripción general <a href="#descripci-c3-b3n-general" id="descripci-c3-b3n-general"></a>

La plantilla Carrusel admite dos formatos de envío:

### **Carrusel con tarjetas de producto personalizadas** <a href="#carrusel-con-tarjetas-de-producto-personalizadas" id="carrusel-con-tarjetas-de-producto-personalizadas"></a>

Máxima flexibilidad para su caso de uso. Ideal cuando necesita personalización y libertad de marketing.

* Usted define el carrusel: número de tarjetas, textos, variables y botones
* Al enviar, proporciona imágenes y valores de las variables
* Útil para promociones a medida, ofertas especiales y contenido por segmento
* Control total del aspecto y del texto de cada tarjeta

<figure><img src="https://2579420816-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhUATFb1X4MrZmATrI8Pi%2Fuploads%2Fhu0alLV6YVXe1xw7ZbHV%2Fimage.png?alt=media&#x26;token=257883c0-1a40-4829-b291-d88584752d4c" alt=""><figcaption></figcaption></figure>

***

### **Carrusel con tarjetas de producto de su Catálogo de WhatsApp** <a href="#carrusel-con-tarjetas-de-producto-de-su-cat-c3-a1logo-de-whatsapp" id="carrusel-con-tarjetas-de-producto-de-su-cat-c3-a1logo-de-whatsapp"></a>

Rápido, automático y con menos errores. Ideal para envíos masivos y ventas recurrentes.

* Las tarjetas se obtienen directamente de su Catálogo de WhatsApp
* No hace falta rellenar descripciones, subir imágenes ni configurar botones a mano
* Los datos están siempre actualizados: precio, nombre, descripción, imágenes
* Menos trabajo manual y menos errores al enviar

<figure><img src="https://2579420816-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhUATFb1X4MrZmATrI8Pi%2Fuploads%2F1Nlgu98PabsuDyIRCvEt%2Fimage.png?alt=media&#x26;token=95effe44-3f8a-4146-a2e3-00a5393125b7" alt=""><figcaption></figcaption></figure>

***

### **Descripción** <a href="#descripci-c3-b3n" id="descripci-c3-b3n"></a>

Las plantillas Carrusel permiten enviar un único mensaje de texto (1) junto con un conjunto de hasta 10 tarjetas de carrusel (2) con desplazamiento horizontal.

Los usuarios pueden ver el carrusel tanto en móvil como en el cliente web de WhatsApp.

**Reglas básicas para crear la plantilla:**

1. Es obligatorio un mensaje de burbuja (1). Las burbujas son solo texto y admiten variables.
2. Las plantillas Carrusel admiten hasta 10 tarjetas.
3. El formato del encabezado multimedia y los tipos de botones deben ser los mismos en todas las tarjetas.
4. Cada tarjeta debe tener un encabezado multimedia obligatorio (imagen o vídeo) y texto en el cuerpo.
5. Cada tarjeta debe tener al menos 1 botón. La plantilla admite como máximo 2 botones por tarjeta.
6. Tipos de botón admitidos: Quick Reply, URL de sitio web (CTA) y Número de teléfono (CTA). Pueden ser del mismo tipo o mezcla de Quick Reply, teléfono o URL por tarjeta.

### **Formas de enviar el Carrusel** <a href="#formas-de-enviar-el-carrusel" id="formas-de-enviar-el-carrusel"></a>

El Carrusel se puede enviar de dos formas:

* [**Mediante plantilla**](#enviar-plantilla-carrusel) **(mensaje de plantilla)** — para enviar **fuera de la ventana de 24 horas**. Requiere crear y que Meta apruebe la plantilla de WhatsApp. El envío es **de pago**.
* [**Como mensaje de servicio** ](#enviar-carrusel-como-mensaje-de-servicio)— **dentro de la ventana de conversación de 24 horas**. No hace falta plantilla. El envío es **gratuito**.

***

## Crear la plantilla <a href="#crear-la-plantilla" id="crear-la-plantilla"></a>

La creación se describe en la API en el método[ `/addTemplate`.](https://docs.1msg.io/#tag/Templates/operation/addTemplate)

La diferencia respecto a una plantilla básica es añadir el tipo **CAROUSEL** en `components` y el array **cards**.

También puede crear desde "Dev Toolkit" → "Test requests". No olvide indicar ejemplos de variables si las usa en el cuerpo o en la URL de los botones; si no, Meta puede rechazar la plantilla.

***

#### Parámetros de referencia <a href="#par-c3-a1metros-de-referencia" id="par-c3-a1metros-de-referencia"></a>

| Parámetro                          | Tipo             | Descripción                                                                                                    | Ejemplo                                                                                                       |
| ---------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **BUBBLE\_TEXT**                   | String           | **Obligatorio.** Texto de la burbuja. Admite variables. Máx. 1024 caracteres.                                  | `Summer is here, and we've got the freshest produce around! Use code {{1}} to get {{2}} off your next order.` |
| **BUBBLE\_TEXT\_VAR\_EXAMPLE**     | Array de strings | **Obligatorio** si la burbuja tiene variables. Tantos ejemplos como variables.                                 | `"15OFF","15%"`                                                                                               |
| **CARD\_BODY\_TEXT**               | String           | **Obligatorio.** Texto del cuerpo de la tarjeta. Admite variables. Máx. 160 caracteres.                        | `Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce.`                              |
| **CARD\_BODY\_TEXT\_VAR\_EXAMPLE** | Array de strings | **Obligatorio** si el cuerpo de la tarjeta tiene variables.                                                    | `"15OFF","15%"`                                                                                               |
| **CARD\_HEADER\_FORMAT**           | Enum             | **Obligatorio.** Formato del encabezado: `IMAGE` o `VIDEO`.                                                    | `IMAGE`                                                                                                       |
| **CARD\_HEADER\_HANDLE**           | —                | **Obligatorio.** Ejemplo del medio enviado.                                                                    | —                                                                                                             |
| **QUICK\_REPLY\_BUTTON\_TEXT**     | String           | **Obligatorio** si usa botón Quick Reply. Etiqueta. Máx. 25 caracteres.                                        | `Send more like this #2`                                                                                      |
| **TEMPLATE\_CATEGORY**             | Enum             | **Obligatorio.** `MARKETING` o `UTILITY`.                                                                      | `MARKETING`                                                                                                   |
| **TEMPLATE\_LANGUAGE**             | Enum             | **Obligatorio.** Idioma y código de locale.                                                                    | `en`                                                                                                          |
| **TEMPLATE\_NAME**                 | String           | **Obligatorio.** Nombre de la plantilla. Máx. 512 caracteres.                                                  | `marketing_carousel_01_test`                                                                                  |
| **URL\_BUTTON\_TEXT**              | String           | **Obligatorio** si usa botón URL. Etiqueta. Máx. 25 caracteres.                                                | `Buy now`                                                                                                     |
| **URL\_BUTTON\_URL**               | String           | **Obligatorio** si usa botón URL. URL que se abre al pulsar. Admite 1 variable al final. Máx. 2000 caracteres. | `https://www.luckyshrub.com/shop?promo={{1}}`                                                                 |
| **URL\_BUTTON\_VAR\_EXAMPLE**      | String           | **Obligatorio** si la URL tiene variable. Ejemplo de URL.                                                      | `https://www.luckyshrub.com/shop?promo=summer_lemons_2023`                                                    |

***

#### Ejemplo: crear plantilla Carrusel (tarjetas personalizadas) <a href="#ejemplo-crear-plantilla-carrusel-tarjetas-personalizadas" id="ejemplo-crear-plantilla-carrusel-tarjetas-personalizadas"></a>

*Los enlaces son de prueba; use los correctos al copiar. Ejemplo tomado de 360Dialog.*

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json

{
  "name": "marketing_carousel_01_test",
  "allow_category_change": true,
  "category": "MARKETING",
  "language": "en",
  "components": [
    {
      "text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get {{2}} off your next order.",
      "type": "BODY",
      "example": { "body_text": [["15OFF", "15%"]] }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": { "header_handle": ["https://img.example.com/delicious-background-orange-slices_23-2148231462.jpg"] }
            },
            {
              "type": "BODY",
              "text": "Rare lemons for unique cocktails. Use code {{1}} to get {{2}} off all produce",
              "example": { "body_text": [["150FF", "10%"]] }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                { "type": "QUICK_REPLY", "text": "Send more like this #1" },
                { "type": "URL", "text": "Buy now", "url": "https://www.luckyshrub.com/shop?promo={{1}}", "example": ["summer_lemons_2023"] }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": { "header_handle": ["https://img.example.com/top-view-citric-fruit-slices-table_23-2148495686.jpg"] }
            },
            {
              "type": "BODY",
              "text": "Exotic fruit for unique cocktails! Use code {{1}} to get {{2}} off all exotic produce",
              "example": { "body_text": [["20OFFEXOTIC", "20%"]] }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                { "type": "QUICK_REPLY", "text": "Send more like this #2" },
                { "type": "URL", "text": "Buy now", "url": "https://www.luckyshrub.com/shop?promo={{1}}", "example": ["exotic_produce_2023"] }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

***

#### Ejemplo: crear plantilla Carrusel con productos del Catálogo de WhatsApp <a href="#ejemplo-crear-plantilla-carrusel-con-productos-del-cat-c3-a1logo-de-whatsapp" id="ejemplo-crear-plantilla-carrusel-con-productos-del-cat-c3-a1logo-de-whatsapp"></a>

*Ejemplos para pruebas; sustituya por datos reales. Los ID de producto se rellenan al enviar.*

```json
POST https://api.1msg.io/{{channel}}/addTemplate
Content-Type: application/json

{
  "name": "marketing_carousel_01_test",
  "allow_category_change": true,
  "category": "MARKETING",
  "language": "en",
  "components": [
    {
      "type": "BODY",
      "text": "Hi, {{1}}! Summer is here, and we have the freshest produce around!",
      "example": { "body_text": [["Anna"]] }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            { "type": "BUTTONS", "buttons": [{ "type": "SPM", "text": "View" }] }
          ]
        },
        {
          "components": [
            { "type": "HEADER", "format": "PRODUCT" },
            { "type": "BUTTONS", "buttons": [{ "type": "SPM", "text": "View" }] }
          ]
        }
      ]
    }
  ]
}
```

***

## Enviar un Carrusel <a href="#enviar-un-carrusel" id="enviar-un-carrusel"></a>

### Enviar plantilla Carrusel <a href="#enviar-plantilla-carrusel" id="enviar-plantilla-carrusel"></a>

El Carrusel en plantilla:

* Tiene su propio `type`: **CAROUSEL**
* El objeto CAROUSEL contiene un array **cards**. Solo se usa en este tipo de plantilla.
* Cada tarjeta tiene **card\_index** — orden en el carrusel. 0 = primera, 1 = segunda, etc.

**Ejemplo: enviar plantilla Carrusel (tarjetas personalizadas)**

Plantilla de 2 tarjetas. Cada una: botón Quick Reply y botón URL. Encabezado: imagen.

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json

{
  "token": "{{token}}",
  "namespace": "{{namespace}}",
  "template": "marceting_carousel_01_test",
  "language": { "policy": "deterministic", "code": "en" },
  "params": [
    {
      "type": "body",
      "parameters": [
        { "type": "text", "text": "21OFF" },
        { "type": "text", "text": "21" }
      ]
    },
    {
      "type": "carousel",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "image", "image": { "link": "https://img.freepik.com/free-photo/top-view-citric-fruit-slices-table_23-2148495686.jpg" } }
              ]
            },
            {
              "type": "button",
              "sub_type": "url",
              "index": 1,
              "parameters": [{ "type": "text", "text": "summer" }]
            },
            {
              "type": "body",
              "parameters": [
                { "type": "text", "text": "10F" },
                { "type": "text", "text": "10" }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "image", "image": { "link": "https://img.freepik.com/free-photo/delicious-background-orange-slices_23-2148231462.jpg" } }
              ]
            },
            {
              "type": "button",
              "sub_type": "url",
              "index": 1,
              "parameters": [{ "type": "text", "text": "winter" }]
            },
            {
              "type": "body",
              "parameters": [
                { "type": "text", "text": "30F" },
                { "type": "text", "text": "30" }
              ]
            }
          ]
        }
      ]
    }
  ],
  "phone": "+556123122026"
}
```

*Puede omitir `body` si el texto común no tiene variables. Puede omitir el `body` de la tarjeta si su texto no tiene variables.*

***

**Ejemplo: enviar plantilla Carrusel con productos del Catálogo de WhatsApp**

Plantilla de 2 tarjetas con productos del catálogo.

```json
POST https://api.1msg.io/{{channel}}/sendTemplate
Content-Type: application/json

{
  "namespace": "{{namespace}}",
  "template": "marketing_carousel_01_test",
  "language": { "policy": "deterministic", "code": "en" },
  "params": [
    {
      "type": "body",
      "parameters": [{ "type": "text", "text": "Anna" }]
    },
    {
      "type": "carousel",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "product", "product": { "product_retailer_id": "0001", "catalog_id": "{{catalog_id}}" } }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "product", "product": { "product_retailer_id": "0002", "catalog_id": "{{catalog_id}}" } }
              ]
            }
          ]
        }
      ]
    }
  ],
  "phone": "{{phone}}"
}
```

***

### Enviar Carrusel como mensaje de servicio <a href="#enviar-carrusel-como-mensaje-de-servicio" id="enviar-carrusel-como-mensaje-de-servicio"></a>

Para enviar el Carrusel **como mensaje de servicio** (sin plantilla Meta creada de antemano), use el método[ **`/sendCarousel`**.](https://docs.1msg.io/#tag/Messaging/operation/sendCarousel)

**No** hace falta crear una plantilla Meta antes.

La estructura es parecida al envío por plantilla, pero debe **indicar todos los elementos explícitamente**, porque el mensaje se envía **sin plantilla**.

***

**Ejemplo: enviar Carrusel vía /sendCarousel (tarjetas personalizadas)**

2 tarjetas. Cada una: 2 botones Quick Reply. Encabezado: imagen.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json

{
  "phone": "{{phone}}",
  "params": [
    {
      "type": "BODY",
      "parameters": [{ "type": "text", "text": "Text Body" }]
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "image", "image": { "link": "https://test-pick.ru/38eff70e116842949fd3019b226d31db.jpg" } }
              ]
            },
            {
              "type": "BODY",
              "parameters": [{ "type": "text", "text": "Description card 1" }]
            },
            {
              "type": "button",
              "sub_type": "quick_reply",
              "parameters": [
                { "text": "Button", "id": "Buttons1" },
                { "text": "Button 2", "id": "Buttons2" }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "image", "image": { "link": "https://test-pick.ru/38eff70e116842949fd3019b226d31db.jpg" } }
              ]
            },
            {
              "type": "body",
              "parameters": [{ "type": "text", "text": "Description card 2" }]
            },
            {
              "type": "button",
              "sub_type": "quick_reply",
              "parameters": [
                { "text": "Button", "id": "Button3" },
                { "text": "Button 2", "id": "Button4" }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```

***

**Ejemplo: enviar Carrusel vía /sendCarousel con productos del Catálogo de WhatsApp**

2 tarjetas de producto del Catálogo de WhatsApp.

```json
POST https://api.1msg.io/{{channel}}/sendCarousel
Content-Type: application/json

{
  "phone": "{{phone}}",
  "params": [
    {
      "type": "BODY",
      "parameters": [{ "type": "text", "text": "Text body" }]
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "card_index": 0,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "product", "product": { "product_retailer_id": "0001", "catalog_id": "{{catalog_id}}" } }
              ]
            }
          ]
        },
        {
          "card_index": 1,
          "components": [
            {
              "type": "header",
              "parameters": [
                { "type": "product", "product": { "product_retailer_id": "0002", "catalog_id": "{{catalog_id}}" } }
              ]
            }
          ]
        }
      ]
    }
  ]
}
```
