> ## Documentation Index > Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Enviar carrossel > Envie de 2 a 10 cartões com mídia, texto e botão, que o cliente rola para o lado. Envia um **carrossel de cartões** que o cliente rola para o lado. Cada cartão tem uma imagem ou um vídeo, um texto curto e um botão. É ideal para apresentar produtos, planos ou opções lado a lado. A [janela de 24 horas](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/introducao.md#janela-de-24-horas) precisa estar aberta. > [!NOTE] > > O destinatário pode ser informado pelo **número de telefone** (`to`) ou pelo **ID do usuário** (`recipient`). Se os dois forem enviados, vale o `to`; para enviar pelo ID do usuário, deixe o `to` em branco. Veja a diferença em [Destinatário](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/introducao.md#destinatário). ## Estrutura da mensagem A mensagem é do tipo `interactive`, com `interactive.type` igual a `carousel`: | Parte | Campo | Obrigatório | Limite | | - | - | - | - | | Texto | `interactive.body.text` | **Sim** | 1.024 caracteres. Aparece acima dos cartões. | | Cartões | `interactive.action.cards` | **Sim** | De **2 a 10** cartões. | O carrossel **não aceita cabeçalho nem rodapé** no nível da mensagem. A mídia e os botões ficam dentro de cada cartão. ## Cartões Cada item de `cards` é um cartão: | Campo | Obrigatório | Regra | | - | - | - | | `card_index` | **Sim** | Posição do cartão, começando em `0` e indo até `9`. | | `type` | **Sim** | Use `cta_url`, inclusive nos cartões com botões de resposta rápida. Sem esse campo, a Meta recusa o envio. | | `header` | **Sim** | Imagem ou vídeo do cartão, **somente por `link`**. | | `body.text` | Não | Texto do cartão, com até **160 caracteres** e no máximo 2 quebras de linha. | | `action` | **Sim** | Um botão com link **ou** botões de resposta rápida. | > [!WARNING] > > Todos os cartões precisam ser **iguais na estrutura**: o mesmo tipo de mídia (só imagens ou só vídeos) e o mesmo tipo e quantidade de botões. Se um cartão tem dois botões de resposta rápida, todos precisam ter dois. ### Mídia do cartão A mídia do cartão fica em `header`, com `type` igual a `image` ou `video`, e só é aceita por **`link`**: ```json theme={null} "header": { "type": "image", "image": { "link": "https://exemplo.com/produto-1.jpg" } } ``` > [!WARNING] > > O carrossel **não aceita o `id` de mídia** no cartão. Com `header.image.id`, a Meta recusa o envio com o erro `131009` ("The parameter interactive\['action']\['cards']\[].header.image.link is required"). Para gerar um link, envie o arquivo na aba **Mídias** do número, no [painel da Datafy](https://app.datafyapi.com.br). Os formatos e tamanhos aceitos são os mesmos de [Enviar imagem](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/enviar-imagem.md#formatos-aceitos) e [Enviar vídeo](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/enviar-video.md#formatos-aceitos). ### Botão com link Para um botão que abre uma URL, use `name` igual a `cta_url` e os `parameters`: ```json theme={null} { "card_index": 0, "type": "cta_url", "header": { "type": "image", "image": { "link": "https://exemplo.com/produto-1.jpg" } }, "body": { "text": "*Cesta de frutas*\nFrutas frescas selecionadas." }, "action": { "name": "cta_url", "parameters": { "display_text": "Comprar", "url": "https://exemplo.com/produto-1" } } } ``` `display_text` aceita até **20 caracteres**. A URL abre no navegador do celular e não aparece no cartão. ### Botões de resposta rápida Para o cliente responder com um toque, use `action.buttons` com itens do tipo `quick_reply`: ```json theme={null} { "card_index": 0, "type": "cta_url", "header": { "type": "image", "image": { "link": "https://exemplo.com/produto-1.jpg" } }, "body": { "text": "*Cesta de frutas*\nFrutas frescas selecionadas." }, "action": { "buttons": [ { "type": "quick_reply", "quick_reply": { "id": "cesta-frutas-saber-mais", "title": "Saber mais" } }, { "type": "quick_reply", "quick_reply": { "id": "cesta-frutas-favoritar", "title": "Favoritar" } } ] } } ``` | Campo | Limite | Para que serve | | - | - | - | | `quick_reply.id` | 256 caracteres | Identificador do botão. Inclua algo que identifique o cartão, como `cesta-frutas-saber-mais`, para saber qual produto o cliente escolheu. | | `quick_reply.title` | 20 caracteres | Texto exibido no botão. | > [!NOTE] > > Nos cartões com botões de resposta rápida, o `type` do cartão continua sendo `cta_url`, como no exemplo da Meta. O valor `quick_reply` não é aceito nesse campo. No **Testar**, o carrossel já vem preenchido com três cartões de exemplo com botão de link. Para testar botões de resposta rápida, troque o `action` de cada cartão pelo formato acima. ## Resposta do cliente Quando o cliente toca em um botão de **resposta rápida** de um cartão, chega pelo [webhook](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/mensagens.md) uma mensagem do tipo **`button`**, com o `id` do botão em `button.payload` e o rótulo em `button.text`. O `context.id` aponta para a mensagem do carrossel: ```json theme={null} { "object": "whatsapp_business_account", "entry": [ { "id": "234567890123456", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5541999999999", "phone_number_id": "123456789012345" }, "contacts": [ { "profile": { "name": "Camila Souza" }, "wa_id": "5511999999999", "user_id": "BR.13491208655302741918" } ], "messages": [ { "context": { "from": "5541999999999", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA=" }, "from": "5511999999999", "from_user_id": "BR.13491208655302741918", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjdEQjQ=", "timestamp": "1757956800", "type": "button", "button": { "payload": "cesta-frutas-saber-mais", "text": "Saber mais" } } ] }, "field": "messages" } ] } ] } ``` > [!WARNING] > > O carrossel é diferente de [Enviar botões](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/enviar-botoes.md). Lá a resposta chega como `interactive`, com `interactive.button_reply.id`. Aqui ela chega como `button`, com `button.payload`. Se o seu sistema só trata `button_reply`, os toques no carrossel passam despercebidos. Como o `payload` é o único dado que identifica a escolha, use um `id` que diga **qual cartão e qual ação**, como `cesta-frutas-saber-mais`. Cartões com **botão de link** não geram webhook quando o cliente toca. Para medir esses cliques, use um parâmetro de rastreamento na URL. A resposta do cliente é uma mensagem nova, então **renova a janela de 24 horas**. Veja mais detalhes na [documentação de carrossel de mídia da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-media-carousel-messages). ## OpenAPI ````yaml api-reference/whatsapp/specs/carrossel.json POST /v1/{phone_number_id}/messages openapi: 3.1.0 info: title: Datafy API — Enviar carrossel version: 1.0.0 servers: - url: https://cloud.datafyapi.com.br description: Produção security: - bearerAuth: [] paths: /v1/{phone_number_id}/messages: post: summary: Enviar carrossel operationId: enviarCarrossel parameters: - name: phone_number_id in: path required: true schema: type: string description: ID do número que envia a mensagem. Descubra com `GET /me`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MensagemCarrossel' example: messaging_product: whatsapp recipient_type: individual to: '5511999999999' type: interactive interactive: type: carousel body: text: Confira as ofertas da semana selecionadas para você. action: cards: - card_index: 0 type: cta_url header: type: image image: link: >- https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg body: text: |- *Cesta de frutas* Frutas frescas selecionadas, entregues no mesmo dia. action: name: cta_url parameters: display_text: Comprar url: https://datafyapi.com.br - card_index: 1 type: cta_url header: type: image image: link: >- https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg body: text: |- *Kit saudável* Verduras, grãos e frutas para a semana toda. action: name: cta_url parameters: display_text: Comprar url: https://datafyapi.com.br - card_index: 2 type: cta_url header: type: image image: link: >- https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg body: text: |- *Buquê de flores* Arranjo com flores da estação para presentear. action: name: cta_url parameters: display_text: Comprar url: https://datafyapi.com.br responses: '200': description: Envio aceito pela Meta. Não confirma a entrega. content: application/json: example: messaging_product: whatsapp contacts: - input: '5511999999999' wa_id: '5511999999999' messages: - id: wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA= '400': description: >- Erro retornado pela Meta, como usar `id` em vez de `link` no cabeçalho do cartão. content: application/json: example: error: message: (#131009) Parameter value is not valid type: OAuthException code: 131009 error_data: messaging_product: whatsapp details: >- The parameter interactive['action']['cards'][].header.image.link is required fbtrace_id: AbCdEfGhIjK '401': description: Token ausente ou inválido. content: application/json: example: statusCode: 401 message: Token inválido ou não encontrado. components: schemas: MensagemCarrossel: type: object required: - messaging_product - to - type - interactive properties: messaging_product: type: string enum: - whatsapp default: whatsapp example: whatsapp description: Sempre `whatsapp`. recipient_type: type: string enum: - individual default: individual example: individual description: Sempre `individual`. to: type: string example: '5511999999999' description: >- Número do destinatário com código do país e DDD, como `5511999999999`. Tem prioridade sobre `recipient`: para enviar pelo ID do usuário, deixe em branco. recipient: type: string description: >- ID do usuário no WhatsApp (BSUID), recebido nos webhooks em `from_user_id` e `contacts[].user_id`, como `BR.13491208655302741918`. Usado quando `to` não é informado. type: type: string enum: - interactive default: interactive example: interactive description: Sempre `interactive`. interactive: type: object required: - type - body - action description: >- Carrossel de cartões com mídia, texto e botão. Não aceita cabeçalho nem rodapé no nível da mensagem. properties: type: type: string enum: - carousel default: carousel example: carousel description: Sempre `carousel`. body: type: object required: - text description: Texto exibido acima dos cartões. properties: text: type: string maxLength: 1024 example: Confira as ofertas da semana selecionadas para você. description: Texto da mensagem, com até 1.024 caracteres. action: type: object required: - cards properties: cards: type: array minItems: 2 maxItems: 10 description: >- De 2 a 10 cartões. Todos precisam usar o mesmo tipo de mídia e o mesmo tipo e quantidade de botões. items: $ref: '#/components/schemas/Cartao' context: type: object description: Responde citando uma mensagem anterior da conversa. properties: message_id: type: string description: ID (`wamid`) da mensagem que será citada. Cartao: type: object required: - card_index - type - header - action properties: card_index: type: integer minimum: 0 maximum: 9 example: 0 description: Posição do cartão no carrossel, começando em `0`. type: type: string enum: - cta_url - button default: cta_url example: cta_url description: >- Obrigatório. Use `cta_url`, inclusive nos cartões com botões de resposta rápida. header: type: object required: - type description: >- Mídia do cartão. Todos os cartões precisam usar o mesmo tipo: só imagens ou só vídeos. properties: type: type: string enum: - image - video example: image description: 'Tipo da mídia: `image` ou `video`.' image: type: object description: Imagem do cartão, usada quando `type` é `image`. properties: link: type: string description: >- URL pública da imagem. No carrossel, a mídia só é aceita por `link`. video: type: object description: Vídeo do cartão, usado quando `type` é `video`. properties: link: type: string description: >- URL pública do vídeo. No carrossel, a mídia só é aceita por `link`. body: type: object description: Texto opcional do cartão. properties: text: type: string maxLength: 160 description: >- Texto do cartão, com até 160 caracteres e no máximo 2 quebras de linha. action: type: object description: >- Botões do cartão: um botão com link (`name` e `parameters`) ou botões de resposta rápida (`buttons`). properties: name: type: string enum: - cta_url description: Use `cta_url` para um botão com link. parameters: type: object description: Botão com link. properties: display_text: type: string maxLength: 20 description: Texto do botão, com até 20 caracteres. url: type: string description: URL aberta quando o cliente toca no botão. buttons: type: array description: >- Botões de resposta rápida. Use no lugar de `name` e `parameters`. items: type: object required: - type - quick_reply properties: type: type: string enum: - quick_reply description: Sempre `quick_reply`. quick_reply: type: object required: - id - title properties: id: type: string maxLength: 256 description: Identificador do botão, com até 256 caracteres. title: type: string maxLength: 20 description: Texto do botão, com até 20 caracteres. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Token gerado no painel da Datafy ao criar o canal. Formato: `sk_live_xxx`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.