Quando a janela da sessão fecha?

Se o cliente não tiver escrito ou respondido dentro de 24 horas, sendMessage falhará até que um template reabra o chat.

Como faço para verificar a entrega?

sent: true apenas confirma a aceitação. Acompanhe a entrega via webhook hooks[] ou por polling.

E se a mensagem não for entregue?

Registre o hook falhado/undelivered, verifique a janela de sessão e, em seguida, tente novamente ou utilize um template.

Posso conectar isso ao meu CRM ou backend?

Sim — acione a chamada da API a partir do seu webhook de entrada ou do mecanismo de workflow.

WhatsApp Business API para catálogo de produtos interativo

Este cenário envia uma lista interativa com sendList durante a janela de sessão de 24 horas.

Experimente a demonstração Ver exemplo de código

Visão geral do caso de uso

Este cenário envia uma lista interativa com sendList durante a janela de sessão de 24 horas. Duas seções agrupam linhas de produtos; o cliente abre o catálogo e seleciona um item.

Exemplo de modelo

Navegue pelo nosso catálogo para{{1}}:

{{1}}
contexto da campanha ou do produto mostrado no texto do cabeçalho da lista

WhatsApp Business API for product catalog — interactive list

Quando usá-lo

Acesse este cenário quando uma campanha de vendas pelo WhatsApp já tiver uma sessão aberta e o comprador precisar escolher um SKU sem que um agente cole longas listas de produtos. Isso se adequa a equipes que estão realizando envios promocionais, onde um catálogo estruturado é melhor do que texto livre e a entrada manual de SKU poderia atrasar o checkout.

Menos abandono de compradores na conversa

sendList substitui as colagens de SKU por duas seções agrupadas e um botão de Ver catálogo, permitindo que o comprador selecione dentro do WhatsApp em vez de abandonar uma lista de texto difícil de ler no mobile.

Nenhuma entrada manual de SKU

O cliente toca em uma linha de produto na lista interativa e seu webhook de entrada recebe o id da linha, assim os agentes e os sistemas de backend evitam retrabalhar na digitação de SKUs a partir do chat.

Contexto da campanha em uma variável

Uma variável de corpo carrega o rótulo da campanha ou promoção no texto do cabeçalho da lista, assim o mesmo layout de lista funciona para diferentes ofertas sem a necessidade de reescrever o corpo da mensagem.

O checkout continua a partir da seleção

O webhook passa o ID da linha do produto para o seu CRM ou loja virtual, que continua o fluxo do pedido ou o follow-up a partir daquele SKU, em vez de pedir ao comprador para repetir sua escolha.

Fluxo de Trabalho

Atos do cliente
Um evento de campanha ou resposta do cliente mantém a sessão aberta.
user action
Evento de captura
Seu backend constrói uma lista interativa em duas seções com linhas de produtos.
POST /send_list
Taps Ver catálogo
O cliente clica em Ver catálogo e seleciona um produto.
user action
Entregue
O webhook retorna o id da linha para processamento de pedidos ou CRM.
delivered

Implementação técnica

Pré-requisitos

1MSG API Key · Como obter a chave da API
Conta comercial do WhatsApp · Como Conectar a WABA
Janela de sessão aberta 24 horas · Como funciona a janela de 24 horas
Opt-in do cliente · Como Gerenciar o Consentimento dos Clientes
Ponto de extremidade do Webhook · Como Configurar Webhooks

Exemplos de código

#!/usr/bin/env bash
set -euo pipefail

# === Configuration (replace "___" placeholders) ===
API_BASE_URL="https://api.1msg.io"        # production 1MSG API base URL
CHANNEL_ID="___"                           # channel ID from 1MSG dashboard
API_TOKEN="___"                            # channel JWT token (Bearer)



# === Test data ===
TEST_PHONE="___"                 # client phone in international format
TEST_PRODUCTCONTEXT="___"         # {{1}} product context

PHONE_NORM="$(printf '%s' "$TEST_PHONE" | tr -cd '0-9')"
URL="${API_BASE_URL%/}/${CHANNEL_ID}/sendList"

read -r -d '' PAYLOAD <<JSON || true
{
  "phone": "${PHONE_NORM}",
  "body": "Browse our catalog for spring promotion:",
  "buttonText": "View catalog",
  "action": "catalog",
  "sections": [{"title":"Featured products","rows":[{"id":"prod_alpha","title":"Alpha Widget","description":"Compact model"},{"id":"prod_beta","title":"Beta Widget","description":"Standard model"}]},{"title":"Bundles","rows":[{"id":"bundle_starter","title":"Starter pack","description":"Two items included"},{"id":"bundle_pro","title":"Pro pack","description":"Four items included"}]}]
}
JSON

RESPONSE="$(curl -s -w '\n%{http_code}' -X POST "$URL" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -d "$PAYLOAD")"

HTTP_CODE="$(printf '%s' "$RESPONSE" | tail -n1)"
BODY="$(printf '%s' "$RESPONSE" | sed '$d')"

case "$BODY" in
  *'"sent":true'*) ok=1 ;;
  *) ok=0 ;;
esac

if [ "$HTTP_CODE" -ge 200 ] && [ "$HTTP_CODE" -lt 300 ] && [ "$ok" -eq 1 ]; then
  echo "Message sent to client."
else
  echo "$BODY" >&2
  exit 1
fi

Status de resposta e entrega

HTTP 2xx e JSON"sent": truemean 1MSGaceitomensagem para envio — não que já tenha chegado ao telefone do cliente.idcampowamid.…) para correlacionar os callbacks de entrega.

200 OKResposta

{
  "sent": true,
  "id": "wamid.HBgLMzgwNjM5...",
  "message": "Message accepted for delivery"
}

sent
Aprovado para envio.nãoainda no telefone do cliente
id
Armazenar; retornos de entrega.hookInfosão focados nisso

A entrega em si chega mais tarde, como um retorno separado. Registre um webhookPOST …/webhook) e 1MSG POSTs atualizações de status para seu endpoint HTTPS em um nível superiorhooks[]carga.

200 OKWebhook de status de entrega — payload recebido

{
  "hooks": [
    {
      "id": "gBGGeSaGViBfAgnlzOSHEwK9O6F",
      "type": "message",
      "status": "sent",
      "timestamp": "1654864094",
      "recipient_id": "556123122026"
    }
  ]
}

status
sent, delivered, read— ou um status de falha quando aplicável
id
Correla a chamada com a revisão.idretornado pela chamada de envio
timestamp
Segundos Unix, como uma string

Se você não quer receber retornos de telefonema, escolha não optar por isso.GET {base}/{channel}/hookInfo?messageId=<id>em vez disso. Na prática, a entrega geralmente é concluída em segundos — mas o contrato da API não garante isso, então nunca bloqueie um fluxo esperando por isso.

Erros comuns

Status	Resposta	Causa
200	Message was not sent: empty body	No body in the request.
200	Message was not sent: provide chatId, phone, bsuid, or username	No recipient the channel could resolve.
200	wrong file	The media could not be fetched or uploaded — not a reachable URL, not valid base64.
403	access denied	The token is wrong, or belongs to a different channel than the URL.
200	Message was not sent: filename	sendFile called without a filename, so the media has no extension to send.