Índice:
Introducción
El tipo de mensaje carrusel, actualmente solo existe como plantilla en el canal de Whatsapp. El objetivo de este documento es describir el Carrusel Plantilla y cómo usarlos. Esta plantilla permite enviar un único mensaje de texto acompañado por un conjunto de hasta 10 Carrusel Cards en una visualización horizontal con scroll.
Observación: Por tratarse de un mensaje del tipo plantilla, el envío del carrusel se cobra conforme una notificación activa, incluso si se envía como contenido dinámico en el flujo de los mensajes.
Creación del Carrusel Plantilla
Para crear el Carrusel Plantilla será necesario realizar los siguientes pasos, a través de los comandos listados a continuación y para ejecutar estos comandos necesitarás la url de comando de tu organización y la API-Key. Haz clic aquí para saber cómo encontrarlo.
Para ilustrar se creará la siguiente plantilla:
1. Añadir medios que serán utilizados en la plantilla
Los medios que se usarán en el header de los cards deben ser enviados previamente para obtener el valor del handler que será entonces añadido en la creación de la plantilla. La plataforma de Blip se encargará de llamar a la API de Meta y realizar el upload del medio. Sigue el detalle del comando:
ORGANIZATION_ID: es el identificador de la organización.
YOUR_TOKEN: es la clave de autorización de tu bot.
|
POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1 Content-Type: application/json Authorization: Key {YOUR_TOKEN} { "id": "{{$guid}}", "method": "set", "to": "postmaster@wa.gw.msging.net", "type": "application/vnd.lime.media-link+json", "uri": "/message-templates-attachment", "resource": { "uri": "https://www.blip.ai/wp-content/uploads/2023/06/Blip_General_Thumb.png" } } |
La respuesta de esta llamada contendrá información de los medios, la más importante de ellas es el campo fileHandle, que se utilizará en la creación del template.
|
{ "type": "application/json", "resource": { "uploadSessionId": "upload:MTphdHR………………", "fileHandle": "4::aW1hZ2UvcG5n:ARb4uJ6m………………..", "fileSize": "43122", "fileSizeUploaded": "43122" }, "method": “set”, "status": “success”, "id": “{{$guid}}”, "from": “postmaster@wa.gw.msging.net/#msging-gateway-whatsapp”,, "to": “botid@msging.net/#msging-server”, "metadata": { "traceparent": "00-111ss26458-4f584a16e5tr4dd5d55d5d", "#command.uri": "lime://botid@msging.net/message-templates-attachment" } } |
2. Crear Carrusel Plantilla
Para crear la plantilla del carrusel se debe enviar el siguiente comando:
ORGANIZATION_ID: es el identificador de la organización.
YOUR_TOKEN: es la clave de autorización de tu bot.
|
POST https://{ORGANIZATION_ID}.http.msging.net/commands HTTP/1.1 Content-Type: application/json Authorization: Key {YOUR_TOKEN} { "id": "{{$guid}}", "method": "set", "to": "postmaster@wa.gw.msging.net", "type": "application/json", "uri": "/message-templates", "resource": { "name": "<TEMPLATE_NAME>", "language": "<TEMPLATE_LANGUAGE>", "category": "<TEMPLATE_CATEGORY>", "components": [ /* Message bubble, required */ { "type": "BODY", "text": "<BUBBLE_TEXT>", "example": { "body_text": [ [ "<BUBBLE_TEXT_VAR_EXAMPLE_1>", "<BUBBLE_TEXT_VAR_EXAMPLE_2>" ] ] } }, /* Carousel cards*/ { "type": "CAROUSEL", "cards": [ /* Begin first carousel card */ { "components": [ { "type": "HEADER", "format": "<CARD_HEADER_FORMAT>", "example": { "header_handle": [ "<CARD_HEADER_HANDLE>" ] } }, { "type": "BODY", "text": "<CARD_BODY_TEXT>", "example": { "body_text": [ [ "<CARD_BODY_TEXT_VAR_EXAMPLE_1>", "<CARD_BODY_TEXT_VAR_EXAMPLE_2>" ] ] } }, /* At least one button required */ { "type": "BUTTONS", "buttons": [ { "type": "QUICK_REPLY", "text": "<QUICK_REPLY_BUTTON_TEXT>" }, { "type": "URL", "text": "<URL_BUTTON_TEXT>", "url": "<URL_BUTTON_URL>", "example": [ "<URL_BUTTON_VAR_EXAMPLE>" ] } ] } ] }, /* End first carousel card */ ] } ] } } |
Template
- TEMPLATE_NAME: nombre del template del carrusel.
- TEMPLATE_LANGUAGE: Idioma del template.
- TEMPLATE_CATEGORY: Categoría del template.
Message bubble
- BUBBLE_TEXT: Texto. Máximo 1024 caracteres.
- BUBBLE_TEXT_VAR_EXAMPLE: Valores en texto, referente a las variables que son sustituidas en el BUBBLE_TEXT, en caso de que haya. El número de variables debe corresponder al número incluido en BUBBLE_TEXT. Ejemplo:
|
{ "type": "BODY", "text": "Use the coupon {{1}} to get discount in {{2}}", "example": { "body_text": [ [ "NEWCLIENT", "SHOES" ] ] } } |
Carousel cards
donde, cada cards se define cómo será presentado.
- CARD_HEADER_FORMAT: formato de la media. Debe ser imagen o video. (image/video)
- CARD_HEADER_HANDLE: valor fileHandle, retornado por Meta en la solicitud de la etapa anterior.
- CARD_BODY_TEXT: Texto del card, máximo 160 caracteres.
- CARD_BODY_TEXT_VAR_EXAMPLE: Valores en texto, referente a las variables que se sustituyen en CARD_BODY_TEXT, si las hay. El número de variables debe corresponder al número incluido en CARD_BODY_TEXT.
Botones del card. Al menos uno es obligatorio.
- QUICK_REPLY_BUTTON_TEXT: texto del botón de quick reply. Máximo 25 caracteres.
- URL_BUTTON_TEXT: texto, etiqueta de la url. Soporta solo 1 variable. Máximo de 25 caracteres.
- URL_BUTTON_URL: url con parámetros. Soporta solo 1 variable. Máximo 2000 caracteres.
- URL_BUTTON_VAR_EXAMPLE: url con parámetro de ejemplo, referente a las variables que se sustituyen en URL_BUTTON_URL, si las hay.
La respuesta de esta llamada contendrá información como el ID del carrousel template creado y el status de la solicitud, si success, el template se creó con éxito.
|
{ "type": "application/json", "resource": { "id": "1854……" }, "method": "set", "status": "success", "id": "{{$guid}}", "from": “postmaster@wa.gw.msging.net/#msging-gateway-whatsapp”,, "to": “botid@msging.net/#msging-server”, "metadata": { "traceparent": "00-9cee92d86c62fcc09189d6c61186d5b6-b0fcf66ee873c1b3-01", "#command.uri": "lime://botid@msging.net/message-templates" } } |
Todavía no es posible visualizar tu nuevo template en Blip, pero podrás ver tu template creado en la gestión de Wabas
Enviar Template de Carrusel
Después de que el template de carrusel haya sido creado, es posible enviar el mensaje que contiene el carrusel. Hay dos formas de enviarlo: como una notificación activa y en el flujo del builder a través de contenido dinámico. Recordando que, independientemente de la forma en que se envíe, al ser un template, será cobrado como notificación activa.
Notificación activa
Para el envío de notificaciones activas, antes debe realizarse el comando de verificación del número, conforme a la documentación.
ORGANIZATION_ID: es el identificador de la organización.
YOUR_TOKEN: es la clave de autorización de tu bot.
USER_PHONE_NUMBER: número de teléfono del usuario que recibirá el mensaje del template de carrusel , según se consulta en la documentación.
CAROUSEL_TEMPLATE_NAME: nombre del template de carrusel que fue creado
|
POST https://{ORGANIZATION_ID}.http.msging.net/messages HTTP/1.1 Content-Type: application/json Authorization: Key {YOUR_TOKEN} { "id": "{{$guid}}", "to": "{USER_PHONE_NUMBER}@wa.gw.msging.net", "type": "application/json", "content": { "type": "template", "template": { "name": "<TEMPLATE_NAME>", "language": { "code": "<TEMPLATE_LANGUAGE>" }, "components": [ /* Message bubble; can omit if template message bubble has no variables */ { "type": "BODY", "parameters": [ { "type": "TEXT", "text": "20OFF" }, { "type": "TEXT", "text": "20%" } ] }, /* Carousel cards */ { "type": "CAROUSEL", "cards": [ { "card_index": 0, "components": [ { "type": "HEADER", "parameters": [ { /* Required if template uses image header, otherwise omit */ "type": "IMAGE", "image": { "link": "https://www.blip.ai/wp-content/uploads/2023/06/Blip_General_Thumb.png" } /* Required if template uses video header, otherwise omit */ "type": "VIDEO", "video": { "id": "12345678978569" } } ] }, /* Can be omitted if card body text in template has no variables */ { "type": "BODY", "parameters": [ { "type": "TEXT", "text": "10OFF" }, { "type": "TEXT", "text": "10%" } ] }, { "type": "BUTTON", "sub_type": "QUICK_REPLY", "index": "0", "parameters": [ { "type": "PAYLOAD", "payload": "59NqSd" } ] }, { "type": "BUTTON", "sub_type": "URL", "index": "1", "parameters": [ { "type": "PAYLOAD", "payload": "last_chance_2023" } ] } ] }, { "card_index": 1, "components": [ { "type": "HEADER", "parameters": [ { "type": "IMAGE", "image": { "id": "24230790383178626" } } ] }, { "type": "BODY", "parameters": [ { "type": "TEXT", "text": "30OFF" }, { "type": "TEXT", "text": "30%" } ] }, { "type": "BUTTON", "sub_type": "QUICK_REPLY", "index": "0", "parameters": [ { "type": "PAYLOAD", "payload": "7C4xhY" } ] }, { "type": "BUTTON", "sub_type": "URL", "index": "1", "parameters": [ { "type": "PAYLOAD", "payload": "summer_blues_2023" } ] } ] } ] } ] } } } |
Como contenido dinámico
Para enviar el carrusel como contenido dinámico, se debe agregar en el flujo el componente de tipo contenido dinámico, conforme a la documentación, donde:
Type: application/json
Content: json, el mismo valor que se asignó en el campo “content” de la solicitud de envío de mensaje para notificación activa. Ejemplo:
Nota: Recordando que incluso estando como contenido dinámico en el flujo de conversaciones, se cobrará como una notificación activa, por tratarse de un template.
Para más información, visite la discusión sobre el tema en nuestra comunidad o los vídeos en nuestro canal.😃