# Enviar lista

> Envie uma lista de opções com seções no WhatsApp usando POST /v1/messages e receba a escolha do contato.

`POST /v1/messages` com `type: "interactive"` e `interactive.type: "list"` mostra um botão que abre uma lista de opções. Só existe no WhatsApp. Os campos que valem para todos os envios estão em [Campos comuns](/send/text/#campos-comuns).

## Antes de começar

- Uma chave de API com a permissão `send` (veja [Autenticação](/api/authentication/)).
- Uma conexão **Ativa** do WhatsApp.
- Mensagem interativa é mensagem livre: só sai dentro da janela de 24 horas (veja [Janelas](/api/limits/#janelas)). Fora dela, use um template.

## Enviar uma lista

**cURL**

```bash
curl https://api.messajo.com/v1/messages \
  -H "Authorization: Bearer $MESSAJO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "connection_id": "conn_...",
      "to": "5511999999999",
      "type": "interactive",
      "interactive": {
        "type": "list",
        "header": {
          "type": "text",
          "text": "Atendimento"
        },
        "body": {
          "text": "Sobre o que você quer falar?"
        },
        "footer": {
          "text": "Escolha uma opção"
        },
        "action": {
          "button": "Ver opções",
          "sections": [
            {
              "title": "Pedidos",
              "rows": [
                {
                  "id": "status",
                  "title": "Status do pedido",
                  "description": "Onde está minha entrega"
                },
                {
                  "id": "troca",
                  "title": "Troca ou devolução"
                }
              ]
            },
            {
              "title": "Conta",
              "rows": [
                {
                  "id": "fatura",
                  "title": "Segunda via da fatura"
                },
                {
                  "id": "humano",
                  "title": "Falar com uma pessoa",
                  "description": "Atendimento em horário comercial"
                }
              ]
            }
          ]
        }
      }
    }'
```

**TypeScript**

```ts
import { Messajo } from "@messajo/sdk";

const messajo = new Messajo({ apiKey: process.env.MESSAJO_API_KEY! });

const sent = await messajo.messages.send({
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Atendimento"
    },
    "body": {
      "text": "Sobre o que você quer falar?"
    },
    "footer": {
      "text": "Escolha uma opção"
    },
    "action": {
      "button": "Ver opções",
      "sections": [
        {
          "title": "Pedidos",
          "rows": [
            {
              "id": "status",
              "title": "Status do pedido",
              "description": "Onde está minha entrega"
            },
            {
              "id": "troca",
              "title": "Troca ou devolução"
            }
          ]
        },
        {
          "title": "Conta",
          "rows": [
            {
              "id": "fatura",
              "title": "Segunda via da fatura"
            },
            {
              "id": "humano",
              "title": "Falar com uma pessoa",
              "description": "Atendimento em horário comercial"
            }
          ]
        }
      ]
    }
  }
});
```

**n8n**

n8n HTTP Request: POST https://api.messajo.com/v1/messages

```json
{
  "connection_id": "conn_...",
  "to": "5511999999999",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "Atendimento"
    },
    "body": {
      "text": "Sobre o que você quer falar?"
    },
    "footer": {
      "text": "Escolha uma opção"
    },
    "action": {
      "button": "Ver opções",
      "sections": [
        {
          "title": "Pedidos",
          "rows": [
            {
              "id": "status",
              "title": "Status do pedido",
              "description": "Onde está minha entrega"
            },
            {
              "id": "troca",
              "title": "Troca ou devolução"
            }
          ]
        },
        {
          "title": "Conta",
          "rows": [
            {
              "id": "fatura",
              "title": "Segunda via da fatura"
            },
            {
              "id": "humano",
              "title": "Falar com uma pessoa",
              "description": "Atendimento em horário comercial"
            }
          ]
        }
      ]
    }
  }
}
```

## Campos da lista

| Campo | Regra |
|---|---|
| `interactive.body.text` | Obrigatório, de 1 a 1024 caracteres. |
| `interactive.header`, `interactive.footer` | Opcionais. Cabeçalho de texto e rodapé com até 60 caracteres. |
| `action.button` | De 1 a 20 caracteres. É o rótulo do botão que abre a lista. |
| `action.sections` | De 1 a 10 seções. |
| `sections[].title` | Opcional, até 24 caracteres. |
| `sections[].rows` | Pelo menos 1 linha. |
| `rows[].id` | De 1 a 200 caracteres. É o que você recebe de volta. |
| `rows[].title` | De 1 a 24 caracteres. |
| `rows[].description` | Opcional, até 72 caracteres. |

## Receber a escolha

A escolha chega como um evento [`message.received`](/webhooks/events/), com `data.message.content` do tipo `reply` e `kind: "list"`:

```json
{
  "type": "message.received",
  "data": {
    "message": {
      "direction": "inbound",
      "content": {
        "type": "reply",
        "kind": "list",
        "id": "status",
        "title": "Status do pedido",
        "description": "Onde está minha entrega",
        "payload": null
      }
    }
  }
}
```

`id`, `title` e `description` são os da linha escolhida. Ligue o `id` à sua lógica.

## Outros tipos interativos

- Botões de resposta e de link: [Enviar botões](/send/buttons/).
- Fluxos: [Flows](/guides/flows/).
- Catálogo e pedido com Pix: [Vendas no WhatsApp](/guides/commerce/).

## Erros comuns

- [`outside_service_window`](/errors#outside_service_window) (422): fora das 24 horas ([janelas](/api/limits/#janelas)). O fim da janela vem em `details[0].message`.
- [`type_not_supported_by_channel`](/errors#type_not_supported_by_channel) (422): o canal não aceita esse tipo. Exemplo: `interactive` no Instagram ou no Messenger, ou `buttons` no WhatsApp.
- [`validation_failed`](/errors#validation_failed) (400): corpo fora das regras, como mais de 3 botões ou título acima do limite.
