Enviar lista

curl --request POST \
  --url https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
            }
          ]
        }
      ]
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    recipient_type: 'individual',
    to: '5511999999999',
    type: 'interactive',
    interactive: {
      type: 'list',
      header: {type: 'text', text: 'Agende seu atendimento'},
      body: JSON.stringify({
        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'}]
          }
        ]
      }
    }
  })
};

fetch('https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages"

payload = {
    "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"
                        }
                    ]
                }
            ]
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "5511999999999",
      "wa_id": "5511999999999"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA="
    }
  ]
}

{
  "error": {
    "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

{
  "statusCode": 401,
  "message": "Token inválido ou não encontrado."
}

POST

{phone_number_id}

messages

Enviar lista

curl --request POST \
  --url https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
            }
          ]
        }
      ]
    }
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    messaging_product: 'whatsapp',
    recipient_type: 'individual',
    to: '5511999999999',
    type: 'interactive',
    interactive: {
      type: 'list',
      header: {type: 'text', text: 'Agende seu atendimento'},
      body: JSON.stringify({
        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'}]
          }
        ]
      }
    }
  })
};

fetch('https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://cloud.datafyapi.com.br/v1/{phone_number_id}/messages"

payload = {
    "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"
                        }
                    ]
                }
            ]
        }
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "5511999999999",
      "wa_id": "5511999999999"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjNFQjA="
    }
  ]
}

{
  "error": {
    "message": "(#100) Invalid parameter",
    "type": "OAuthException",
    "code": 100,
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

{
  "statusCode": 401,
  "message": "Token inválido ou não encontrado."
}

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 precisa estar aberta.

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.

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.

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”).

"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 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:

{
  "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"
        }
      ]
    }
  ]
}

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.

Autorizações

Authorization

string

header

obrigatório

Token gerado no painel da Datafy ao criar o canal. Formato: sk_live_xxx.

Parâmetros de caminho

phone_number_id

string

obrigatório

ID do número que envia a mensagem. Descubra com GET /me.

Corpo

application/json

messaging_product

enum<string>

padrão:whatsapp

obrigatório

Sempre whatsapp.

Opções disponíveis:

whatsapp

Exemplo:

"whatsapp"

string

obrigatório

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.

Exemplo:

"5511999999999"

type

enum<string>

padrão:interactive

obrigatório

Sempre interactive.

Opções disponíveis:

interactive

Exemplo:

"interactive"

interactive

object

obrigatório

Mensagem com um botão que abre uma lista de opções.

Show child attributes

recipient_type

enum<string>

padrão:individual

Sempre individual.

Opções disponíveis:

individual

Exemplo:

"individual"

recipient

string

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.

context

object

Responde citando uma mensagem anterior da conversa.

Show child attributes

Resposta

Envio aceito pela Meta. Não confirma a entrega.

Começar

Administração

Mensagens

Recursos de mensagens

Mídias

Templates

Conta e número

Endpoints Datafy

Webhooks

Enviar lista

Estrutura da mensagem

Seções e opções

Resposta do cliente

Autorizações

Parâmetros de caminho

Corpo

Resposta

​Estrutura da mensagem

​Seções e opções

​Resposta do cliente

Autorizações

Parâmetros de caminho

Corpo

Resposta

Estrutura da mensagem

Seções e opções

Resposta do cliente