Atualizado em 25/10/2026
Para usar catálogo na API do WhatsApp, você cadastra os produtos em um catálogo da Meta (pelo Commerce Manager ou pela API de Commerce), conecta esse catálogo à conta do WhatsApp Business e envia mensagens interativas que mostram os itens: catálogo completo, um produto só ou até 30 produtos organizados em seções. O cliente navega, monta o carrinho dentro do WhatsApp e envia o pedido, que chega no seu webhook como mensagem do tipo order.
Este guia mostra a configuração, os formatos de mensagem com exemplos de payload, o tratamento do pedido e os limites que a documentação oficial aponta.
Como funciona o comércio pelo catálogo
A visão geral de catálogos da Meta divide o processo em quatro etapas:
- Inventário: os produtos sobem para um catálogo da Meta, com nome, descrição, preço, imagens e disponibilidade. O catálogo aceita produtos físicos ou digitais e também serviços.
- Configuração de comércio: por número, você define se o carrinho fica ativo e se o ícone de vitrine aparece.
- Envio: mensagens de catálogo, de produto único, multiproduto ou carrossel.
- Resposta: perguntas e pedidos chegam pelo webhook de mensagens.
Passo 1: criar e conectar o catálogo
Se a empresa já tem um catálogo na Meta (usado em anúncios ou no Instagram, por exemplo), pode usá-lo. Se não tem, há dois caminhos, segundo a página Upload inventory:
- criar no Commerce Manager, manualmente, por planilha ou feed;
- criar pela API de Commerce da Meta, útil quando o estoque vem de um ERP ou de uma plataforma de e-commerce.
Depois, conecte o catálogo à conta do WhatsApp pelo WhatsApp Manager, seguindo a ajuda da Meta sobre conectar catálogos.
Duas regras importantes:
- Um catálogo por conta do WhatsApp. O mesmo catálogo vale para todos os números daquela conta.
- Revisão automática. O WhatsApp revisa os itens adicionados ao catálogo conectado. Itens que violam a política de comércio são sinalizados, e a contestação é feita no Commerce Manager.
O campo que liga tudo é o SKU do produto, que a API chama de product_retailer_id e o Commerce Manager mostra como ID de conteúdo. Use o mesmo SKU do seu sistema para não precisar de tabela de conversão.
Passo 2: carrinho e vitrine por número
As configurações de comércio ficam no endpoint whatsapp_commerce_settings de cada número. Pela página Set commerce settings, o padrão é carrinho ativo e vitrine oculta.
# Ativar o carrinho e mostrar o ícone de vitrine
curl -X POST "https://graph.facebook.com/vXX.X/PHONE_NUMBER_ID/whatsapp_commerce_settings?is_cart_enabled=true&is_catalog_visible=true" \
-H "Authorization: Bearer TOKEN"| Configuração | Padrão | Efeito |
|---|---|---|
is_cart_enabled | true | Mostra os botões de adicionar ao carrinho no chat, no catálogo e nos detalhes do produto |
is_catalog_visible | false | Mostra o ícone de vitrine na conversa e a prévia do catálogo no perfil da empresa |
Atenção: se a vitrine estiver oculta, links wa.me para o catálogo e o botão Ver catálogo mostram aviso de link inválido.
Passo 3: escolher o formato da mensagem
| Formato | O que mostra | Tipo na API | Fora da janela de 24 h |
|---|---|---|---|
| Mensagem de catálogo | Imagem de um produto, texto e botão Ver catálogo | catalog_message | Template de catálogo |
| Produto único | Um produto com imagem, título, preço e botão Ver | product | Template de produto único |
| Multiproduto | Até 30 produtos em seções | product_list | Template multiproduto (categoria marketing, até 10 seções) |
| Carrossel de produtos | De 2 a 10 cartões de produto com rolagem horizontal | carousel | Template de carrossel |
As mensagens interativas de produto não precisam de aprovação prévia, porque são montadas na hora com preço e estoque atuais. Mas a Meta deixa claro que as mensagens de produto único e multiproduto não podem ser enviadas como notificação: só dentro de uma conversa em andamento, ou seja, na janela de 24 horas. Para iniciar contato, use o template correspondente.
Produto único
{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "interactive",
"interactive": {
"type": "product",
"body": { "text": "Esse é o modelo que você perguntou." },
"footer": { "text": "Frete grátis acima de R$ 199" },
"action": {
"catalog_id": "CATALOG_ID",
"product_retailer_id": "TENIS-AZUL-42"
}
}
}Multiproduto
No multiproduto, o cabeçalho de texto é obrigatório, e cada seção tem um título e uma lista de SKUs.
{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "interactive",
"interactive": {
"type": "product_list",
"header": { "type": "text", "text": "Sugestões para você" },
"body": { "text": "Separei alguns itens da nova coleção." },
"action": {
"catalog_id": "CATALOG_ID",
"sections": [
{
"title": "Tênis",
"product_items": [
{ "product_retailer_id": "TENIS-AZUL-42" },
{ "product_retailer_id": "TENIS-PRETO-42" }
]
},
{
"title": "Meias",
"product_items": [
{ "product_retailer_id": "MEIA-KIT-3" }
]
}
]
}
}
}Se nenhum SKU enviado existir no catálogo, a API devolve erro e não manda a mensagem. Se pelo menos um existir, a mensagem sai, os SKUs sem correspondência são descartados e você recebe um erro pedindo atualização do catálogo. Vale validar a lista contra o estoque antes de enviar.
Mensagem de catálogo
{
"messaging_product": "whatsapp",
"to": "5584999999999",
"type": "interactive",
"interactive": {
"type": "catalog_message",
"body": { "text": "Veja todos os produtos e monte seu pedido por aqui." },
"action": {
"name": "catalog_message",
"parameters": { "thumbnail_product_retailer_id": "TENIS-AZUL-42" }
}
}
}O thumbnail_product_retailer_id define a imagem do cabeçalho. Sem ele, o WhatsApp usa a imagem do primeiro item do catálogo.
Passo 4: receber o carrinho
Quando o cliente envia o carrinho, chega no webhook uma mensagem do tipo order, descrita na referência do webhook de pedidos:
{
"from": "5584999999999",
"id": "wamid.HBgL...",
"timestamp": "1761400000",
"type": "order",
"order": {
"catalog_id": "CATALOG_ID",
"text": "Pode ser entrega amanhã?",
"product_items": [
{ "product_retailer_id": "TENIS-AZUL-42", "quantity": 1, "item_price": 299.9, "currency": "BRL" },
{ "product_retailer_id": "MEIA-KIT-3", "quantity": 2, "item_price": 39.9, "currency": "BRL" }
]
}
}O que fazer com ele:
- Recalcular o total no seu sistema a partir do SKU e do preço atual. Não use o
item_pricedo webhook como verdade para cobrança sem conferir. - Responder na mesma conversa com o resumo, frete e forma de pagamento. A janela de atendimento está aberta, porque o pedido é uma mensagem do cliente.
- Registrar o
idda mensagem para não processar o mesmo pedido duas vezes se o webhook for reenviado.
Se o cliente tocar em Enviar mensagem dentro de um produto, chega uma mensagem de texto com o objeto context indicando qual produto ele estava vendo. Use isso para responder sem perguntar “qual item?”.
Para empresas no Brasil, a Meta também documenta uma API de pagamentos com mensagens order_details e order_status, que permitem cobrar por PIX, boleto ou link de pagamento dentro da conversa.
Regras do carrinho que afetam o atendimento
Segundo a documentação oficial:
- existe um carrinho por conversa e por aparelho; ele não sincroniza entre aparelhos do mesmo cliente;
- o carrinho não expira até ser enviado; depois de enviado, não pode ser editado, e o cliente precisa mandar outro;
- cada item aceita até 99 unidades, sem limite de itens diferentes;
- a empresa não pode enviar um carrinho para o cliente;
- se um produto ficar indisponível, ele sai do carrinho e o cliente vê o aviso de que itens foram atualizados;
- pela Cloud API, o ícone de carrinho não aparece no cabeçalho da conversa, ao contrário do app WhatsApp Business.
Para quem atende com várias pessoas, isso significa que o pedido só existe no seu sistema depois que o webhook order chega. O artigo sobre delivery e restaurantes mostra como encadear o pedido com mensagens de status, e o de recuperação de carrinho trata dos lembretes.
Custos
As mensagens de produto seguem a cobrança normal. Mensagens interativas enviadas na janela de atendimento são mensagens de serviço: cada número tem 1.000 entregues grátis por mês, e a partir daí há cobrança por mensagem. Os templates de catálogo, de produto e multiproduto pagam pela categoria do template; o template multiproduto, por exemplo, é sempre de marketing. O pedido enviado pelo cliente não é cobrado. Os valores estão em quanto custa a API do WhatsApp no Brasil.
Como isso funciona na Vectalk
Na Vectalk, as mensagens de produto usam o mesmo payload da Meta no POST /api/messages: a página Enviar Produto / Catálogo traz exemplos de produto único (product), multiproduto (product_list) e mensagem de catálogo (catalog_message). As configurações de carrinho e vitrine podem ser lidas e alteradas pela própria API, com is_cart_enabled e is_catalog_visible, nos endpoints Obter e Atualizar configurações de comércio, usando token de instância. O pedido chega nos webhooks registrados como mensagem order, com catalog_id e product_items, conforme a documentação de webhooks.
Para começar, crie sua conta em apps.vectalk.com.br/register. Se a sua operação é de loja virtual, o artigo WhatsApp API para e-commerce complementa este guia, e o guia da API oficial do WhatsApp traz a visão geral. Para mandar a primeira mensagem por código, veja como enviar mensagem pela API do WhatsApp.
Perguntas frequentes
Posso usar o mesmo catálogo do Instagram e dos anúncios?
Sim. Se a empresa já tem um catálogo na Meta, a orientação oficial é usá-lo e conectá-lo à conta do WhatsApp.
Quantos produtos cabem em uma mensagem multiproduto?
Até 30 produtos. No template multiproduto, eles podem ser organizados em até 10 seções.
Posso mandar uma mensagem de produto para quem não falou comigo hoje?
Não com a mensagem interativa: ela só pode ser enviada dentro de uma conversa em andamento. Para iniciar contato, use um template de catálogo, de produto único, multiproduto ou de carrossel.
O cliente consegue pagar dentro do WhatsApp?
O carrinho envia o pedido, não o pagamento. Para empresas no Brasil, a Meta documenta uma API de pagamentos com PIX, boleto e link de pagamento por meio das mensagens order_details. Sem ela, você responde ao pedido com o link ou os dados de pagamento do seu checkout.
Preciso aprovar as mensagens de produto?
As mensagens interativas de produto não precisam de aprovação. Os templates de catálogo e de produtos passam pela análise normal de templates.
Fontes oficiais consultadas em 25/10/2026: Catalogs overview, Upload inventory, Set commerce settings, Share products, Single-product messages, Multi-product messages, Multi-product template messages, Catalog messages, Product carousel messages, Receive responses, Order messages webhook, WhatsApp orders (Brasil), Preços da plataforma, Ajuda da Meta: conectar catálogo, Enviar Produto / Catálogo na Vectalk, Configurações de comércio na Vectalk.