Pular para o conteúdo principal

Carrossel Templates

  • Atualizado

Índice:

  1. Introdução
  2. Criação do Carrossel Template
  3. Enviar Carrossel Template

Introdução

O tipo de mensagem carrossel, atualmente só existe como template no canal do Whatsapp. O objetivo deste documento é descrever o Carrossel Template e como usá-los. Esse template permite você enviar uma única mensagem de texto acompanhada por um conjunto de até 10 Carrossel Cards em uma visualização horizontal com scroll.

Observação: Por se tratar de uma mensagem do tipo template, o envio do carrossel é cobrado conforme uma notificação ativa, mesmo se for enviado como conteúdo dinâmico no fluxo das mensagens.

 

Criação do Carrossel Template

Para criar o Carrossel Template será necessário realizar os passos a seguir, através  dos comandos listados abaixo e para executar esses comandos você precisará da url de comando da sua organização e da API-Key. Clique aqui para saber como encontrar.

Para ilustrar será criado o seguinte template:

1. Adicionar mídias que serão utilizadas no template

As mídias que serão usadas no header dos cards devem ser enviadas previamente  para obter o valor do handler que será então adicionado na criação do template. A plataforma do Blip se encarregará de chamar a API da Meta e realizar o upload da mídia. Segue o detalhamento do comando:

ORGANIZATION_ID: é o identificador da organização.

YOUR_TOKEN: é a chave de autorização do seu 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"
    }
}

A resposta desta chamada conterá informações da mídia, a mais importante delas é o campo fileHandle, que será utilizado na criação do 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. Criar Carrossel Template

Para criar o template do carrossel deve ser enviado o seguinte comando:

ORGANIZATION_ID: é o identificador da organização.

YOUR_TOKEN: é a chave de autorização do seu 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: nome do carrossel template.
  • TEMPLATE_LANGUAGE: Idioma do template.
  • TEMPLATE_CATEGORY: Categoria do template.

Message bubble

  • BUBBLE_TEXT:  Texto. Máximo 1024 caracteres.
  • BUBBLE_TEXT_VAR_EXAMPLE: Valores em texto, referente às variáveis que são substituídas no BUBBLE_TEXT, caso tenha. O número de variáveis deve corresponder ao número ​​incluídas em BUBBLE_TEXT. Exemplo:

 

{
    "type": "BODY",
    "text": "Use the coupon {{1}} to get discount in {{2}}",
    "example": {
                   "body_text": [
                                    [
                                        "NEWCLIENT",
                                        "SHOES"
                                    ]
                              ]
               }
}

 

Carousel cards

onde, cada cards é definido como será apresentado.

  • CARD_HEADER_FORMAT: formato da mídia. Deve ser imagem ou vídeo. (image/video)
  • CARD_HEADER_HANDLE: valor fileHandle, retornado pela Meta na requisição da etapa anterior. 
  • CARD_BODY_TEXT: Texto do card, máximo 160 caracteres.
  • CARD_BODY_TEXT_VAR_EXAMPLE: Valores em texto, referente às variáveis que são substituídas no CARD_BODY_TEXT, caso tenha. O número de variáveis deve corresponder ao número ​​incluídos em CARD_BODY_TEXT.

Botões do card. Pelo menos um é obrigatório

  • QUICK_REPLY_BUTTON_TEXT: texto do botão de quick reply. Máximo 25 caracteres.
  • URL_BUTTON_TEXT: texto, label da url. Suporta apenas 1 variável. Máximo de 25 caracteres. 
  • URL_BUTTON_URL: url com parâmetros. Suporta apenas 1 variável. Máximo 2000 caracteres.
  • URL_BUTTON_VAR_EXAMPLE: url com parâmetro preenchido de exemplo, referente às variáveis que são substituídas no URL_BUTTON_URL, caso tenha.

A resposta desta chamada conterá informações como o ID do carrossel template criado e o status da requisição, se success, o template foi criado com sucesso.

{
    "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"
    }
}

Ainda não é possível visualizar o seu novo template no Blip, mas você poderá ver seu template criado no gerenciamento de Wabas

Enviar Carrossel Template

Após o template de carrossel ter sido criado é possível enviar a mensagem contendo o carrossel. Há duas formas de enviá-lo: como uma notificação ativa e no fluxo do builder através de conteúdo dinâmico. Lembrando que independente da forma que for enviado, por ser um template irá ser cobrado como notificação ativa.

 

Notificação ativa

Para envio de notificações ativas, antes deve ser realizado o comando de verificação do número, conforme documentação.

ORGANIZATION_ID: é o identificador da organização.

YOUR_TOKEN: é a chave de autorização do seu bot.

USER_PHONE_NUMBER: número de telefone do usuário que receberá a mensagem do carrossel template, conforme consultado na documentação.

CAROUSEL_TEMPLATE_NAME: nome do carrossel template que foi criado

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 conteúdo dinâmico

Para envio do carrossel como conteúdo dinâmico, deve ser adicionado no fluxo o componente do tipo conteúdo dinâmico, conforme a documentação, onde:

Type: application/json

Content: json, o mesmo valor que foi atribuído no campo “content” da requisição de envio de mensagem para notificação ativa. Exemplo: 

Observação: Lembrando que mesmo estando como conteúdo dinâmico no fluxo de conversas, será cobrado como uma notificação ativa, por se tratar de um template.

 

Para mais informações, acesse a discussão sobre o assunto em nossa comunidade ou os vídeos no nosso canal.😃

Artigos relacionados