Enviar carrossel

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": "carousel",
    "body": {
      "text": "Confira as ofertas da semana selecionadas para você."
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg"
            }
          },
          "body": {
            "text": "*Cesta de frutas*\nFrutas frescas selecionadas, entregues no mesmo dia."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg"
            }
          },
          "body": {
            "text": "*Kit saudável*\nVerduras, grãos e frutas para a semana toda."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        },
        {
          "card_index": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg"
            }
          },
          "body": {
            "text": "*Buquê de flores*\nArranjo com flores da estação para presentear."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        }
      ]
    }
  }
}
'

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: 'carousel',
      body: JSON.stringify({text: 'Confira as ofertas da semana selecionadas para você.'}),
      action: {
        cards: [
          {
            card_index: 0,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg'
              }
            },
            body: JSON.stringify({
              text: '*Cesta de frutas*\nFrutas frescas selecionadas, entregues no mesmo dia.'
            }),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          },
          {
            card_index: 1,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg'
              }
            },
            body: JSON.stringify({text: '*Kit saudável*\nVerduras, grãos e frutas para a semana toda.'}),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          },
          {
            card_index: 2,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg'
              }
            },
            body: JSON.stringify({text: '*Buquê de flores*\nArranjo com flores da estação para presentear.'}),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          }
        ]
      }
    }
  })
};

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": "carousel",
        "body": { "text": "Confira as ofertas da semana selecionadas para você." },
        "action": { "cards": [
                {
                    "card_index": 0,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg" }
                    },
                    "body": { "text": "*Cesta de frutas*
Frutas frescas selecionadas, entregues no mesmo dia." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                },
                {
                    "card_index": 1,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg" }
                    },
                    "body": { "text": "*Kit saudável*
Verduras, grãos e frutas para a semana toda." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                },
                {
                    "card_index": 2,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg" }
                    },
                    "body": { "text": "*Buquê de flores*
Arranjo com flores da estação para presentear." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                }
            ] }
    }
}
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": "(#131009) Parameter value is not valid",
    "type": "OAuthException",
    "code": 131009,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "The parameter interactive['action']['cards'][].header.image.link is required"
    },
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

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

POST

{phone_number_id}

messages

Enviar carrossel

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": "carousel",
    "body": {
      "text": "Confira as ofertas da semana selecionadas para você."
    },
    "action": {
      "cards": [
        {
          "card_index": 0,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg"
            }
          },
          "body": {
            "text": "*Cesta de frutas*\nFrutas frescas selecionadas, entregues no mesmo dia."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        },
        {
          "card_index": 1,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg"
            }
          },
          "body": {
            "text": "*Kit saudável*\nVerduras, grãos e frutas para a semana toda."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        },
        {
          "card_index": 2,
          "type": "cta_url",
          "header": {
            "type": "image",
            "image": {
              "link": "https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg"
            }
          },
          "body": {
            "text": "*Buquê de flores*\nArranjo com flores da estação para presentear."
          },
          "action": {
            "name": "cta_url",
            "parameters": {
              "display_text": "Comprar",
              "url": "https://datafyapi.com.br"
            }
          }
        }
      ]
    }
  }
}
'

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: 'carousel',
      body: JSON.stringify({text: 'Confira as ofertas da semana selecionadas para você.'}),
      action: {
        cards: [
          {
            card_index: 0,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg'
              }
            },
            body: JSON.stringify({
              text: '*Cesta de frutas*\nFrutas frescas selecionadas, entregues no mesmo dia.'
            }),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          },
          {
            card_index: 1,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg'
              }
            },
            body: JSON.stringify({text: '*Kit saudável*\nVerduras, grãos e frutas para a semana toda.'}),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          },
          {
            card_index: 2,
            type: 'cta_url',
            header: {
              type: 'image',
              image: {
                link: 'https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg'
              }
            },
            body: JSON.stringify({text: '*Buquê de flores*\nArranjo com flores da estação para presentear.'}),
            action: {
              name: 'cta_url',
              parameters: {display_text: 'Comprar', url: 'https://datafyapi.com.br'}
            }
          }
        ]
      }
    }
  })
};

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": "carousel",
        "body": { "text": "Confira as ofertas da semana selecionadas para você." },
        "action": { "cards": [
                {
                    "card_index": 0,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/2/2f/Culinary_fruits_front_view.jpg" }
                    },
                    "body": { "text": "*Cesta de frutas*
Frutas frescas selecionadas, entregues no mesmo dia." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                },
                {
                    "card_index": 1,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/6/6d/Good_Food_Display_-_NCI_Visuals_Online.jpg" }
                    },
                    "body": { "text": "*Kit saudável*
Verduras, grãos e frutas para a semana toda." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                },
                {
                    "card_index": 2,
                    "type": "cta_url",
                    "header": {
                        "type": "image",
                        "image": { "link": "https://upload.wikimedia.org/wikipedia/commons/3/3f/JPEG_example_flower.jpg" }
                    },
                    "body": { "text": "*Buquê de flores*
Arranjo com flores da estação para presentear." },
                    "action": {
                        "name": "cta_url",
                        "parameters": {
                            "display_text": "Comprar",
                            "url": "https://datafyapi.com.br"
                        }
                    }
                }
            ] }
    }
}
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": "(#131009) Parameter value is not valid",
    "type": "OAuthException",
    "code": 131009,
    "error_data": {
      "messaging_product": "whatsapp",
      "details": "The parameter interactive['action']['cards'][].header.image.link is required"
    },
    "fbtrace_id": "AbCdEfGhIjK"
  }
}

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

Envia um carrossel de cartões que o cliente rola para o lado. Cada cartão tem uma imagem ou um vídeo, um texto curto e um botão. É ideal para apresentar produtos, planos ou opções lado a lado. 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 carousel:

Parte	Campo	Obrigatório	Limite
Texto	`interactive.body.text`	Sim	1.024 caracteres. Aparece acima dos cartões.
Cartões	`interactive.action.cards`	Sim	De 2 a 10 cartões.

O carrossel não aceita cabeçalho nem rodapé no nível da mensagem. A mídia e os botões ficam dentro de cada cartão.

Cartões

Cada item de cards é um cartão:

Campo	Obrigatório	Regra
`card_index`	Sim	Posição do cartão, começando em `0` e indo até `9`.
`type`	Sim	Use `cta_url`, inclusive nos cartões com botões de resposta rápida. Sem esse campo, a Meta recusa o envio.
`header`	Sim	Imagem ou vídeo do cartão, somente por `link`.
`body.text`	Não	Texto do cartão, com até 160 caracteres e no máximo 2 quebras de linha.
`action`	Sim	Um botão com link ou botões de resposta rápida.

Todos os cartões precisam ser iguais na estrutura: o mesmo tipo de mídia (só imagens ou só vídeos) e o mesmo tipo e quantidade de botões. Se um cartão tem dois botões de resposta rápida, todos precisam ter dois.

Mídia do cartão

A mídia do cartão fica em header, com type igual a image ou video, e só é aceita por link:

"header": {
  "type": "image",
  "image": { "link": "https://exemplo.com/produto-1.jpg" }
}

O carrossel não aceita o id de mídia no cartão. Com header.image.id, a Meta recusa o envio com o erro 131009 (“The parameter interactive[‘action’][‘cards’][].header.image.link is required”). Para gerar um link, envie o arquivo na aba Mídias do número, no painel da Datafy.

Os formatos e tamanhos aceitos são os mesmos de Enviar imagem e Enviar vídeo.

Botão com link

Para um botão que abre uma URL, use name igual a cta_url e os parameters:

{
  "card_index": 0,
  "type": "cta_url",
  "header": {
    "type": "image",
    "image": { "link": "https://exemplo.com/produto-1.jpg" }
  },
  "body": { "text": "*Cesta de frutas*\nFrutas frescas selecionadas." },
  "action": {
    "name": "cta_url",
    "parameters": {
      "display_text": "Comprar",
      "url": "https://exemplo.com/produto-1"
    }
  }
}

display_text aceita até 20 caracteres. A URL abre no navegador do celular e não aparece no cartão.

Botões de resposta rápida

Para o cliente responder com um toque, use action.buttons com itens do tipo quick_reply:

{
  "card_index": 0,
  "type": "cta_url",
  "header": {
    "type": "image",
    "image": { "link": "https://exemplo.com/produto-1.jpg" }
  },
  "body": { "text": "*Cesta de frutas*\nFrutas frescas selecionadas." },
  "action": {
    "buttons": [
      {
        "type": "quick_reply",
        "quick_reply": { "id": "cesta-frutas-saber-mais", "title": "Saber mais" }
      },
      {
        "type": "quick_reply",
        "quick_reply": { "id": "cesta-frutas-favoritar", "title": "Favoritar" }
      }
    ]
  }
}

Campo	Limite	Para que serve
`quick_reply.id`	256 caracteres	Identificador do botão. Inclua algo que identifique o cartão, como `cesta-frutas-saber-mais`, para saber qual produto o cliente escolheu.
`quick_reply.title`	20 caracteres	Texto exibido no botão.

Nos cartões com botões de resposta rápida, o type do cartão continua sendo cta_url, como no exemplo da Meta. O valor quick_reply não é aceito nesse campo.

No Testar, o carrossel já vem preenchido com três cartões de exemplo com botão de link. Para testar botões de resposta rápida, troque o action de cada cartão pelo formato acima.

Resposta do cliente

Quando o cliente toca em um botão de resposta rápida de um cartão, chega pelo webhook uma mensagem do tipo button, com o id do botão em button.payload e o rótulo em button.text. O context.id aponta para a mensagem do carrossel:

{
  "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.HBgNNTUxMTk5OTk5OTk5ORUCABIYFjdEQjQ=",
                "timestamp": "1757956800",
                "type": "button",
                "button": {
                  "payload": "cesta-frutas-saber-mais",
                  "text": "Saber mais"
                }
              }
            ]
          },
          "field": "messages"
        }
      ]
    }
  ]
}

O carrossel é diferente de Enviar botões. Lá a resposta chega como interactive, com interactive.button_reply.id. Aqui ela chega como button, com button.payload. Se o seu sistema só trata button_reply, os toques no carrossel passam despercebidos.

Como o payload é o único dado que identifica a escolha, use um id que diga qual cartão e qual ação, como cesta-frutas-saber-mais. Cartões com botão de link não geram webhook quando o cliente toca. Para medir esses cliques, use um parâmetro de rastreamento na URL. A resposta do cliente é uma mensagem nova, então renova a janela de 24 horas. Veja mais detalhes na documentação de carrossel de mídia 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

Carrossel de cartões com mídia, texto e botão. Não aceita cabeçalho nem rodapé no nível da mensagem.

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 carrossel

Estrutura da mensagem

Cartões

Mídia do cartão

Botão com link

Botões de resposta rápida

Resposta do cliente

Autorizações

Parâmetros de caminho

Corpo

Resposta

​Estrutura da mensagem

​Cartões

​Mídia do cartão

​Botão com link

​Botões de resposta rápida

​Resposta do cliente

Autorizações

Parâmetros de caminho

Corpo

Resposta

Estrutura da mensagem

Cartões

Mídia do cartão

Botão com link

Botões de resposta rápida

Resposta do cliente