Carrossel

Cartões lado a lado, que o contato arrasta para o lado. Cada cartão tem uma mídia, um texto e os seus botões. Serve para vitrine de produtos, planos ou opções com foto.

text: o texto que vai acima dos cartões.
cards[]: os cartões, na ordem em que aparecem.
- type: a mídia do cartão (image, video ou document). Com url e sem type, vale image.
- url ou base64: o arquivo. Use um dos dois; filename dá o nome do documento.
- text: o texto do cartão, abaixo da mídia. Aceita quebra de linha.
- choices[]: os botões do cartão. Sem action (ou action: reply), o botão responde: o contato toca e chega um message.received com interactive_reply, e o option_id é o id do botão (sem id, vale o title). Com action: url, abre o link em value; call liga para o número em value; copy copia o código em value. Esses três não geram evento: nada chega ao WhatsApp da inbox.

Nos botões, title, id e value não aceitam aspas, \ nem quebra de linha. Use id diferente em cada botão de resposta, mesmo entre cartões: o clique diz qual botão foi tocado, não qual cartão.

Só no WhatsApp Web. Na API oficial, no Telegram, no Instagram e no Messenger, responde 501 com unsupported_for_channel.

Canais

Canal	Funciona	Observação
WhatsApp (Web)	Sim
WhatsApp (API oficial)	Não
Instagram	Não
Messenger	Não
Telegram	Não

Pedido

POST /messages com "type": "carousel". Testar

{
  "to": "5511999999999",
  "type": "carousel",
  "text": "Nossos destaques",
  "cards": [
    {
      "type": "image",
      "url": "https://loja.exemplo/xyz.jpg",
      "text": "Smartphone XYZ\nR$ 1.999",
      "choices": [
        {
          "id": "comprar_xyz",
          "title": "Comprar"
        },
        {
          "title": "Ver no site",
          "action": "url",
          "value": "https://loja.exemplo/xyz"
        }
      ]
    },
    {
      "type": "image",
      "url": "https://loja.exemplo/fone.jpg",
      "text": "Fone ABC\nR$ 299",
      "choices": [
        {
          "id": "comprar_fone",
          "title": "Comprar"
        },
        {
          "title": "Falar com vendedor",
          "action": "call",
          "value": "+5511888888888"
        }
      ]
    }
  ]
}

Na uazapi

POST /send/carousel, que continua funcionando. Os botões do cartão (choices) têm o mesmo formato das outras opções; a mídia do cartão (type, url) vai solta no próprio cartão. Na uazapi o link ia no id com type: URL; na Orkesio vai em value com action: url. A resposta é a própria mensagem, igual ao message.sent.

uazapi (POST /send/carousel)

{
  "number": "5511999999999",
  "text": "Nossos destaques",
  "carousel": [
    {
      "text": "Smartphone XYZ\nR$ 1.999",
      "image": "https://loja.exemplo/xyz.jpg",
      "buttons": [
        {
          "id": "comprar_xyz",
          "text": "Comprar",
          "type": "REPLY"
        },
        {
          "id": "https://loja.exemplo/xyz",
          "text": "Ver no site",
          "type": "URL"
        }
      ]
    },
    {
      "text": "Fone ABC\nR$ 299",
      "image": "https://loja.exemplo/fone.jpg",
      "buttons": [
        {
          "id": "comprar_fone",
          "text": "Comprar",
          "type": "REPLY"
        },
        {
          "id": "+5511888888888",
          "text": "Falar com vendedor",
          "type": "CALL"
        }
      ]
    }
  ]
}

Orkesio (POST /messages)

{
  "to": "5511999999999",
  "type": "carousel",
  "text": "Nossos destaques",
  "cards": [
    {
      "type": "image",
      "url": "https://loja.exemplo/xyz.jpg",
      "text": "Smartphone XYZ\nR$ 1.999",
      "choices": [
        {
          "id": "comprar_xyz",
          "title": "Comprar"
        },
        {
          "title": "Ver no site",
          "action": "url",
          "value": "https://loja.exemplo/xyz"
        }
      ]
    },
    {
      "type": "image",
      "url": "https://loja.exemplo/fone.jpg",
      "text": "Fone ABC\nR$ 299",
      "choices": [
        {
          "id": "comprar_fone",
          "title": "Comprar"
        },
        {
          "title": "Falar com vendedor",
          "action": "call",
          "value": "+5511888888888"
        }
      ]
    }
  ]
}

Resposta

A própria mensagem (OrkesioMessage), no formato do message.sent e da busca. No WhatsApp Web volta na hora com status: queued: por padrão o envio vai pela fila (com options.async: false, espera o envio e volta a mensagem enviada). É o pedido no formato da mensagem: o arquivo, a miniatura e a prévia do link chegam no message.sent. Na API oficial volta depois que a Meta aceita, com status: pending. O resultado chega em message.status (a falha também em message.failed).

{
  "id": "3EB05DCE1D4036FCE241C6",
  "chat_id": "5511999999999@s.whatsapp.net",
  "author": {
    "id": "5511888888888@s.whatsapp.net",
    "phone": "5511888888888"
  },
  "direction": "out",
  "sent_by": "api",
  "sent_at": "2026-10-17T12:00:00.000Z",
  "type": "carousel",
  "text": "Nossos destaques",
  "cards": [
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "text": "Smartphone XYZ\nR$ 1.999",
      "choices": [
        {
          "id": "comprar_xyz",
          "title": "Comprar"
        },
        {
          "title": "Ver no site",
          "action": "url",
          "value": "https://loja.exemplo/xyz"
        }
      ]
    },
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "text": "Fone ABC\nR$ 299",
      "choices": [
        {
          "id": "comprar_fone",
          "title": "Comprar"
        },
        {
          "title": "Falar com vendedor",
          "action": "call",
          "value": "+5511888888888"
        }
      ]
    }
  ],
  "category": "unsent",
  "status": "queued"
}

Na uazapi

O content da uazapi é o proto do WhatsApp; aqui vai resumido (...).

uazapi

{
  "id": "5511888888888:3EB05DCE1D4036FCE241C6",
  "messageid": "3EB05DCE1D4036FCE241C6",
  "chatid": "5511999999999@s.whatsapp.net",
  "fromMe": true,
  "messageType": "InteractiveMessage",
  "messageTimestamp": 1792238400000,
  "text": "Nossos destaques",
  "content": {
    "body": {
      "text": "Nossos destaques"
    },
    "carouselMessage": {
      "cards": [
        "..."
      ]
    }
  },
  "wasSentByApi": true,
  "response": {
    "status": "success",
    "message": "Message sent successfully"
  }
}

Orkesio

{
  "id": "3EB05DCE1D4036FCE241C6",
  "chat_id": "5511999999999@s.whatsapp.net",
  "author": {
    "id": "5511888888888@s.whatsapp.net",
    "phone": "5511888888888"
  },
  "direction": "out",
  "sent_by": "api",
  "sent_at": "2026-10-17T12:00:00.000Z",
  "type": "carousel",
  "text": "Nossos destaques",
  "cards": [
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "text": "Smartphone XYZ\nR$ 1.999",
      "choices": [
        {
          "id": "comprar_xyz",
          "title": "Comprar"
        },
        {
          "title": "Ver no site",
          "action": "url",
          "value": "https://loja.exemplo/xyz"
        }
      ]
    },
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "text": "Fone ABC\nR$ 299",
      "choices": [
        {
          "id": "comprar_fone",
          "title": "Comprar"
        },
        {
          "title": "Falar com vendedor",
          "action": "call",
          "value": "+5511888888888"
        }
      ]
    }
  ],
  "category": "unsent",
  "status": "queued"
}

No webhook

O que chega no seu webhook (ou em GET /events) depois do envio.

message.sent

Quando o carrossel sai, com os cartões. O evento message.sent

{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD5H",
  "type": "message.sent",
  "created_at": "2026-10-17T12:00:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "message": {
      "id": "3EB05DCE1D4036FCE241C6",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511888888888@s.whatsapp.net",
        "phone": "5511888888888"
      },
      "direction": "out",
      "sent_by": "api",
      "sent_at": "2026-10-17T12:00:00.000Z",
      "category": "conversation",
      "type": "carousel",
      "text": "Nossos destaques",
      "cards": [
        {
          "type": "image",
          "mime_type": "image/jpeg",
          "text": "Smartphone XYZ\nR$ 1.999",
          "choices": [
            {
              "id": "comprar_xyz",
              "title": "Comprar"
            },
            {
              "title": "Ver no site",
              "action": "url",
              "value": "https://loja.exemplo/xyz"
            }
          ]
        },
        {
          "type": "image",
          "mime_type": "image/jpeg",
          "text": "Fone ABC\nR$ 299",
          "choices": [
            {
              "id": "comprar_fone",
              "title": "Comprar"
            },
            {
              "title": "Falar com vendedor",
              "action": "call",
              "value": "+5511888888888"
            }
          ]
        }
      ]
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    }
  }
}

message.status

sent, delivered, read e played (áudio e voz), um evento por mudança; failed se o envio falhar. O evento message.status

{
  "id": "evt_01JAB3K9ZQ7V0M4T8R2X6WYD6J",
  "type": "message.status",
  "created_at": "2026-10-17T12:00:05.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    },
    "status": "delivered",
    "at": "2026-10-17T12:00:05.000Z",
    "messages": [
      {
        "id": "3EB05DCE1D4036FCE241C6"
      }
    ]
  }
}

Quando o contato responde

message.received

O contato tocou no botão Comprar do primeiro cartão. kind é template_button (é assim que o WhatsApp manda o clique no carrossel) e reply_to é o id do carrossel. O evento message.received

{
  "id": "evt_01JAB3M2K8P4R6T8V0X2Z4B6D8",
  "type": "message.received",
  "created_at": "2026-10-17T12:03:00.000Z",
  "inbox": {
    "id": "r0269625d29bfbd",
    "name": "loja",
    "phone": "5511888888888",
    "channel": "whatsapp_web"
  },
  "data": {
    "message": {
      "id": "AC1FACA14F3FA7A19DB5FB19D7035506",
      "chat_id": "5511999999999@s.whatsapp.net",
      "author": {
        "id": "5511999999999@s.whatsapp.net",
        "phone": "5511999999999",
        "lid": "123456789012345@lid",
        "name": "Maria"
      },
      "direction": "in",
      "sent_at": "2026-10-17T12:03:00.000Z",
      "category": "conversation",
      "type": "interactive_reply",
      "kind": "template_button",
      "option_id": "comprar_xyz",
      "text": "Comprar",
      "reply_to": "3EB05DCE1D4036FCE241C6"
    },
    "chat": {
      "id": "5511999999999@s.whatsapp.net",
      "lid": "123456789012345@lid",
      "type": "direct"
    }
  }
}