Mensagens ricas

Quem usa

• A IA, sozinha, em todo chatbot com IA: mostra opções quando a pessoa precisa escolher e um botão de link quando a resposta é abrir uma página da base.
• As suas ações, no campo components do retorno (veja Ações).
• A API, no POST /v1/messages, junto de um texto.

Um componente por mensagem.

Formatos

buttons

De 1 a 3 botões, título até 20 caracteres.

{
  "type": "buttons",
  "buttons": [
    { "title": "Pedir calabresa", "action": { "name": "adicionar_ao_carrinho", "params": { "item": "101" } } },
    { "title": "Ver cardápio", "id": "ver_cardapio" }
  ]
}

list

De 1 a 10 itens: título até 24 caracteres e description opcional até 72. button (opcional, até 20) é o rótulo do botão que abre a lista no WhatsApp.

{
  "type": "list",
  "button": "Ver sabores",
  "items": [
    { "title": "Pizza Calabresa", "description": "R$ 49,90", "action": { "name": "adicionar_ao_carrinho", "params": { "item": "101" } } },
    { "title": "Pizza Marguerita", "description": "R$ 45,90", "action": { "name": "adicionar_ao_carrinho", "params": { "item": "102" } } },
    { "title": "Falar com a loja", "id": "falar_loja" }
  ]
}

link

Título até 20 caracteres e um endereço HTTPS (link de WhatsApp ou de DM não vale: a conversa já é por ali).

{ "type": "link", "title": "Ver pedido", "url": "https://seu-sistema.com/pedidos/1234" }

carousel

De 1 a 10 cards. Cada card tem image ou video (HTTPS), title (até 80) e/ou text (até 300), e os botões: buttons com 1 ou 2 de resposta, ou link com um botão de link ({title, url}). Todos os cards precisam ter o mesmo tipo e a mesma quantidade de botões: é regra do WhatsApp.

{
  "type": "carousel",
  "cards": [
    {
      "image": "https://seu-sistema.com/fotos/calabresa.jpg",
      "title": "Pizza Calabresa",
      "text": "R$ 49,90. Calabresa, cebola e azeitona.",
      "buttons": [{ "title": "Pedir este", "action": { "name": "adicionar_ao_carrinho", "params": { "item": "101" } } }]
    },
    {
      "image": "https://seu-sistema.com/fotos/marguerita.jpg",
      "title": "Pizza Marguerita",
      "text": "R$ 45,90. Tomate, muçarela e manjericão.",
      "buttons": [{ "title": "Pedir este", "action": { "name": "adicionar_ao_carrinho", "params": { "item": "102" } } }]
    }
  ]
}

Como fica em cada canal

• WhatsApp, carrossel: o texto do card leva o título no começo e é cortado em 160 caracteres (no fim de uma palavra), com até 2 quebras de linha.
• Instagram pelo computador: respostas rápidas e cards não aparecem no instagram.com. Por isso o resumo numerado das opções vai sempre numa mensagem própria, e a pessoa pode responder com o número.
• Site: só a última mensagem aceita toque, e o primeiro toque desativa os botões dela.

O que acontece no toque

• Botão com ação vale por 24 horas. Uso único só nas ações executa ou de pedido: assim o segundo toque em “adicionar” coloca a segunda pizza.
• A ação precisa existir no chatbot, estar ativa e receber parâmetros válidos para o schema dela.

WhatsApp e Instagram: o portão

• Opção, item ou card com produto proibido pela Meta sai.
• Com bebida alcoólica ou remédio, sai para quem não confirmou 18 anos, e entra o botão “Ver opções 18+” (no carrossel, numa mensagem logo depois).
• Pela API, o BoaVoz nunca edita: o envio é recusado com 422 prohibited_content, apontando o campo.

Pela API

No POST /v1/messages, components vai com "type": "text" e o texto até 1.024 caracteres. Formato fora das regras: 400 invalid_request, com o field do problema (por exemplo, components.cards[1].buttons).

curl https://boavoz.com/api/v1/messages \
  -H "Authorization: Bearer bv_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1d…" \
  -d '{
    "bot_id": "bot_…",
    "to": "phone:5511999990000",
    "type": "text",
    "text": "Quer receber o cardápio do dia?",
    "components": {
      "type": "buttons",
      "buttons": [{ "title": "Sim, quero", "id": "quero_cardapio" }, { "title": "Agora não", "id": "agora_nao" }]
    }
  }'