# Send list

> Send a list of options with sections on WhatsApp using POST /v1/messages and receive the contact's choice.

`POST /v1/messages` with `type: "interactive"` and `interactive.type: "list"` shows a button that opens a list of options. It exists on WhatsApp only. The fields shared by every send are in [Common fields](/en/send/text/#common-fields).

## Before you start

- An API key with the `send` permission (see [Authentication](/en/api/authentication/)).
- An **Active** WhatsApp connection.
- An interactive message is a free-form message: it only goes out within the 24-hour window (see [Windows](/en/api/limits/#windows)). Outside it, use a template.

## Send a list

**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": "Support"
        },
        "body": {
          "text": "What would you like to talk about?"
        },
        "footer": {
          "text": "Pick an option"
        },
        "action": {
          "button": "See options",
          "sections": [
            {
              "title": "Orders",
              "rows": [
                {
                  "id": "status",
                  "title": "Order status",
                  "description": "Where is my delivery"
                },
                {
                  "id": "troca",
                  "title": "Exchange or return"
                }
              ]
            },
            {
              "title": "Account",
              "rows": [
                {
                  "id": "fatura",
                  "title": "Invoice copy"
                },
                {
                  "id": "humano",
                  "title": "Talk to a person",
                  "description": "Business hours support"
                }
              ]
            }
          ]
        }
      }
    }'
```

**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": "Support"
    },
    "body": {
      "text": "What would you like to talk about?"
    },
    "footer": {
      "text": "Pick an option"
    },
    "action": {
      "button": "See options",
      "sections": [
        {
          "title": "Orders",
          "rows": [
            {
              "id": "status",
              "title": "Order status",
              "description": "Where is my delivery"
            },
            {
              "id": "troca",
              "title": "Exchange or return"
            }
          ]
        },
        {
          "title": "Account",
          "rows": [
            {
              "id": "fatura",
              "title": "Invoice copy"
            },
            {
              "id": "humano",
              "title": "Talk to a person",
              "description": "Business hours support"
            }
          ]
        }
      ]
    }
  }
});
```

**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": "Support"
    },
    "body": {
      "text": "What would you like to talk about?"
    },
    "footer": {
      "text": "Pick an option"
    },
    "action": {
      "button": "See options",
      "sections": [
        {
          "title": "Orders",
          "rows": [
            {
              "id": "status",
              "title": "Order status",
              "description": "Where is my delivery"
            },
            {
              "id": "troca",
              "title": "Exchange or return"
            }
          ]
        },
        {
          "title": "Account",
          "rows": [
            {
              "id": "fatura",
              "title": "Invoice copy"
            },
            {
              "id": "humano",
              "title": "Talk to a person",
              "description": "Business hours support"
            }
          ]
        }
      ]
    }
  }
}
```

## List fields

| Field | Rule |
|---|---|
| `interactive.body.text` | Required, 1 to 1024 characters. |
| `interactive.header`, `interactive.footer` | Optional. Text header and footer with up to 60 characters. |
| `action.button` | 1 to 20 characters. The label of the button that opens the list. |
| `action.sections` | 1 to 10 sections. |
| `sections[].title` | Optional, up to 24 characters. |
| `sections[].rows` | At least 1 row. |
| `rows[].id` | 1 to 200 characters. This is what you get back. |
| `rows[].title` | 1 to 24 characters. |
| `rows[].description` | Optional, up to 72 characters. |

## Receiving the choice

The choice arrives as a [`message.received`](/en/webhooks/events/) event, with `data.message.content` of type `reply` and `kind: "list"`:

```json
{
  "type": "message.received",
  "data": {
    "message": {
      "direction": "inbound",
      "content": {
        "type": "reply",
        "kind": "list",
        "id": "status",
        "title": "Order status",
        "description": "Where is my delivery",
        "payload": null
      }
    }
  }
}
```

`id`, `title` and `description` are those of the chosen row. Tie your logic to the `id`.

## Other interactive types

- Reply and link buttons: [Send buttons](/en/send/buttons/).
- Flows: [Flows](/en/guides/flows/).
- Catalog and Pix order: [Selling on WhatsApp](/en/guides/commerce/).

## Common errors

- [`outside_service_window`](/en/errors#outside_service_window) (422): outside the 24 hours ([windows](/en/api/limits/#windows)). The window end is in `details[0].message`.
- [`type_not_supported_by_channel`](/en/errors#type_not_supported_by_channel) (422): the channel does not accept this type. For example, `interactive` on Instagram or Messenger, or `buttons` on WhatsApp.
- [`validation_failed`](/en/errors#validation_failed) (400): the body breaks the rules, such as more than 3 buttons or a title over the limit.
