Mensagens Interativas no WhatsApp: Botões, Listas, Enquetes e PIX

O PanÐá Zap suporta mensagens interativas — botões, listas, enquetes e cartões de ação — no WhatsApp. O formato exato da requisição depende do motor de conexão do canal (Baileys, Zapo ou UazAPI, todos não oficiais/QR Code) ou do canal WABA (API oficial da Meta), porque cada provedor expõe um conjunto diferente de recursos nativos. Todas as requisições exigem o cabeçalho Authorization: Bearer {BearerToken}.

Ao contrário dos endpoints de Enviar Mensagens, a maioria dos endpoints interativos abaixo usa ticketId em vez de number — eles respondem dentro de uma conversa já aberta. Use Enviar por Ticket ou um webhook recebido para obter o ticketId antes de chamar estes endpoints.

Provedor	Tipo de canal	Prefixo da rota
Baileys	Não oficial (QR Code)	`/sendInteractive/baileys/*`
Zapo	Não oficial (QR Code)	`/sendInteractive/zapo/*`
UazAPI	Não oficial	`/sendInteractive/uazapi/*`
WABA	Oficial (Meta Cloud API)	`/sendButtonWABA`, `/sendListWABA`

Baileys

Canais conectados via Baileys (QR Code) suportam seis tipos de mensagem interativa.

Resposta Rápida (Botões)

Envia até 3 botões de resposta rápida abaixo de uma mensagem de texto.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/quickReply

{
  "ticketId": 1262,
  "body": { "text": "Escolha uma opção:" },
  "footer": { "text": "Rodapé opcional" },
  "buttons": [
    { "display_text": "Opção 1", "id": "op1" },
    { "display_text": "Opção 2", "id": "op2" }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket (conversa) de destino.
`body.text`	string	Sim	Texto principal da mensagem, exibido acima dos botões.
`footer.text`	string	Não	Texto pequeno exibido abaixo dos botões.
`buttons`	array	Sim	Lista de botões (máximo recomendado: 3).
`buttons[].display_text`	string	Sim	Texto exibido no botão.
`buttons[].id`	string	Sim	Identificador retornado no payload de webhook quando o contato tocar no botão.

Seleção Única (Lista)

Envia um menu em formato de lista, agrupado em seções, acionado por um botão “Ver opções”.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/singleSelect

{
  "ticketId": 1262,
  "body": { "text": "Escolha uma opção:" },
  "footer": { "text": "Rodapé" },
  "list": {
    "title": "Ver opções",
    "sections": [
      {
        "title": "Seção 1",
        "rows": [
          { "id": "1", "title": "Item 1", "description": "Descrição" },
          { "id": "2", "title": "Item 2" }
        ]
      }
    ]
  }
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`body.text`	string	Sim	Texto principal exibido acima do botão de abertura da lista.
`footer.text`	string	Não	Texto pequeno exibido no rodapé.
`list.title`	string	Sim	Texto do botão que abre a lista — por exemplo, `"Ver opções"`.
`list.sections`	array	Sim	Seções da lista, cada uma com um `title` e um array `rows`.
`list.sections[].rows[].id`	string	Sim	Identificador retornado via webhook quando o item for selecionado.
`list.sections[].rows[].title`	string	Sim	Título do item na lista.
`list.sections[].rows[].description`	string	Não	Descrição secundária exibida abaixo do título do item.

Botão de PIX

Envia um botão que exibe os dados de uma chave PIX para pagamento direto pelo WhatsApp.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/pixButton

{
  "ticketId": 1262,
  "pixType": "EVP",
  "pixKey": "chave-aleatoria-uuid",
  "pixName": "Nome Beneficiario",
  "bodyText": "Pague com PIX:"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`pixType`	string	Sim	Tipo da chave PIX — `EVP` (chave aleatória), `CPF`, `CNPJ`, `EMAIL` ou `PHONE`.
`pixKey`	string	Sim	Valor da chave PIX correspondente ao `pixType`.
`pixName`	string	Sim	Nome do beneficiário exibido no botão.
`bodyText`	string	Não	Texto de introdução exibido acima do botão.

CTA — Copiar Código

Envia um botão que copia um código (cupom, rastreio, token) para a área de transferência do contato.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/ctaCopy

{
  "ticketId": 1262,
  "body": { "text": "Copie seu código:" },
  "footer": { "text": "Válido por 24h" },
  "displayText": "Copiar código",
  "copyCode": "BR123456789"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`body.text`	string	Sim	Texto principal da mensagem.
`footer.text`	string	Não	Texto do rodapé.
`displayText`	string	Sim	Texto exibido no botão.
`copyCode`	string	Sim	Valor copiado para a área de transferência ao tocar no botão.

CTA — Abrir URL

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/ctaUrl

{
  "ticketId": 1262,
  "body": { "text": "Acesse nosso site:" },
  "footer": { "text": "Clique para visitar" },
  "displayText": "Visitar site",
  "url": "https://exemplo.com"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`body.text`	string	Sim	Texto principal da mensagem.
`footer.text`	string	Não	Texto do rodapé.
`displayText`	string	Sim	Texto exibido no botão.
`url`	string	Sim	URL aberta no navegador do contato ao tocar no botão.

CTA — Ligar

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/baileys/ctaCall

{
  "ticketId": 1262,
  "body": { "text": "Precisa de ajuda?" },
  "footer": { "text": "Ligue para nós" },
  "displayText": "Ligar agora",
  "phoneNumber": "+5511999999999"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`body.text`	string	Sim	Texto principal da mensagem.
`footer.text`	string	Não	Texto do rodapé.
`displayText`	string	Sim	Texto exibido no botão.
`phoneNumber`	string	Sim	Número discado ao tocar no botão, no formato internacional (`+55...`).

Zapo

Canais conectados via Zapo suportam os mesmos seis tipos do Baileys acima — quickReply, singleSelect, pixButton, ctaCopy, ctaUrl e ctaCall — com campos idênticos, apenas trocando o segmento da URL de baileys para zapo:

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/quickReply
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/singleSelect
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/pixButton
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/ctaCopy
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/ctaUrl
POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/ctaCall

Consulte as tabelas de campos na seção Baileys acima — elas se aplicam sem alteração a cada rota equivalente do Zapo.

Enquete (exclusivo Zapo)

Além dos seis tipos compartilhados, o Zapo oferece um sétimo tipo, exclusivo deste provedor: enquetes nativas do WhatsApp.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/zapo/poll

{
  "ticketId": 1262,
  "name": "Qual sua preferência?",
  "options": ["Opção A", "Opção B", "Opção C"],
  "selectableCount": 1
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`name`	string	Sim	Pergunta da enquete.
`options`	string[]	Sim	Lista de opções de resposta (mínimo 2).
`selectableCount`	integer	Não	Quantas opções o contato pode selecionar simultaneamente. Use `1` para escolha única.

UazAPI

Canais conectados via UazAPI têm seu próprio conjunto de sete tipos interativos, com nomes de campo próprios (text/choices em vez de body/buttons).

Botão

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/button

{
  "ticketId": 1262,
  "text": "Escolha uma opção:",
  "choices": ["Opção 1", "Opção 2", "Opção 3"],
  "footerText": "Rodapé opcional",
  "imageButton": "https://exemplo.com/img.png"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`text`	string	Sim	Texto principal da mensagem.
`choices`	string[]	Sim	Textos dos botões exibidos (um botão por item).
`footerText`	string	Não	Texto do rodapé.
`imageButton`	string	Não	URL de uma imagem exibida acima do texto.

Lista

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/list

{
  "ticketId": 1262,
  "text": "Escolha uma opção:",
  "choices": ["Item 1", "Item 2", "Item 3", "Item 4"],
  "listButton": "Ver opções",
  "footerText": "Selecione uma opção"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`text`	string	Sim	Texto principal, exibido acima do botão de abertura.
`choices`	string[]	Sim	Itens exibidos dentro da lista.
`listButton`	string	Sim	Texto do botão que abre a lista.
`footerText`	string	Não	Texto do rodapé.

Enquete

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/poll

{
  "ticketId": 1262,
  "text": "Qual sua preferência?",
  "choices": ["Opção A", "Opção B", "Opção C"],
  "selectableCount": 1
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`text`	string	Sim	Pergunta da enquete.
`choices`	string[]	Sim	Opções de resposta.
`selectableCount`	integer	Não	Quantas opções podem ser selecionadas simultaneamente.

Carrossel

Envia uma série de cartões navegáveis horizontalmente, cada um com imagem, texto e botões próprios.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/carousel

{
  "ticketId": 1262,
  "text": "Confira nossas opções:",
  "carousel": [
    {
      "text": "Produto A",
      "image": "https://exemplo.com/a.png",
      "buttons": [{ "text": "Ver detalhes", "type": "REPLY" }]
    },
    {
      "text": "Produto B",
      "image": "https://exemplo.com/b.png",
      "buttons": [{ "text": "Comprar", "type": "URL" }]
    }
  ]
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`text`	string	Não	Texto introdutório exibido acima do carrossel.
`carousel`	array	Sim	Lista de cartões do carrossel.
`carousel[].text`	string	Sim	Texto do cartão.
`carousel[].image`	string	Sim	URL da imagem do cartão.
`carousel[].buttons[].text`	string	Sim	Texto do botão dentro do cartão.
`carousel[].buttons[].type`	string	Sim	`REPLY` para um botão de resposta rápida, ou `URL` para abrir um link.

Botão de PIX

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/pixButton

{
  "ticketId": 1262,
  "pixType": "EVP",
  "pixKey": "chave-aleatoria-uuid",
  "pixName": "Nome Beneficiario"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`pixType`	string	Sim	Tipo da chave PIX — `EVP`, `CPF`, `CNPJ`, `EMAIL` ou `PHONE`.
`pixKey`	string	Sim	Valor da chave PIX.
`pixName`	string	Sim	Nome do beneficiário.

Botão de Localização

Solicita que o próprio contato compartilhe a localização dele pelo WhatsApp.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/locationButton

{
  "ticketId": 1262,
  "text": "Por favor, compartilhe sua localização:"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`text`	string	Sim	Texto do pedido exibido ao contato.

Solicitar Pagamento

Envia uma cobrança formatada com valor, descrição e dados de PIX para pagamento.

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendInteractive/uazapi/requestPayment

{
  "ticketId": 1262,
  "amount": 150.00,
  "title": "Pedido #001",
  "text": "Sua cobrança está pronta:",
  "footer": "Vencimento em 3 dias",
  "itemName": "Produto X",
  "invoiceNumber": "NF-001",
  "pixType": "EVP",
  "pixKey": "chave-aleatoria-uuid",
  "pixName": "Nome Beneficiario"
}

Campo	Tipo	Obrigatório	Descrição
`ticketId`	integer	Sim	ID do ticket de destino.
`amount`	number	Sim	Valor cobrado.
`title`	string	Sim	Título da cobrança.
`text`	string	Não	Texto introdutório.
`footer`	string	Não	Texto do rodapé — por exemplo, prazo de vencimento.
`itemName`	string	Não	Nome do item ou serviço cobrado.
`invoiceNumber`	string	Não	Número da nota fiscal ou referência interna.
`pixType`	string	Sim	Tipo da chave PIX.
`pixKey`	string	Sim	Valor da chave PIX.
`pixName`	string	Sim	Nome do beneficiário.

WABA (Oficial)

Canais WABA têm apenas dois tipos interativos suportados pela Cloud API da Meta — botões de resposta rápida e listas — e, diferente dos provedores acima, endereçam o destinatário por number (podendo também fixar em um ticketId específico).

Botões (SendButtonWABA)

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendButtonWABA

{
  "number": "5515998566622",
  "message": "Escolha uma opção:",
  "button1": "Opção 1",
  "button2": "Opção 2",
  "button3": "Opção 3",
  "ticketId": 1262
}

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do WhatsApp do destinatário.
`message`	string	Sim	Texto que acompanha os botões.
`button1`	string	Sim	Texto do primeiro botão.
`button2`	string	Sim	Texto do segundo botão.
`button3`	string	Não	Texto do terceiro botão (a Meta permite até 3).
`ticketId`	integer	Não	Direciona a mensagem para um ticket específico já aberto com este contato.

Lista (SendListWABA)

POST https://{BaseUrl}/v2/api/external/{ApiID}/sendListWABA

{
  "number": "5515998566622",
  "header": "Menu Principal",
  "body": "Escolha uma opção da lista:",
  "footer": "Selecione uma opção",
  "button_text": "Ver opções",
  "sections": [
    {
      "title": "Seção 1",
      "rows": [
        { "id": "1", "title": "Opção 1", "description": "Descrição da opção 1" },
        { "id": "2", "title": "Opção 2", "description": "Descrição da opção 2" }
      ]
    }
  ],
  "ticketId": 1262
}

Campo	Tipo	Obrigatório	Descrição
`number`	string	Sim	Número do WhatsApp do destinatário.
`header`	string	Não	Cabeçalho da mensagem de lista.
`body`	string	Sim	Corpo principal da mensagem.
`footer`	string	Não	Rodapé da mensagem.
`button_text`	string	Sim	Texto do botão que abre a lista.
`sections`	array	Sim	Seções da lista, cada uma com `title` e `rows[]`.
`sections[].rows[].id`	string	Sim	Identificador retornado via webhook quando selecionado.
`sections[].rows[].title`	string	Sim	Título do item.
`sections[].rows[].description`	string	Não	Descrição secundária do item.
`ticketId`	integer	Não	Direciona a mensagem para um ticket específico já aberto com este contato.

Resposta de Sucesso

Todos os endpoints interativos acima retornam o formato padrão de envio:

{
  "success": true,
  "data": {
    "message": "Message sent successfully",
    "ticketId": 1262
  }
}

A seleção feita pelo contato (botão tocado, item da lista escolhido, resposta da enquete) chega de volta como uma mensagem recebida comum no webhook do canal — consulte Webhooks — trazendo o id do botão/linha selecionado no corpo da mensagem.

Primeiros Passos

Mensagens