Subcontas: repasse o custo de IA aos seus clientes

Atualizado em 21/10/2026

Se você embute a IA da plataforma no seu produto, as Subcontas resolvem a conta do fim do mês: cada cliente seu vira uma subconta com créditos pré-pagos, chave de API própria e consumo isolado. Você define o preço e a margem; o seu cliente só vê créditos, nunca o seu custo. E quando o saldo zera, a IA pausa sozinha, sem surpresa de fatura para ninguém.

Como funciona o dinheiro

Pré-pago puro: o cliente recarrega antes de usar. O consumo de IA debita os créditos na hora, com a sua margem.
Sua margem, seu preço: com margem de 30%, um consumo que custa R$ 1,00 debita R$ 1,30 do cliente. A conversão também é sua: com 10.000 créditos por real, uma recarga de R$ 50 vira 500.000 créditos.
Zerou, pausou: sem créditos, a IA para de responder aquele cliente e o atendimento segue com humanos. A recarga reativa na hora. O saldo é conferido de verdade antes de cada resposta, com folga para uma resposta típica, então a subconta não fecha no negativo. E o aviso que a pessoa vê no chat deixa claro que a pausa não é culpa da pergunta dela, sem falar de dinheiro.
Você escolhe o que cobra, pelo que a resposta usou: Base de conhecimento (respostas montadas com os artigos e documentos) e Dados de APIs (respostas com números e registros consultados em sistemas). O que ficar de fora, você absorve como custo seu. Útil para dar as dúvidas de cortesia e cobrar só as consultas, por exemplo. Vale por onde a pergunta entrar (chat ou chave de API), e a consulta é cobrada a partir do momento em que a resposta consulta um sistema.

Ativando o recurso

Abra Inteligência › Agentes › aba Subcontas (disponível nos planos com o recurso). Um assistente de três etapas configura tudo — e, depois de ativo, o botão Configurações abre uma página própria, com um cartão por assunto (agentes, preço, cobrança, operação automática, webhook), cada um com o seu "Saiba mais" e uma prévia ao vivo do preço. A desativação fica no fim dessa página.

Preço e créditos: sua margem sobre o custo e quantos créditos vale R$ 1.
O que é cobrado: respostas pela base de conhecimento, respostas com dados de APIs, ou ambas. Atenção: com qualquer cobrança ligada, os agentes marcados só respondem conversas identificadas com uma subconta; visitantes sem identificação seguem para atendimento humano. Por isso, outro agente nunca passa para um agente marcado uma conversa sem identificação: ele passa para a equipe. No chat do site, o cliente é convidado a entrar na conta; no WhatsApp, onde não há como se identificar na conversa, ele só é avisado de que alguém da equipe vai continuar. Cliente sem saldo continua tirando dúvidas pela base quando ela é de cortesia; só a consulta a sistemas fica indisponível para ele até a recarga.
Agentes que participam: só o consumo dos agentes marcados é debitado dos seus clientes. Os demais consomem da sua conta, como sempre.

Ativação das Subcontas

Operação automática: cadastro sozinho e planos de créditos

Nas configurações, o cartão Operação automática reúne o que roda sem a sua mão:

Cadastro na primeira conversa identificada: ligado, a subconta é criada sozinha quando um cliente identificado (verificação assinada) conversa pela primeira vez — sem cadastro prévio e sem chamada de API. A criação é idempotente: a mesma referência nunca duplica.
Planos de créditos: um plano é um pacote com nome ("Básico", "Avançado") que define a franquia mensal da subconta — créditos que renovam todo mês e não acumulam, consumidos antes dos avulsos (que seguem sem vencimento). Aumentar um plano credita a diferença na hora para quem já está nele; reduzir vale a partir da próxima renovação (detalhe abaixo). Subconta sem plano continua funcionando exatamente como antes, só com recargas avulsas.

Excluir um plano ou desativar o recurso pede confirmação — e o nome de cada plano é único na sua conta.

Franquia mensal: o saldo que renova sozinho

A franquia é a cota de créditos que volta ao valor cheio todo mês, sozinha — o jeito de embutir a IA numa mensalidade, sem o seu cliente precisar recarregar nada. Ela convive com os créditos avulsos no mesmo saldo, e a ordem importa:

A franquia é gasta primeiro; os créditos avulsos só entram quando ela acaba.
A franquia não acumula: o que sobra no fim do mês não passa para o próximo.
Os créditos avulsos não expiram: ficam guardados até serem usados.

O saldo que o seu cliente vê é a soma dos dois, e a IA só pausa quando os dois zeram.

Onde definir

No detalhe da subconta, o cartão Franquia mensal tem três portas:

Plano da conta: a subconta acompanha um plano nomeado que você criou. Mudou o plano, mudam todos os clientes dele.
Valor próprio: um número só daquele cliente, fora dos planos.
Sem franquia: só créditos avulsos. É como toda subconta nasce.

Mudou de plano no meio do mês

Aumentar vale na hora. A diferença entra no saldo do mês imediatamente: quem estava num plano de 10.000, já gastou 4.000 e sobe para 30.000 fica com 26.000 na hora — a franquia nova menos o que já consumiu. Quem não tinha franquia nenhuma e ganha um plano recebe o valor cheio na hora.
Reduzir vale a partir da próxima renovação. Crédito já concedido nunca é retirado: o cliente termina o mês com o que tinha e só sente a mudança na virada. Vale também para tirar o plano da subconta ou excluir o plano.

Ao aumentar um plano, todos os clientes dele recebem a diferença de uma vez — menos os que têm valor próprio, que não seguem o plano. Se a subconta estava pausada por falta de créditos, o aumento reativa o atendimento na hora, como faria uma recarga. Cada renovação e cada aumento aparecem nos últimos lançamentos da subconta, para o seu cliente entender de onde veio o saldo.

Criando e gerenciando subcontas

Clique em Nova subconta: informe o nome do cliente, a referência externa (o ID dele no seu sistema, que torna a criação idempotente pela API) e os créditos iniciais.

Achar o cliente pela pessoa que falou

Você lê uma conversa em Atendimento › Chamados, vê o nome e o e-mail de quem falou — e o que você precisa é o cliente de quem é aquela conversa, que costuma ter outro nome. A busca da aba procura pelos dois lados: o cliente (nome e referência externa) e as pessoas dentro dele (nome, e-mail e o user_ref da identificação). Quando o resultado vem por uma pessoa, a linha mostra quem foi — "Maria Souza · maria@…" —, para você saber por que aquele cliente apareceu.

Quem conversa identificado passa a existir no cartão Usuários da subconta, mesmo sem ter consumido nada ainda. Pelo modo simples do chat entra só o user_ref: nome e e-mail continuam vindo apenas da verificação assinada, que é o que impede um visitante de rebatizar a pessoa de outro cliente. Quem já tinha conversado antes também está lá, pela referência.

O nome se mantém sozinho

O nome que aparece aqui é o do cadastro do seu sistema, e ele se atualiza sem você fazer nada: mande o nome da empresa no campo subaccount_name da identificação assinada e, na próxima conversa identificada dela, o nome muda aqui também. Isso evita o caso chato de a cobrança do fim do mês listar um nome que não existe mais — ou, quando a subconta nasceu sozinha sem receber um nome, ficar com a referência crua no lugar dele.

Atenção ao campo certo. A subconta é a empresa, então quem a nomeia é o subaccount_name. O name do mesmo payload é de quem está conversando: se a empresa tem dois usuários, usar esse campo faria o nome da subconta trocar conforme quem falou por último.
Só vale a identificação assinada. O nome que o visitante digita no chat nunca renomeia nada; só o que o servidor do seu sistema assina. Sem isso, qualquer pessoa poderia renomear o cliente de outra.
Quer um nome diferente do seu cadastro? Clique no lápis ao lado do nome, no detalhe da subconta. O nome escrito à mão fica fixo e nenhuma conversa o desfaz — a linha abaixo da referência avisa que ele está definido ali, e o link Voltar a seguir o cadastro devolve o automático quando você quiser.
Renomear não mexe em mais nada. Saldo, chave de API, referência externa e histórico seguem iguais: muda só o nome que você lê nas telas e no extrato.

No detalhe de cada subconta você encontra:

Saldo e créditos: o saldo atual, o botão Adicionar créditos (recarga reativa bloqueio na hora) e Suspender. Para encerrar a cobrança de um cliente, suspenda. Nunca há exclusão: o histórico fica.
Chave de API: gerada no detalhe e exibida uma única vez. Ela só opera a própria subconta, é a chave que vai embutida no seu produto. Rotacionar invalida a anterior na hora.
Identificação no chat e WhatsApp: snippets prontos para colar (abaixo).
Últimos lançamentos: recargas e débitos, com o usuário final quando identificado.

O topo da aba resume o mês: consumo dos clientes, seu custo e o lucro da diferença.

Detalhe de uma subconta

Identificando o cliente no chat

Para saber de quem é o consumo, o widget precisa saber qual cliente está falando. Dois modos:

Token simples: cole o token da subconta (ct_live_…) no snippet do widget, no sistema do seu cliente. Zero código de servidor.
Verificação assinada (recomendada): o servidor do seu sistema assina a identidade com o segredo do canal, incluindo no payload o campo subaccount_ref — a referência externa da subconta, a mesma que você usou ao criá-la. É ele que amarra a conversa ao cliente certo (não confunda com o company_ref, que organiza o seu cadastro de clientes). Mande junto o subaccount_name, com a razão social, para o nome se manter sozinho, e o user_ref para saber quem, dentro daquele cliente, consumiu. É inviolável, e você pode exigir a assinatura na subconta: aí o token simples passa a ser recusado. Todos os campos do payload estão em Verificação de identidade — e o segredo que assina fica a um clique do próprio snippet, em Pegar o segredo e ver o passo a passo, dentro do cartão "Identificação no chat" da subconta.

Sem identificação, a conversa funciona normalmente; o consumo só não é atribuído a nenhuma subconta (fica por sua conta), ou vai para atendimento humano se houver cobrança ligada. E se quiser transparência total, ligue Mostrar saldo no chat: o cliente identificado vê os créditos dele no menu do widget, com aviso de saldo baixo.

Testando antes de publicar

Na prévia do chat (Administração › Configurações › Canais › Chat), o card Teste como tem a seção Subcontas: escolha de qual cliente é o teste, buscando pelo nome ou pela referência externa. A tela diz na hora se a referência casa com alguém — e, quando não casa, avisa que a conversa ficaria sem vínculo, que é exatamente o que acontece no site quando o seu sistema manda uma referência errada.

Dois avisos que valem o tempo que economizam:

Marcar "testar como verificado" não substitui isso. Identidade assinada prova quem é a pessoa; a subconta diz de quem ela é cliente. O agente que exige identificação espera a segunda.
Referência inexistente é aceita de propósito, para você poder ver o caminho do bloqueio: o agente não responde, a conversa vai para a fila e o motivo aparece na própria prévia.

WhatsApp identificado

O mesmo vale para o WhatsApp: seu sistema emite um QR de pareamento (válido por 15 minutos), o cliente escaneia e envia a mensagem, e o telefone fica vinculado à subconta. Todo consumo daquele número passa a debitar os créditos dele. O vínculo pode ser revogado a qualquer momento, e um novo pareamento do mesmo telefone substitui o anterior.

API, webhooks e automação

Duas chaves, dois papéis: qualquer chave de gestão sua (Administração › Configurações › Tokens) administra todas as subcontas; a chave da subconta só consome IA em nome daquele cliente. Os principais endpoints:

Criar (POST /subaccounts): idempotente pela referência externa; repetir devolve a existente — e, se o nome vier diferente, renomeia. É assim que você troca o nome sem guardar o id daqui.
Saldo (GET /subaccounts/{id}/balance): o "meu saldo" que você exibe dentro do seu produto.
Recarregar (POST /subaccounts/{id}/credits): idempotente pela referência do seu pagamento; retry não credita duas vezes.
Consumo (GET /subaccounts/{id}/usage): débitos por dia e por usuário final no mês. Cada pessoa vem com debited_credits e limit_credits (o teto dela, ou null).
Limite por usuário (GET/PUT /subaccounts/{id}/user-limits): teto mensal de créditos de cada pessoa dentro do cliente, pelo mesmo user_ref da identificação. O PUT recebe { "limits": [ { "user_ref": "45", "monthly_credits": 5000 } ] } e substitui o conjunto inteiro; null remove o teto e 0 bloqueia.
Planos de créditos (GET/POST/PATCH/DELETE /subaccount-plans): o catálogo de franquias, para espelhar os planos do seu sistema. Na subconta, mande plan_id (acompanha o plano) ou monthly_credits (valor próprio) — os dois se excluem, e nenhum dos dois significa "sem franquia".
Webhooks assinados: criação da subconta, saldo baixo, bloqueio e o fim de cada execução pedida pelo seu sistema (concluída ou com erro). Chegam com a assinatura no cabeçalho X-Desk-Signature, para o seu sistema conferir que veio mesmo daqui. A URL e o segredo ficam nas configurações de Subcontas: o segredo aparece inteiro uma única vez, ao gerar (botão Gerar segredo no cartão "Avisos ao seu sistema", ou POST /subaccounts-config/webhook-secret/rotate); depois só o final fica visível. Perdeu? Gere outro e atualize o seu sistema, o anterior deixa de valer na hora.

Prefere não escrever código? Conecte o seu assistente de IA à sua conta via MCP e gerencie por comando: "crie uma subconta para o cliente X com 50 mil créditos". A documentação completa está no botão API da própria aba.

Bom saber

O toggle do agente: além da ativação geral, cada agente tem o interruptor "Usar Subcontas" (em Avançado). Ele aparece quando o agente tem uma API conectada com autenticação pelo token do visitante.
Ações em conversas de subconta: elas rodam, mas só em consulta, só com identidade assinada e só quando a credencial é do próprio usuário (ou a identidade vai assinada para a sua API). Escrita e credencial fixa ficam de fora — é o que impede o cliente final de alcançar as integrações da sua conta, ou de ler os dados do vizinho. A regra completa está em APIs: conecte a IA aos seus sistemas.
Consumo por usuário final: envie o user_ref na identificação e os lançamentos mostram quem, dentro do cliente, consumiu — e a busca da lista passa a achar o cliente pelo nome ou pelo e-mail dessa pessoa.
Teto por pessoa: no detalhe da subconta, o cartão Usuários lista quem usou a IA no mês, com "usado / limite", e é ali (ou pela API acima) que você define o teto de cada um. Sem teto, vale só o saldo da subconta. Quem atinge o teto vê "Você atingiu o limite de uso de IA deste mês. Fale com o administrador da sua conta." e os demais seguem normalmente; o mês vira e o contador zera. A soma considera tudo o que a pessoa debitou (franquia e avulsos, sem distinção); o que a conta absorve como grátis não conta. Pelo modo simples do chat o user_ref vai em claro, então para o teto valer de verdade use a verificação assinada.

Limites e regras

Bloqueio por saldo não se desfaz na mão: subconta bloqueada volta a atender com recarga, e só. A suspensão manual é outra coisa — essa você liga e desliga quando quiser.
No chat, saldo zerado transfere para humano quando tudo é cobrado: o agente para de responder e a conversa entra na fila, com o aviso padrão de espera. Se a base de conhecimento é de cortesia, o agente continua respondendo por ela; só a consulta a sistemas fica indisponível, e ele diz isso ao cliente. O texto desses avisos não é personalizável hoje.
Pela API, saldo zerado devolve 402 com o motivo (bloqueada, sem créditos ou subaccount_user_limit_reached quando é o teto da pessoa), antes de qualquer processamento — e você recebe um aviso no sino, uma vez por dia, para não descobrir pelo cliente reclamando.
Criar é idempotente: repetir o mesmo POST com a mesma referência externa devolve a subconta existente, sem alterar créditos nem margem. Criação nova responde 201; a repetição responde 200. O nome é a exceção deliberada: reenviar o cadastro com um nome novo renomeia a subconta (a resposta diz renamed), porque reenviar o cadastro sempre significou "este é o cadastro atual".
Margem: vale a regra de cobrança mais específica; sem ela, a margem da subconta; sem ela, a da conta. A conversão entre créditos e reais é uma só, definida na conta.
A cortesia é pelo que a resposta usou, não por onde entrou: com "Base de conhecimento" desligado e "Dados de APIs" ligado, a dúvida respondida pela base fica por sua conta e a resposta que consultou os seus sistemas debita o cliente, seja no chat ou numa execução pedida pelo seu sistema. A cobrança começa na consulta: o que o agente gastou antes de decidir consultar é conteúdo.
Suspender pela API: PATCH /subaccounts/{id} com status em suspended (e active para voltar). O mesmo endpoint aceita name, margin_pct, low_balance_threshold_credits, require_signed_identify e client_id. Mandar name por aqui fixa o nome, como o lápis da tela: as conversas param de atualizá-lo até você mandar name_locked: false.
Sem limite de ritmo na gestão: criar subconta, recarregar e consultar saldo não têm teto por minuto — a rotina mensal de recarga roda à vontade. O limite existe nas execuções pedidas pelo seu sistema: 120 por minuto por subconta, 1.200 por conta.
Franquia sobe na hora, desce na virada: aumentar credita a diferença no mês corrente; reduzir só vale na próxima renovação, e nada do que já foi concedido é retirado. Não há rateio por dias.
O histórico nunca recalcula: mudar plano, margem ou conversão não mexe em lançamento já feito.
Sem teto de subcontas. Milhares de clientes cabem; o que existe é limite de ritmo nas execuções pedidas pelo seu sistema.

O extrato da subconta

O extrato fala a língua de quem paga a conta: cada resposta da IA aparece como uma linha ("Resposta do assistente com a base no chat", "Resposta do assistente com dados de sistemas pela API"), com o total daquela resposta e o saldo depois dela. Antes, a mesma resposta aparecia em várias linhas no mesmo minuto. Com a revisão da resposta ligada no agente, a conferência aparece como outra linha, "Revisão da resposta".