Enviar menú interactivo (botones, carrusel, lista o encuesta)

Este endpoint ofrece una interfaz unificada para el envío de cuatro tipos principales de mensajes interactivos:

• Botones: Para acciones rápidas y directas
• Carrusel de botones: Para una lista horizontal de botones con imágenes
• Listas: Para menús organizados en secciones
• Encuestas: Para recopilar opiniones y votaciones

Soporte para campos de seguimiento: Este endpoint también admite track_source y track_id documentados en la tag “Enviar Mensaje”.

Estructura base del payload

Todas las solicitudes siguen esta estructura base:

{
  "number": "5511999999999",
  "type": "button|button_legacy|list|poll|carousel",
  "text": "Texto principal da mensagem",
  "choices": ["opções baseadas no tipo escolhido"],
  "footerText": "Texto do rodapé (opcional para botões e listas)",
  "listButton": "Texto do botão (para listas)",
  "selectableCount": "Número de opções selecionáveis (apenas para enquetes)"
}

Tipos de mensajes interactivos

1. Botones (type: “button”)

Crea botones interactivos con diferentes funcionalidades de acción.

Campos específicos

• footerText: Texto opcional mostrado debajo del mensaje principal
• choices: Array de opciones que se convertirán en botones

Formatos de botones

Cada botón puede configurarse usando | (pipe) o \n (salto de línea) como separadores:

• Botón de respuesta:

  • "texto|id" o
  • "texto\nid" o
  • "texto" (el ID será igual al texto)

• Botón de copia:

  • "texto|copy:código" o
  • "texto\ncopy:código"

• Botón de llamada:

  • "texto|call:+5511999999999" o
  • "texto\ncall:+5511999999999"

• Botón de URL:

  • "texto|https://exemplo.com" o
  • "texto|url:https://exemplo.com"

Botones con imagen, video o documento

El encabezado del botón puede llevar una imagen, un video o un documento en file, por URL o base64, como en /send/media. El tipo se obtiene del propio archivo; para forzarlo, envíe mimetype: image, video, document o el MIME type del archivo (por ejemplo, video/mp4). El documento usa el nombre de docName; sin él, el nombre del archivo.

El audio no se admite en el botón: WhatsApp no tiene audio en el encabezado, y la API responde 400. Envíe el audio antes, con /send/media. Sin mimetype, la API reconoce el audio por la extensión de la URL o por el inicio del base64; en una URL sin extensión, indique el mimetype.

{
  "number": "5511999999999",
  "type": "button",
  "text": "Escolha um produto:",
  "file": "https://exemplo.com/produto1.jpg",
  "choices": [
    "Produto A|prod_a",
    "Mais Info|https://exemplo.com/produto-a",
    "Produto B|prod_b",
    "Ligar|call:+5511999999999"
  ],
  "footerText": "Produtos em destaque"
}

{
  "number": "5511999999999",
  "type": "button",
  "text": "Tabela de preços de outubro",
  "file": "https://exemplo.com/tabela.pdf",
  "docName": "Tabela de preços.pdf",
  "choices": ["Quero comprar|comprar", "Falar com vendedor|vendedor"]
}

Si el medio no se descarga o no se sube a WhatsApp, el botón se envía sin él.

Botones en formato legado (type: “button_legacy”)

Use button_legacy solo cuando necesite enviar los botones de respuesta del formato anterior. El formato de choices es:

• "texto|id"
• "texto\nid"
• "texto|reply:id"
• "texto" — el propio texto se usará como ID

Este modo crea solo botones de respuesta. Las acciones de URL, llamada y copia y el medio en file siguen disponibles en el formato actual type: "button".

{
  "number": "5511999999999",
  "type": "button_legacy",
  "text": "Deseja continuar?",
  "choices": [
    "Sim|confirmar",
    "Não|reply:cancelar"
  ],
  "footerText": "Escolha uma opção"
}

Ejemplo completo

{
  "number": "5511999999999",
  "type": "button",
  "text": "Como podemos ajudar?",
  "choices": [
    "Suporte Técnico|suporte",
    "Fazer Pedido|pedido",
    "Nosso Site|https://exemplo.com",
    "Falar Conosco|call:+5511999999999"
  ],
  "footerText": "Escolha uma das opções abaixo"
}

Limitaciones y compatibilidad

Importante: Al combinar botones de respuesta con otros tipos (call, url, copy) en el mismo mensaje, se mostrará el aviso: “No es posible mostrar este mensaje en WhatsApp Web. Abra WhatsApp en su teléfono para verlo.”

2. Listas (type: “list”)

Crea menús organizados en secciones con elementos seleccionables.

Campos específicos

• listButton: Texto del botón que abre la lista
• footerText: Texto opcional del pie de página
• choices: Array con las secciones y los elementos de la lista

Formato de las choices

• "[Título da Seção]": Inicia una nueva sección
• "texto|id|descrição": Elemento de la lista con:
  • texto: Etiqueta del elemento
  • id: Identificador único, opcional
  • descrição: Texto descriptivo adicional y opcional

Ejemplo completo

{
  "number": "5511999999999",
  "type": "list",
  "text": "Catálogo de Produtos",
  "choices": [
    "[Eletrônicos]",
    "Smartphones|phones|Últimos lançamentos",
    "Notebooks|notes|Modelos 2024",
    "[Acessórios]",
    "Fones|fones|Bluetooth e com fio",
    "Capas|cases|Proteção para seu device"
  ],
  "listButton": "Ver Catálogo",
  "footerText": "Preços sujeitos a alteração"
}

3. Encuestas (type: “poll”)

Crea encuestas interactivas para votación.

Campos específicos

• selectableCount: Número de opciones que pueden seleccionarse (predeterminado: 1)
• choices: Array simple con las opciones de voto

Ejemplo completo

{
  "number": "5511999999999",
  "type": "poll",
  "text": "Qual horário prefere para atendimento?",
  "choices": [
    "Manhã (8h-12h)",
    "Tarde (13h-17h)",
    "Noite (18h-22h)"
  ],
  "selectableCount": 1
}

4. Carousel (type: “carousel”)

Crea un carrusel de tarjetas con imágenes y botones interactivos.

Campos específicos

• choices: Array con los elementos del carrusel en el siguiente orden:
  • [Texto do cartão]: Texto de la tarjeta entre corchetes
  • {URL ou base64 da imagem}: Imagen entre llaves
  • Botones de la tarjeta (uno por línea):
    • "texto|copy:código" para botón de copiar
    • "texto|https://url" para botón de enlace
    • "texto|call:+número" para botón de llamada

Ejemplo completo

{
  "number": "5511999999999",
  "type": "carousel",
  "text": "Conheça nossos produtos",
  "choices": [
    "[Smartphone XYZ\nO mais avançado smartphone da linha]",
    "{https://exemplo.com/produto1.jpg}",
    "Copiar Código|copy:PROD123",
    "Ver no Site|https://exemplo.com/xyz",
    "Fale Conosco|call:+5511999999999",
    "[Notebook ABC\nO notebook ideal para profissionais]",
    "{https://exemplo.com/produto2.jpg}",
    "Copiar Código|copy:NOTE456",
    "Comprar Online|https://exemplo.com/abc",
    "Suporte|call:+5511988888888"
  ]
}

Nota: Creamos otro endpoint para carrusel: /send/carousel; funciona de la misma forma, pero con otro formato de payload. Elija el que le resulte más sencillo.

Términos de uso

Los recursos de botones interactivos y listas pueden ser descontinuados en cualquier momento sin previo aviso. No nos responsabilizamos por cualquier cambio o indisponibilidad de estos recursos.

Alternativas y compatibilidad

Considerando la naturaleza dinámica de estos recursos, nuestro endpoint fue diseñado para facilitar la migración entre diferentes tipos de mensajes (botones, listas y encuestas).

Recomendamos crear sus flujos de forma flexible, preparados para alternar entre los diferentes tipos.

En caso de descontinuación de algún recurso, podrá migrar fácilmente a otro tipo de mensaje solo cambiando el campo “type” en el payload, manteniendo la misma estructura de choices.