Guia para plataformas

1. Os pacotes e a chave

1. Assine em Cobrança os pacotes Integrações (a API) e Plataforma (o modelo e as lojas pela API).
2. Em Integrações → Chaves de API, crie uma chave com escopo de toda a conta e as permissões provisioning e sources. Marque members só se o seu sistema for convidar a equipe das lojas para o portal, e billing só se ele for escolher o tamanho de cada chatbot (subir cobra no cartão da assinatura).

2. O modelo

No painel, em Modelos, monte o que todas as lojas têm em comum: a personalidade, as instruções, os assuntos do negócio, as ações (por exemplo buscar_cardapio e criar_pedido, que recebem o loja_id do contexto), os roteiros e a base comum. Na aba Herança, escolha o que cada loja pode mudar (o nome do assistente, a saudação, a aparência, instruções extras) e copie o id do modelo para a API. Publique: cada publicação vira uma versão, e dá para voltar a uma anterior.

3. Uma loja nova, pelo seu sistema

Quando um restaurante entra na sua plataforma, o seu sistema cria o cliente e o chatbot dele:

curl -X POST "https://boavoz.com/api/v1/clients" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{
  "name": "Pizzaria do Zé",
  "external_id": "loja-42",
  "site": "pizzariadoze.com.br"
}'

{
  "client_id": "cli_5b2c8e1a-7d3f-4a6b-9c8e-1f2a3b4c5d6e",
  "external_id": "loja-42",
  "name": "Pizzaria do Zé",
  "compliance_status": "active"
}

curl -X POST "https://boavoz.com/api/v1/bots" \
  -H "Authorization: Bearer $BOAVOZ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
  -d '{
  "client_id": "cli_5b2c8e1a-7d3f-4a6b-9c8e-1f2a3b4c5d6e",
  "template_id": "bot_9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "external_id": "loja-42-site",
  "context": {
    "loja_id": "42"
  },
  "display": {
    "nome": "Pizzaria do Zé, Centro",
    "horario": "terça a domingo, das 18h às 23h",
    "endereco": "Rua das Flores, 120"
  }
}'

{
  "bot_id": "bot_2e4f6a8c-1b3d-4e5f-9a7b-8c9d0e1f2a3b",
  "widget_key": "5f0c2a9e7b1d3c4e6a8b0d2f",
  "client_id": "cli_5b2c8e1a-7d3f-4a6b-9c8e-1f2a3b4c5d6e",
  "external_id": "loja-42-site",
  "template_id": "bot_9d8c7b6a-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
  "name": "Duda",
  "status": "live",
  "context": {
    "loja_id": "42"
  },
  "display": {
    "nome": "Pizzaria do Zé, Centro",
    "horario": "terça a domingo, das 18h às 23h",
    "endereco": "Rua das Flores, 120"
  },
  "size_change": null
}

O context (o id da loja) vai em toda chamada de ação e escolhe as fontes da loja; o display (nome, horário, endereço) é o que a IA sabe dela. O external_id deixa repetir com segurança: o mesmo id devolve o que já existe. O widget_key vai no código do chat do site da loja.

4. WhatsApp e Instagram de cada loja

Peça o link de conexão e mostre no painel da loja ("Conectar WhatsApp"). Quem abre é o dono do restaurante, com a conta dele na Meta: o número continua dele, e ele paga a Meta direto. Antes de conectar, a loja faz o aceite (inclusive de que as conversas dela vão para a sua plataforma). O canal pede um tamanho no chatbot (Cobrança, ou size com a permissão billing).

5. A equipe da loja

A equipe do restaurante atende pelo portal do cliente, com a marca da sua conta: vê só as conversas da loja dela e assume quando a IA chama alguém. Convide pelo painel (página do cliente) ou pela API, com a permissão members (equipe do portal).

6. Eventos, pausa e uso

• Webhooks: pedido de atendente, lead, mensagens, canal conectado ou caído e conformidade chegam no seu sistema, com o external_id do cliente no envelope (Webhooks).
• Pausa: loja fechada, contrato suspenso ou inadimplência com a sua plataforma: pause o chatbot (os canais seguem conectados; a equipe responde pelo portal) e retome depois.
• Uso: GET /v1/usage dá os atendimentos, as mensagens, os contatos em campanhas e o custo estimado da Meta por loja, para você cobrar o restaurante como quiser. O BoaVoz nunca cobra o restaurante.
• Saída de uma loja: pause ou desconecte o canal pela API; os dados dela só servem a ela, e a exclusão é no painel. Se o restaurante quiser levar a loja para outra conta do BoaVoz, ele pede ao suporte.