API atual/Referência completa/WhatsApp Commerce: caixa de entrada

Carrinho e cobrança

Envia ao cliente, dentro da conversa, um botão para abrir um carrinho montado pelo atendente ou para pagar um pedido em aberto.

Duas rotas de venda assistida. Em vez de colar um link cru no texto, a plataforma manda uma mensagem com um botão (o WhatsApp chama de cta_url, "chamada para ação com URL"). O link do botão abre a mini-loja do WhatsApp: uma página de compra leve, que reconhece o cliente pelo telefone da conversa e não pede login.

send-cart cria um carrinho com os produtos que o atendente escolheu e manda o botão Abrir carrinho.
send-payment pega um pedido que já existe e manda o botão Pagar pedido.

Em ambas, o texto da mensagem fica gravado na conversa; o link vive só no botão. O envio usa o número de WhatsApp do seller, como em Responder, e vale a mesma regra da janela de 24 horas.

Enviar um carrinho

POST/api/v1/vendor/whatsapp/inbox/threads/{id}/send-cartSeller

Envia o botão Abrir carrinho com os produtos escolhidos

O link gerado vale para o telefone da conversa e abre a mini-loja já com os itens no carrinho. Os produtos não são validados nesta chamada: um product_id inexistente só aparece quando o cliente abre o carrinho.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

itemsarrayobrigatório

Itens do carrinho. Pelo menos um com product_id preenchido; itens sem product_id são descartados.

product_iduuidobrigatório

Id do produto no catálogo.

qtyintegerpadrão: 1

Quantidade. Zero ou negativo vira 1.

namestring

Nome para exibir enquanto o carrinho carrega. Opcional.

imagestring

URL da imagem para exibir. Opcional.

messagestring

Texto que acompanha o botão. Se omitido ou em branco, a plataforma usa uma frase padrão em português convidando a abrir o carrinho e finalizar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/send-cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "qty": 2, "name": "Tênis Urbano Preto" }
    ],
    "message": "Separei o seu tênis, é só abrir e finalizar."
  }'

Resposta

200Botão enviado

json

{
  "success": true,
  "message": {
    "id": 48230,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Separei o seu tênis, é só abrir e finalizar." },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ3",
    "created_at": "2026-10-11T13:10:00Z"
  }
}

Campos da resposta

successboolean

true quando a Meta aceitou o botão.

messageobject

A mensagem gravada na conversa (texto da frase, sem o link). Mesmos campos da resposta de texto de Responder.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body"}`
400	Nenhum item com `product_id`	`{"error":"items required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Conversas
404	Conversa de outro seller ou inexistente	`{"error":"thread not found"}`
502	A Meta recusou o botão; a mensagem foi gravada	`{"error":"send-cart failed: ...","message":{...}}`
500	Não foi possível gerar o link (a loja ainda não tem endereço público da mini-loja configurado) ou falha ao gravar	`{"error":"send-cart failed: whatsapp send-cart: link indisponivel","message":null}`

Cobrar um pedido

POST/api/v1/vendor/whatsapp/inbox/threads/{id}/send-paymentSeller

Envia o botão Pagar pedido de um pedido do cliente

Aponte para um pedido que já existe (por exemplo, um de open_orders em Contexto do cliente). O botão abre a página do pedido na mini-loja, onde o cliente escolhe como pagar. Esta rota não cria cobrança nem Pix por si só: ela entrega o caminho até o pedido.

Antes de enviar, a plataforma confere que o telefone do pedido coincide com o da conversa, para o atendente não mandar o pedido de outra pessoa.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

order_iduuidobrigatório

Id do pedido a cobrar.

messagestring

Texto que acompanha o botão. Se omitido, a plataforma usa uma frase padrão em português pedindo para tocar e pagar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/send-payment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "3f73310d-bfdd-4713-a664-305c08eda58b", "message": "Pronto, é só tocar para pagar."}'

Resposta

200Botão enviado

json

{
  "success": true,
  "message": {
    "id": 48231,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Pronto, é só tocar para pagar." },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ4",
    "created_at": "2026-10-11T13:11:20Z"
  }
}

Os campos da resposta são os mesmos de send-cart.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body"}`
400	`order_id` vazio	`{"error":"order_id required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Conversas
404	Conversa de outro seller ou inexistente	`{"error":"thread not found"}`
500	O pedido não é deste cliente	`{"error":"send-payment failed: whatsapp send-payment: pedido nao e deste cliente","message":null}`
500	Link indisponível (mini-loja sem endereço público)	`{"error":"send-payment failed: whatsapp send-payment: link indisponivel","message":null}`
502	A Meta recusou o botão; a mensagem foi gravada	`{"error":"send-payment failed: ...","message":{...}}`

Veja também

API atual/Referência completa/WhatsApp Commerce: caixa de entrada

Carrinho e cobrança

Envia ao cliente, dentro da conversa, um botão para abrir um carrinho montado pelo atendente ou para pagar um pedido em aberto.

send-cart cria um carrinho com os produtos que o atendente escolheu e manda o botão Abrir carrinho.
send-payment pega um pedido que já existe e manda o botão Pagar pedido.

Em ambas, o texto da mensagem fica gravado na conversa; o link vive só no botão. O envio usa o número de WhatsApp do seller, como em Responder, e vale a mesma regra da janela de 24 horas.

Enviar um carrinho

POST/api/v1/vendor/whatsapp/inbox/threads/{id}/send-cartSeller

Envia o botão Abrir carrinho com os produtos escolhidos

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

itemsarrayobrigatório

Itens do carrinho. Pelo menos um com product_id preenchido; itens sem product_id são descartados.

product_iduuidobrigatório

Id do produto no catálogo.

qtyintegerpadrão: 1

Quantidade. Zero ou negativo vira 1.

namestring

Nome para exibir enquanto o carrinho carrega. Opcional.

imagestring

URL da imagem para exibir. Opcional.

messagestring

Texto que acompanha o botão. Se omitido ou em branco, a plataforma usa uma frase padrão em português convidando a abrir o carrinho e finalizar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/send-cart" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "product_id": "c3f92551-9dda-4fc7-b518-353d1c4e4035", "qty": 2, "name": "Tênis Urbano Preto" }
    ],
    "message": "Separei o seu tênis, é só abrir e finalizar."
  }'

Resposta

200Botão enviado

json

{
  "success": true,
  "message": {
    "id": 48230,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Separei o seu tênis, é só abrir e finalizar." },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ3",
    "created_at": "2026-10-11T13:10:00Z"
  }
}

Campos da resposta

successboolean

true quando a Meta aceitou o botão.

messageobject

A mensagem gravada na conversa (texto da frase, sem o link). Mesmos campos da resposta de texto de Responder.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body"}`
400	Nenhum item com `product_id`	`{"error":"items required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Conversas
404	Conversa de outro seller ou inexistente	`{"error":"thread not found"}`
502	A Meta recusou o botão; a mensagem foi gravada	`{"error":"send-cart failed: ...","message":{...}}`
500	Não foi possível gerar o link (a loja ainda não tem endereço público da mini-loja configurado) ou falha ao gravar	`{"error":"send-cart failed: whatsapp send-cart: link indisponivel","message":null}`

Cobrar um pedido

POST/api/v1/vendor/whatsapp/inbox/threads/{id}/send-paymentSeller

Envia o botão Pagar pedido de um pedido do cliente

Antes de enviar, a plataforma confere que o telefone do pedido coincide com o da conversa, para o atendente não mandar o pedido de outra pessoa.

Parâmetros de caminho

iduuidobrigatório

Id da conversa.

Corpo da requisição

order_iduuidobrigatório

Id do pedido a cobrar.

messagestring

Texto que acompanha o botão. Se omitido, a plataforma usa uma frase padrão em português pedindo para tocar e pagar.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/inbox/threads/$THREAD_ID/send-payment" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "3f73310d-bfdd-4713-a664-305c08eda58b", "message": "Pronto, é só tocar para pagar."}'

Resposta

200Botão enviado

json

{
  "success": true,
  "message": {
    "id": 48231,
    "phone_number": "5511999990000",
    "message_type": "text",
    "params": { "body": "Pronto, é só tocar para pagar." },
    "status": "sent",
    "whatsapp_message_id": "wamid.HBgNNTUxMTk5OTk5MDAwMBUCABEYEjQ4",
    "created_at": "2026-10-11T13:11:20Z"
  }
}

Os campos da resposta são os mesmos de send-cart.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"invalid request body"}`
400	`order_id` vazio	`{"error":"order_id required"}`
401 / 403	Autenticação, módulo ou privilégio	veja Conversas
404	Conversa de outro seller ou inexistente	`{"error":"thread not found"}`
500	O pedido não é deste cliente	`{"error":"send-payment failed: whatsapp send-payment: pedido nao e deste cliente","message":null}`
500	Link indisponível (mini-loja sem endereço público)	`{"error":"send-payment failed: whatsapp send-payment: link indisponivel","message":null}`
502	A Meta recusou o botão; a mensagem foi gravada	`{"error":"send-payment failed: ...","message":{...}}`