Revenda: o agente dentro do seu produto

Este guia é para parceiros de revenda: empresas que oferecem os agentes Lab019 dentro do próprio produto — cada cliente seu ganha um agente de atendimento, e você controla a experiência, o preço e o relacionamento.

Um exemplo típico: uma plataforma de agendamento que vende "atendente virtual" como adicional. Cada estabelecimento cliente recebe um agente que responde no site e no aplicativo da plataforma; o parceiro embute a conversa na interface que já tem.

O modelo: uma organização por cliente final

Cada cliente seu vive numa organização própria na plataforma. Isso não é burocracia — é o que garante o isolamento:

• Conversas e histórico de um cliente nunca se misturam com os de outro.
• Configuração independente: cada agente tem sua persona, suas ferramentas e seus limites, sem interferência entre clientes.
• Consumo medido por organização: créditos, limites diários e relatórios são por cliente — você enxerga exatamente quanto cada um usa.

As organizações dos seus clientes são criadas junto com o nosso time durante o onboarding da parceria, assim como as condições comerciais de revenda.

Duas formas de integrar

Para cada cliente, você escolhe (ou combina) duas portas de entrada:

	Widget	API pública
Esforço	Uma linha de HTML	Integração de backend
Interface	Janela de chat pronta, com a sua cor e título	100% sua
Onde roda	No site do cliente final (ou no seu)	No seu backend
Credencial	Chave wgt_… (pública, presa às origens)	Chave pak_… (segredo, no seu cofre)
Bom para	Colocar no ar rápido, site do cliente	Embutir no seu app, automações, omnichannel

Na prática de revenda, o widget resolve a maioria dos casos: você gera o snippet do cliente e ele (ou você) cola no site. A API pública entra quando a conversa precisa acontecer dentro do seu produto — aí o seu backend fala com o agente e a sua interface exibe a resposta.

Roteiro por cliente final

1. Organização criada (onboarding da parceria) — uma por cliente.
2. Configure o especialista: persona, ferramentas e teto de custo — veja Configuração do especialista. Se os seus clientes seguem um padrão, mantenha um modelo de configuração e replique.
3. Marque o agente como público para atender visitantes sem login — Agente público.
4. Crie a credencial:
   • Widget: chave com as origens do site do cliente e o orçamento diário — criando a chave.
   • API: chave pak_… guardada no seu cofre, nunca no front-end — criando a chave.
5. Integre e teste: cole o snippet ou aponte o seu backend, mande uma mensagem, veja a resposta chegar.
6. Abra ao público só depois de restringir origens e conferir limites.

Todas as operações do roteiro existem também como API — criação de chaves de widget e de API pública — para você automatizar o provisionamento no seu fluxo de vendas.

Identificando os usuários dos seus clientes

Na API pública, quem identifica o interlocutor é o external_user_id — um id do seu sistema, estável por usuário final. Como cada cliente seu vive na própria organização, os ids não colidem entre clientes; basta que sejam estáveis dentro de cada um.

Use o id que o seu sistema já tem (id de cadastro, telefone normalizado, um hash). Id novo a cada chamada = conversa nova a cada chamada — evite.

Duas chaves na mesma organização

Quem identifica a conversa é a organização + external_user_id — não a chave. Duas chaves pak_… na mesma organização (por exemplo, testes e produção) com o mesmo external_user_id caem na mesma conversa. Se você mantém ambientes na organização de um cliente, diferencie os ids (ex.: prefixo teste-).

Recebendo eventos no seu backend

Duas vias, que se complementam:

• Stream de eventos (SSE) — a resposta do agente em tempo real, pedaço a pedaço. É a via principal e confiável, com retomada por Last-Event-ID — veja o stream.
• Webhook de callback — os eventos de atendimento humano também são enviados a uma URL sua, útil quando o seu backend não mantém o stream aberto — veja webhook.

Custos e limites

Você revende um serviço medido — os controles existem para o consumo de um cliente final nunca virar surpresa:

• Créditos por organização: cada cliente consome dos próprios créditos, e você acompanha por organização.
• Orçamento diário do widget (por chave) — teto de consumo dos visitantes por dia.
• Teto de custo por conversa na configuração do especialista (referência).
• Limites de taxa da API: 120 requisições por minuto por chave — dimensione o seu backend para isso e trate 429 com espera e repetição.
• Limites por visitante do agente público, contra abuso anônimo.

Boas práticas antes do go-live

• Chaves pak_… no cofre de segredos do seu backend; nunca no front-end nem no repositório.
• Origens do widget explícitas (sem *) em produção.
• Um x-idempotency-key novo por mensagem; o mesmo só em retentativa.
• Guarde o último id do stream e retome com Last-Event-ID ao reconectar.
• Rotacione as chaves pak_… periodicamente — a rotação tem carência, sem downtime.
• Combine com o nosso time os limites de custo de cada organização antes de ativar um cliente novo.