Enviar Lista

Auth: TokenAccount ou TokenInstance • Rate-limit: Global (100/min) • Idempotente: não

Descrição

Envia uma lista interativa com até 10 seções e 10 rows por seção (limite total de 100 rows somando todas as seções). O destinatário toca o botão (buttonText) para abrir o menu e escolher uma das opções, e o WhatsApp retorna o id da row selecionada como uma mensagem de resposta. Ideal para menus, catálogos curtos, FAQs guiadas e atendimento estruturado.

Exemplos

Lista simples (1 seção)

Menu enxuto com uma única seção “Pratos” e duas rows. O destinatário toca em “Ver opções” para abrir o menu e selecionar uma das opções, que volta como resposta carregando o id (p1 ou p2).

curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Selecione um item do cardápio:",
    "buttonText":  "Ver opções",
    "sections": [
      {
        "title": "Pratos",
        "rows": [
          { "id": "p1", "title": "Lasanha", "description": "Bolonhesa, 4 fatias" },
          { "id": "p2", "title": "Risoto",  "description": "Funghi" }
        ]
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/list/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:      "5511999999999",
    contentText: "Selecione um item do cardápio:",
    buttonText:  "Ver opções",
    sections: [
      {
        title: "Pratos",
        rows: [
          { id: "p1", title: "Lasanha", description: "Bolonhesa, 4 fatias" },
          { id: "p2", title: "Risoto",  description: "Funghi" }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/list/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":      "5511999999999",
        "contentText": "Selecione um item do cardápio:",
        "buttonText":  "Ver opções",
        "sections": [
            {
                "title": "Pratos",
                "rows": [
                    {"id": "p1", "title": "Lasanha", "description": "Bolonhesa, 4 fatias"},
                    {"id": "p2", "title": "Risoto",  "description": "Funghi"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":      "5511999999999",
        "contentText": "Selecione um item do cardápio:",
        "buttonText":  "Ver opções",
        "sections": [
            {
                "title": "Pratos",
                "rows": [
                    { "id": "p1", "title": "Lasanha", "description": "Bolonhesa, 4 fatias" },
                    { "id": "p2", "title": "Risoto",  "description": "Funghi" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/list/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Lista com múltiplas categorias agrupadas em seções. Cada seção é renderizada com um cabeçalho próprio dentro do menu, separando visualmente os grupos.

curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "contentText": "Cardápio completo. Escolha uma opção:",
    "buttonText":  "Abrir menu",
    "sections": [
      {
        "title": "Pratos principais",
        "rows": [
          { "id": "p1", "title": "Lasanha",  "description": "Bolonhesa, 4 fatias" },
          { "id": "p2", "title": "Risoto",   "description": "Funghi" },
          { "id": "p3", "title": "Salmão",   "description": "Grelhado com legumes" }
        ]
      },
      {
        "title": "Bebidas",
        "rows": [
          { "id": "b1", "title": "Suco natural" },
          { "id": "b2", "title": "Refrigerante" }
        ]
      },
      {
        "title": "Sobremesas",
        "rows": [
          { "id": "s1", "title": "Pudim" },
          { "id": "s2", "title": "Sorvete", "description": "3 sabores" }
        ]
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/list/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:      "5511999999999",
    contentText: "Cardápio completo. Escolha uma opção:",
    buttonText:  "Abrir menu",
    sections: [
      {
        title: "Pratos principais",
        rows: [
          { id: "p1", title: "Lasanha", description: "Bolonhesa, 4 fatias" },
          { id: "p2", title: "Risoto",  description: "Funghi" },
          { id: "p3", title: "Salmão",  description: "Grelhado com legumes" }
        ]
      },
      {
        title: "Bebidas",
        rows: [
          { id: "b1", title: "Suco natural" },
          { id: "b2", title: "Refrigerante" }
        ]
      },
      {
        title: "Sobremesas",
        rows: [
          { id: "s1", title: "Pudim" },
          { id: "s2", title: "Sorvete", description: "3 sabores" }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/list/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":      "5511999999999",
        "contentText": "Cardápio completo. Escolha uma opção:",
        "buttonText":  "Abrir menu",
        "sections": [
            {
                "title": "Pratos principais",
                "rows": [
                    {"id": "p1", "title": "Lasanha", "description": "Bolonhesa, 4 fatias"},
                    {"id": "p2", "title": "Risoto",  "description": "Funghi"},
                    {"id": "p3", "title": "Salmão",  "description": "Grelhado com legumes"}
                ]
            },
            {
                "title": "Bebidas",
                "rows": [
                    {"id": "b1", "title": "Suco natural"},
                    {"id": "b2", "title": "Refrigerante"}
                ]
            },
            {
                "title": "Sobremesas",
                "rows": [
                    {"id": "s1", "title": "Pudim"},
                    {"id": "s2", "title": "Sorvete", "description": "3 sabores"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":      "5511999999999",
        "contentText": "Cardápio completo. Escolha uma opção:",
        "buttonText":  "Abrir menu",
        "sections": [
            {
                "title": "Pratos principais",
                "rows": [
                    { "id": "p1", "title": "Lasanha", "description": "Bolonhesa, 4 fatias" },
                    { "id": "p2", "title": "Risoto",  "description": "Funghi" },
                    { "id": "p3", "title": "Salmão",  "description": "Grelhado com legumes" }
                ]
            },
            {
                "title": "Bebidas",
                "rows": [
                    { "id": "b1", "title": "Suco natural" },
                    { "id": "b2", "title": "Refrigerante" }
                ]
            },
            {
                "title": "Sobremesas",
                "rows": [
                    { "id": "s1", "title": "Pudim" },
                    { "id": "s2", "title": "Sorvete", "description": "3 sabores" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/list/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Lista com cabeçalho e rodapé

Adiciona headerText (título acima do corpo) e footerText (texto em cinza abaixo do botão), úteis para branding e disclaimers curtos.

curl -X POST "https://ryzeapi.cloud/api/message/list/$Instance_Name" \
  -H "token: $Token_Instance" \
  -H "Content-Type: application/json" \
  -d '{
    "number":      "5511999999999",
    "headerText":  "Atendimento RyzeAPI",
    "contentText": "Como podemos ajudar você hoje?",
    "footerText":  "Atendimento 24/7",
    "buttonText":  "Ver opções",
    "sections": [
      {
        "title": "Suporte",
        "rows": [
          { "id": "sup_tec",  "title": "Suporte técnico" },
          { "id": "sup_fin",  "title": "Financeiro" },
          { "id": "sup_com",  "title": "Comercial",   "description": "Falar com vendas" }
        ]
      }
    ]
  }'

await fetch(`https://ryzeapi.cloud/api/message/list/${process.env.Instance_Name}`, {
  method: "POST",
  headers: {
    "token":        process.env.Token_Instance,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    number:      "5511999999999",
    headerText:  "Atendimento RyzeAPI",
    contentText: "Como podemos ajudar você hoje?",
    footerText:  "Atendimento 24/7",
    buttonText:  "Ver opções",
    sections: [
      {
        title: "Suporte",
        rows: [
          { id: "sup_tec", title: "Suporte técnico" },
          { id: "sup_fin", title: "Financeiro" },
          { id: "sup_com", title: "Comercial", description: "Falar com vendas" }
        ]
      }
    ]
  })
});

import os, requests

requests.post(
    f"https://ryzeapi.cloud/api/message/list/{os.environ['Instance_Name']}",
    headers={
        "token":        os.environ["Token_Instance"],
        "Content-Type": "application/json"
    },
    json={
        "number":      "5511999999999",
        "headerText":  "Atendimento RyzeAPI",
        "contentText": "Como podemos ajudar você hoje?",
        "footerText":  "Atendimento 24/7",
        "buttonText":  "Ver opções",
        "sections": [
            {
                "title": "Suporte",
                "rows": [
                    {"id": "sup_tec", "title": "Suporte técnico"},
                    {"id": "sup_fin", "title": "Financeiro"},
                    {"id": "sup_com", "title": "Comercial", "description": "Falar com vendas"}
                ]
            }
        ]
    }
)

package main

import (
    "net/http"
    "os"
    "strings"
)

func main() {
    body := strings.NewReader(`{
        "number":      "5511999999999",
        "headerText":  "Atendimento RyzeAPI",
        "contentText": "Como podemos ajudar você hoje?",
        "footerText":  "Atendimento 24/7",
        "buttonText":  "Ver opções",
        "sections": [
            {
                "title": "Suporte",
                "rows": [
                    { "id": "sup_tec", "title": "Suporte técnico" },
                    { "id": "sup_fin", "title": "Financeiro" },
                    { "id": "sup_com", "title": "Comercial", "description": "Falar com vendas" }
                ]
            }
        ]
    }`)
    req, _ := http.NewRequest("POST", "https://ryzeapi.cloud/api/message/list/"+os.Getenv("Instance_Name"), body)
    req.Header.Set("token", os.Getenv("Token_Instance"))
    req.Header.Set("Content-Type", "application/json")
    http.DefaultClient.Do(req)
}

Resposta de sucesso

O content retornado é o contentText enviado, e o messageType fica fixo em list. Guarde o messageId para correlacionar com os eventos de seleção que chegam via webhook.

200 OK

{
  "success": true,
  "message": "List message sent successfully",
  "status":  "sent",
  "data": {
    "messageId":   "3EB08FCF27E532F1B0F5",
    "direction":   "sent",
    "messageType": "list",
    "content":     "Selecione um item do cardápio:",
    "source":      "api",
    "timestamp":   "2026-04-30T14:30:00Z",
    "chat": {
      "jid":     "5511999999999@s.whatsapp.net",
      "isGroup": false
    },
    "sender": {
      "jid":      "5511777777777@s.whatsapp.net",
      "instance": "minha-instancia"
    }
  }
}

Quando o destinatário escolhe uma opção, o WhatsApp envia uma mensagem de resposta contendo o id da row selecionada, você captura essa resposta via webhook/websocket de eventos para dar continuidade ao fluxo.

Parâmetros de rota

string

obrigatório

Nome da instância (ex.: $Instance_Name).

Headers

string

obrigatório

TokenAccount ou TokenInstance.

string

obrigatório

application/json

Request body

string

obrigatório

Destino: telefone (5511999999999) ou JID (@s.whatsapp.net, @lid, @g.us, @newsletter).

string

obrigatório

Corpo principal da mensagem (descrição). Aparece acima do botão que abre a lista.

string

obrigatório

Texto do botão que abre a lista (ex.: "Ver opções", "Abrir menu"). Limitado pelo WhatsApp a poucos caracteres.

ListSection[]

obrigatório

Array de 1 a 10 seções. O total de rows somando todas as seções não pode exceder 100.

Mostrar ListSection

string

obrigatório

Título da seção (cabeçalho do grupo dentro do menu).

ListRow[]

obrigatório

Array de 1 a 10 rows por seção.

Mostrar ListRow

string

obrigatório

Identificador único da row. É o valor que volta como resposta quando o usuário seleciona essa opção.

string

obrigatório

Título exibido para a opção.

string

Texto secundário em cinza, abaixo do título.

string

Título exibido acima do contentText. Opcional.

string

Texto em cinza claro abaixo do botão. Opcional, ideal para disclaimers curtos.

int

padrão:"0"

Tempo em segundos para aguardar antes de enviar. Durante o intervalo, o servidor envia o indicador de “digitando…” ao destinatário e dispara o “paused” antes do envio real.

string

ID da mensagem a ser citada (reply). A mensagem original precisa pertencer à mesma instância e ter sido salva no banco.

boolean

padrão:"false"

Quando true e replyTo aponta para uma mensagem originária de um grupo, a resposta é redirecionada para o privado do autor original (mantendo a citação).

string

padrão:"api"

Identificador de origem para rastreabilidade (ex.: crm, bot-suporte, n8n). Salvo no registro da mensagem no banco e propagado para webhooks.

Notas

Limites do WhatsApp: máximo de 10 seções, 10 rows por seção e 100 rows no total. Excedeu? O servidor responde com 400 antes de tentar enviar.
A row selecionada pelo usuário retorna pelo evento de mensagem como uma resposta carregando o id original, capture isso via webhook para mapear a escolha.
Listas funcionam bem em DM, grupos e canais, mas a UX pode variar entre WhatsApp Business e WhatsApp pessoal.
description é opcional por row, mas melhora bastante a legibilidade quando o título sozinho é ambíguo.

Erros

HTTP	Status interno	Mensagem
400	,	`Instance name is required`
400	,	`Invalid request body: <detalhe>`
400	,	`Number is required`
400	,	`ContentText is required`
400	,	`ButtonText is required`
400	,	`At least one section is required`
400	,	`Maximum of 10 sections allowed`
400	,	`Section N: Title is required`
400	,	`Section N: At least one row is required`
400	,	`Section N: Maximum of 10 rows allowed`
400	,	`Section N, Row M: ID is required`
400	,	`Section N, Row M: Title is required`
400	,	`Total number of rows across all sections cannot exceed 100`
400	`invalid_number`	`Invalid phone number format: <detalhe>`
404	,	`Instance not found`
500	`send_failed`	`Failed to send message: <reason>`
503	`disconnected`	`Instance is not connected to WhatsApp`

Envelope de erro:

{
  "success": false,
  "error": { "message": "ContentText is required" }
}

Introdução

Instância

Eventos

Mensagens

Chamadas

Grupos

Comunidades

Newsletter

Perfil

Chat

Chatwoot

Typebot

Observabilidade

Descrição

Exemplos

Lista simples (1 seção)

Menu multi-seção (categorias)

Lista com cabeçalho e rodapé

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros

​Descrição

​Exemplos

​Lista simples (1 seção)

​Menu multi-seção (categorias)

​Lista com cabeçalho e rodapé

​Resposta de sucesso

​Parâmetros de rota

​Headers

​Request body

​Notas

​Erros

Descrição

Exemplos

Lista simples (1 seção)

Menu multi-seção (categorias)

Lista com cabeçalho e rodapé

Resposta de sucesso

Parâmetros de rota

Headers

Request body

Notas

Erros