> ## Documentation Index > Fetch the complete documentation index at: https://developers.datafyapi.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Enviar lista > Envie uma mensagem com um menu de opções em lista. Envia uma mensagem com um **botão que abre uma lista de opções**, organizadas em seções. É ideal quando há mais de três escolhas, como horários disponíveis, produtos de um cardápio ou assuntos do atendimento. A [janela de 24 horas](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/introducao.md#janela-de-24-horas) precisa estar aberta. > [!NOTE] > > O destinatário pode ser informado pelo **número de telefone** (`to`) ou pelo **ID do usuário** (`recipient`). Se os dois forem enviados, vale o `to`; para enviar pelo ID do usuário, deixe o `to` em branco. Veja a diferença em [Destinatário](https://developers.datafyapi.com.br/api-reference/whatsapp/mensagens/introducao.md#destinatário). ## Estrutura da mensagem A mensagem é do tipo `interactive`, com `interactive.type` igual a `list`. O cliente vê o texto e um botão; ao tocar no botão, abre a lista para escolher **uma** opção. | Parte | Campo | Obrigatório | Limite | | - | - | - | - | | Cabeçalho | `interactive.header.text` | Não | 60 caracteres. Na lista, **só é aceito cabeçalho de texto**. | | Texto | `interactive.body.text` | **Sim** | 4.096 caracteres. | | Rodapé | `interactive.footer.text` | Não | 60 caracteres. | | Botão | `interactive.action.button` | **Sim** | 20 caracteres. É o texto do botão que abre a lista. | | Seções | `interactive.action.sections` | **Sim** | De 1 a 10 seções. | ## Seções e opções Cada seção tem um título e suas opções (`rows`): | Campo | Limite | Para que serve | | - | - | - | | `sections[].title` | 24 caracteres | Título que agrupa as opções na lista. | | `rows[].id` | 200 caracteres | Identificador que **volta no webhook** quando o cliente escolhe a opção. | | `rows[].title` | 24 caracteres | Texto da opção. | | `rows[].description` | 72 caracteres | Descrição opcional, exibida abaixo do título. | > [!WARNING] > > O limite é de **10 opções no total, somando todas as seções**, e não 10 por seção. Uma lista com duas seções, de 6 e 5 opções, é recusada com o erro `131009` ("Total row count exceed max allowed count: 10"). ```json theme={null} "action": { "button": "Ver horários", "sections": [ { "title": "Manhã", "rows": [ { "id": "seg-09h", "title": "Segunda, 9h", "description": "Unidade Centro" }, { "id": "seg-11h", "title": "Segunda, 11h", "description": "Unidade Centro" } ] }, { "title": "Tarde", "rows": [ { "id": "seg-15h", "title": "Segunda, 15h", "description": "Unidade Norte" } ] } ] } ``` No **Testar**, a lista já vem preenchida com duas seções de horários. Troque pelas opções do seu atendimento. ## Resposta do cliente Quando o cliente escolhe uma opção, chega pelo [webhook](https://developers.datafyapi.com.br/api-reference/whatsapp/webhooks/eventos/mensagens.md) uma mensagem do tipo `interactive`, com `interactive.type` igual a `list_reply`. O `list_reply.id` é o `id` da opção escolhida, e o `context.id` aponta para a mensagem com a lista: ```json theme={null} { "object": "whatsapp_business_account", "entry": [ { "id": "234567890123456", "changes": [ { "value": { "messaging_product": "whatsapp", "metadata": { "display_phone_number": "5541999999999", "phone_number_id": "123456789012345" }, "contacts": [ { "profile": { "name": "Camila Souza" }, "wa_id": "5511999999999", "user_id": "BR.13491208655302741918" } ], "messages": [ { "context": { "from": "5541999999999", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA=" }, "from": "5511999999999", "from_user_id": "BR.13491208655302741918", "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjZDQzM=", "timestamp": "1757956500", "type": "interactive", "interactive": { "type": "list_reply", "list_reply": { "id": "seg-09h", "title": "Segunda, 9h", "description": "Unidade Centro" } } } ] }, "field": "messages" } ] } ] } ``` > [!TIP] > > Use o `list_reply.id` para identificar a escolha. Um `id` com informação útil, como `seg-09h` ou `produto-123`, evita consultas extras no seu sistema. A resposta do cliente é uma mensagem nova, então **renova a janela de 24 horas**. Veja mais detalhes na [documentação de mensagens de lista da Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/messages/interactive-list-messages). ## OpenAPI ````yaml api-reference/whatsapp/specs/lista.json POST /v1/{phone_number_id}/messages openapi: 3.1.0 info: title: Datafy API — Enviar lista version: 1.0.0 servers: - url: https://cloud.datafyapi.com.br description: Produção security: - bearerAuth: [] paths: /v1/{phone_number_id}/messages: post: summary: Enviar lista operationId: enviarLista parameters: - name: phone_number_id in: path required: true schema: type: string description: ID do número que envia a mensagem. Descubra com `GET /me`. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MensagemLista' example: messaging_product: whatsapp recipient_type: individual to: '5511999999999' type: interactive interactive: type: list header: type: text text: Agende seu atendimento body: text: >- Escolha o melhor horário para o seu atendimento na próxima segunda-feira. footer: text: Clínica Exemplo action: button: Ver horários sections: - title: Manhã rows: - id: seg-09h title: Segunda, 9h description: Unidade Centro - id: seg-11h title: Segunda, 11h description: Unidade Centro - title: Tarde rows: - id: seg-15h title: Segunda, 15h description: Unidade Norte responses: '200': description: Envio aceito pela Meta. Não confirma a entrega. content: application/json: example: messaging_product: whatsapp contacts: - input: '5511999999999' wa_id: '5511999999999' messages: - id: wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA= '400': description: Erro retornado pela Meta. content: application/json: example: error: message: (#100) Invalid parameter type: OAuthException code: 100 fbtrace_id: AbCdEfGhIjK '401': description: Token ausente ou inválido. content: application/json: example: statusCode: 401 message: Token inválido ou não encontrado. components: schemas: MensagemLista: type: object required: - messaging_product - to - type - interactive properties: messaging_product: type: string enum: - whatsapp default: whatsapp example: whatsapp description: Sempre `whatsapp`. recipient_type: type: string enum: - individual default: individual example: individual description: Sempre `individual`. to: type: string example: '5511999999999' description: >- Número do destinatário com código do país e DDD, como `5511999999999`. Tem prioridade sobre `recipient`: para enviar pelo ID do usuário, deixe em branco. recipient: type: string description: >- ID do usuário no WhatsApp (BSUID), recebido nos webhooks em `from_user_id` e `contacts[].user_id`, como `BR.13491208655302741918`. Usado quando `to` não é informado. type: type: string enum: - interactive default: interactive example: interactive description: Sempre `interactive`. interactive: type: object required: - type - body - action description: Mensagem com um botão que abre uma lista de opções. properties: type: type: string enum: - list default: list example: list description: Sempre `list`. header: type: object required: - type - text description: Cabeçalho opcional. Na lista, só é aceito cabeçalho de texto. properties: type: type: string enum: - text default: text example: text description: Sempre `text`. text: type: string maxLength: 60 example: Agende seu atendimento description: Texto do cabeçalho, com até 60 caracteres. body: type: object required: - text description: Texto principal da mensagem. properties: text: type: string maxLength: 4096 example: >- Escolha o melhor horário para o seu atendimento na próxima segunda-feira. description: >- Texto da mensagem, com até 4.096 caracteres. URLs viram links clicáveis. footer: type: object description: Rodapé opcional, exibido abaixo do texto em cinza. properties: text: type: string maxLength: 60 example: Clínica Exemplo description: Texto do rodapé, com até 60 caracteres. action: type: object required: - button - sections properties: button: type: string maxLength: 20 example: Ver horários description: Texto do botão que abre a lista, com até 20 caracteres. sections: type: array minItems: 1 maxItems: 10 description: >- De 1 a 10 seções. Somando todas as seções, a lista aceita no máximo 10 opções. items: $ref: '#/components/schemas/Secao' context: type: object description: Responde citando uma mensagem anterior da conversa. properties: message_id: type: string description: ID (`wamid`) da mensagem que será citada. Secao: type: object required: - title - rows properties: title: type: string maxLength: 24 example: Manhã description: Título da seção, com até 24 caracteres. rows: type: array minItems: 1 description: >- Opções da seção. O total de opções, somando todas as seções, é de no máximo 10. items: $ref: '#/components/schemas/Opcao' Opcao: type: object required: - id - title properties: id: type: string maxLength: 200 example: seg-09h description: >- Identificador da opção, com até 200 caracteres. Volta no webhook quando o cliente escolhe a opção. title: type: string maxLength: 24 example: Segunda, 9h description: Texto da opção, com até 24 caracteres. description: type: string maxLength: 72 example: Unidade Centro description: Descrição opcional exibida abaixo do título, com até 72 caracteres. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Token gerado no painel da Datafy ao criar o canal. Formato: `sk_live_xxx`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.