Enviar carrossel de mídia com botões
POST /send/carousel
Este endpoint permite enviar um carrossel com imagens e botões interativos.
Funciona de maneira igual ao endpoint /send/menu com type: carousel, porém usando outro formato de payload.
Campos Comuns
Este endpoint suporta todos os campos opcionais comuns documentados na tag "Enviar Mensagem", incluindo:
delay, readchat, readmessages, replyid, mentions, forward, track_source, track_id, placeholders e envio para grupos.
Estrutura do Payload
{
"number": "5511999999999",
"text": "Texto principal",
"carousel": [
{
"text": "Texto do cartão",
"image": "URL da imagem",
"buttons": [
{
"id": "resposta1",
"text": "Texto do botão",
"type": "REPLY"
}
]
}
]
}
Tipos de Botões
-
REPLY: Botão de resposta rápida- Quando clicado, envia o valor do id como resposta ao chat
- O id será o texto enviado como resposta
-
URL: Botão com link- Quando clicado, abre a URL especificada
- O id deve conter a URL completa (ex: https://exemplo.com)
-
COPY: Botão para copiar texto- Quando clicado, copia o texto para a área de transferência
- O id será o texto que será copiado
-
CALL: Botão para realizar chamada- Quando clicado, inicia uma chamada telefônica
- O id deve conter o número de telefone
Exemplo de Botões
{
"buttons": [
{
"id": "Sim, quero comprar!",
"text": "Confirmar Compra",
"type": "REPLY"
},
{
"id": "https://exemplo.com/produto",
"text": "Ver Produto",
"type": "URL"
},
{
"id": "CUPOM20",
"text": "Copiar Cupom",
"type": "COPY"
},
{
"id": "5511999999999",
"text": "Falar com Vendedor",
"type": "CALL"
}
]
}
Exemplo Completo de Carrossel
{
"number": "5511999999999",
"text": "Nossos Produtos em Destaque",
"carousel": [
{
"text": "Smartphone XYZ\nO mais avançado smartphone da linha",
"image": "https://exemplo.com/produto1.jpg",
"buttons": [
{
"id": "SIM_COMPRAR_XYZ",
"text": "Comprar Agora",
"type": "REPLY"
},
{
"id": "https://exemplo.com/xyz",
"text": "Ver Detalhes",
"type": "URL"
}
]
},
{
"text": "Cupom de Desconto\nGanhe 20% OFF em qualquer produto",
"image": "https://exemplo.com/cupom.jpg",
"buttons": [
{
"id": "DESCONTO20",
"text": "Copiar Cupom",
"type": "COPY"
},
{
"id": "5511999999999",
"text": "Falar com Vendedor",
"type": "CALL"
}
]
}
]
}
Autenticação
[
{
"token": []
}
]
{
"token": {
"name": "token",
"type": "apiKey",
"in": "header"
}
}
Corpo da requisição
{
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "ID do chat para o qual a mensagem será enviada. Pode ser um número de telefone em formato internacional, um ID de grupo (`@g.us`), um ID de usuário (com `@s.whatsapp.net` ou `@lid`).",
"example": "5511999999999"
},
"text": {
"type": "string",
"description": "Texto principal da mensagem",
"example": "Nossos Produtos em Destaque"
},
"carousel": {
"type": "array",
"description": "Array de cartões do carrossel",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"description": "Texto do cartão",
"example": "Smartphone XYZ\nO mais avançado smartphone da linha"
},
"image": {
"type": "string",
"description": "URL da imagem (opcional)",
"example": "https://exemplo.com/produto1.jpg"
},
"video": {
"type": "string",
"description": "URL do vídeo (alternativa à imagem)",
"example": "https://exemplo.com/produto1.mp4"
},
"document": {
"type": "string",
"description": "URL do documento (alternativa à imagem)",
"example": "https://exemplo.com/catalogo.pdf"
},
"filename": {
"type": "string",
"description": "Nome do arquivo para documentos",
"example": "Catalogo.pdf"
},
"buttons": {
"type": "array",
"description": "Array de botões do cartão",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "ID do botão",
"example": "buy_xyz"
},
"text": {
"type": "string",
"description": "Texto exibido no botão",
"example": "Comprar Agora"
},
"type": {
"type": "string",
"description": "Tipo do botão:\n* REPLY - O id será enviado como resposta ao chat\n* URL - O id deve ser a URL completa que será aberta\n* COPY - O id será o texto copiado para área de transferência\n* CALL - O id deve ser o número de telefone para a chamada\n",
"enum": [
"REPLY",
"URL",
"CALL",
"COPY"
],
"example": "REPLY"
}
},
"required": [
"id",
"text",
"type"
]
}
}
},
"required": [
"text",
"buttons"
]
}
},
"delay": {
"type": "integer",
"description": "Atraso em milissegundos antes do envio",
"example": 1000
},
"readchat": {
"type": "boolean",
"description": "Marca conversa como lida após envio",
"example": true
},
"readmessages": {
"type": "boolean",
"description": "Marca últimas mensagens recebidas como lidas",
"example": true
},
"replyid": {
"type": "string",
"description": "ID da mensagem para responder",
"example": "3EB0538DA65A59F6D8A251"
},
"mentions": {
"type": "string",
"description": "Números para mencionar (separados por vírgula)",
"example": "5511999999999,5511888888888"
},
"forward": {
"type": "boolean",
"description": "Marca a mensagem como encaminhada no WhatsApp",
"example": false
},
"async": {
"type": "boolean",
"description": "Se true, envia a mensagem de forma assíncrona via fila interna",
"example": false
},
"track_source": {
"type": "string",
"description": "Origem do rastreamento da mensagem",
"example": "chatwoot"
},
"track_id": {
"type": "string",
"description": "ID para rastreamento da mensagem (aceita valores duplicados)",
"example": "msg_123456789"
}
},
"required": [
"number",
"carousel"
]
},
"examples": {
"basic": {
"summary": "Carrossel com um cartão",
"value": {
"number": "5511999999999",
"text": "Nossos produtos",
"carousel": [
{
"text": "Smartphone XYZ",
"image": "https://exemplo.com/produto.jpg",
"buttons": [
{
"id": "comprar_xyz",
"text": "Comprar agora",
"type": "REPLY"
}
]
}
]
}
}
}
}
}
}
Respostas
{
"200": {
"description": "Carrossel enviado com sucesso",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Message"
},
{
"type": "object",
"properties": {
"response": {
"type": "object",
"properties": {
"status": {
"type": "string",
"example": "success"
},
"message": {
"type": "string",
"example": "Carousel sent successfully"
}
}
}
}
}
]
}
}
}
},
"400": {
"description": "Requisição inválida",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Missing required fields or invalid card format"
}
}
}
}
}
},
"401": {
"description": "Não autorizado",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Invalid token"
}
}
}
}
}
},
"500": {
"description": "Erro interno do servidor",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"error": {
"type": "string",
"example": "Failed to send carousel"
}
}
}
}
}
}
}
#/components/schemas/Message
{
"type": "object",
"description": "Representa uma mensagem trocada no sistema",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "ID único interno da mensagem (formato r + 7 caracteres hex aleatórios)"
},
"messageid": {
"type": "string",
"description": "ID original da mensagem no provedor"
},
"chatid": {
"type": "string",
"description": "ID da conversa relacionada"
},
"sender": {
"type": "string",
"description": "ID do remetente da mensagem"
},
"senderName": {
"type": "string",
"description": "Nome exibido do remetente"
},
"isGroup": {
"type": "boolean",
"description": "Indica se é uma mensagem de grupo",
"default": false
},
"fromMe": {
"type": "boolean",
"description": "Indica se a mensagem foi enviada pelo usuário",
"default": false
},
"messageType": {
"type": "string",
"description": "Tipo de conteúdo da mensagem"
},
"source": {
"type": "string",
"description": "Plataforma de origem da mensagem"
},
"messageTimestamp": {
"type": "integer",
"description": "Timestamp original da mensagem em milissegundos",
"default": 0
},
"status": {
"type": "string",
"description": "Status do ciclo de vida da mensagem.\nExemplos comuns: `Queued`, `Canceled`, `Failed`, `Sent`, `Delivered`, `Read`.\n"
},
"text": {
"type": "string",
"description": "Texto original da mensagem",
"default": ""
},
"quoted": {
"type": "string",
"description": "ID da mensagem citada/respondida",
"default": ""
},
"edited": {
"type": "string",
"description": "Histórico de edições da mensagem",
"default": ""
},
"reaction": {
"type": "string",
"description": "ID da mensagem reagida",
"default": ""
},
"vote": {
"type": "string",
"description": "Dados de votação de enquete e listas",
"default": ""
},
"convertOptions": {
"type": "string",
"description": "Conversão de opções da mensagem, lista, enquete e botões",
"default": ""
},
"buttonOrListid": {
"type": "string",
"description": "ID do botão ou item de lista selecionado",
"default": ""
},
"owner": {
"type": "string",
"description": "Dono da mensagem",
"default": ""
},
"error": {
"type": "string",
"description": "Mensagem de erro caso o envio tenha falhado",
"default": ""
},
"content": {
"description": "Conteúdo bruto da mensagem (JSON serializado ou texto)",
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string",
"description": "Texto bruto quando não for JSON"
}
]
},
"wasSentByApi": {
"type": "boolean",
"description": "Indica se a mensagem foi enviada via API"
},
"sendFunction": {
"type": "string",
"description": "Função usada para enviar a mensagem (quando enviada via API)"
},
"sendPayload": {
"description": "Payload usado no envio quando disponível. Dados de mídia em base64 são omitidos.",
"oneOf": [
{
"type": "object",
"additionalProperties": true
},
{
"type": "string",
"description": "Texto bruto quando não for JSON"
}
]
},
"fileURL": {
"type": "string",
"description": "URL ou referência de arquivo da mensagem"
},
"callPeer": {
"type": "object",
"description": "Contato conhecido associado a uma ligação, quando disponível em `messageType: call`.",
"properties": {
"jid": {
"type": "string"
},
"name": {
"type": "string"
},
"imagePreviewUrl": {
"type": "string"
}
}
},
"send_folder_id": {
"type": "string",
"description": "Pasta associada ao envio (quando aplicável)"
},
"track_source": {
"type": "string",
"description": "Origem de rastreamento"
},
"track_id": {
"type": "string",
"description": "ID de rastreamento (pode repetir)"
},
"ai_metadata": {
"type": "object",
"description": "Metadados do processamento por IA",
"properties": {
"agent_id": {
"type": "string",
"description": "ID do agente de IA responsável"
},
"request": {
"type": "object",
"description": "Dados da requisição à API de IA",
"properties": {
"messages": {
"type": "array",
"description": "Histórico de mensagens enviadas para a API"
},
"tools": {
"type": "array",
"description": "Ferramentas disponíveis para o agente"
},
"options": {
"type": "object",
"description": "Opções de configuração da API",
"properties": {
"model": {
"type": "string"
},
"temperature": {
"type": "number"
},
"maxTokens": {
"type": "integer"
},
"topP": {
"type": "number"
},
"frequencyPenalty": {
"type": "number"
},
"presencePenalty": {
"type": "number"
}
}
}
}
},
"response": {
"type": "object",
"description": "Resposta da API de IA",
"properties": {
"choices": {
"type": "array",
"description": "Resultados retornados pela API"
},
"toolResults": {
"type": "array",
"description": "Resultados da execução de ferramentas"
},
"error": {
"type": "string",
"description": "Mensagem de erro, se houver"
}
}
}
}
},
"sender_pn": {
"description": "JID PN resolvido do remetente (quando disponível)",
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sender_lid": {
"description": "LID original do remetente (quando disponível)",
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"sender_image_preview_url": {
"type": "string",
"format": "uri",
"description": "URL temporária de preview do remetente, quando conhecida. A hidratação desta versão preenche mensagens recebidas em grupos; o campo pode ser omitido. Não provoca consulta de foto ao WhatsApp na listagem."
}
}
}