Perguntas Frequentes

Para acessar a plataforma, siga as etapas abaixo:

1. Na página inicial, localize e clique no botão 'Entrar'. Este botão está no canto superior direito da tela.

2. Após clicar, será exibida uma tela solicitando seu e-mail e sua senha.

3. Insira seu e-mail cadastrado e sua senha nos campos indicados.

4. Em seguida, clique novamente no botão 'Entrar'.

Você será então redirecionado para a área de testes do seu último agente. Caso ainda não possua nenhum agente criado, a plataforma o levará para a página de criação de agentes.

Para criar seu primeiro agente de IA, siga este procedimento:

1. Na página inicial, observe a caixa de texto principal. Nela, digite a solicitação do que você deseja que o agente automatize. Um exemplo pode ser: 'crie um agente para analisar atestados'. Você pode incluir regras e detalhes específicos nesta descrição inicial.

2. Depois de descrever a função do agente, clique no botão 'Criar agente'.

3. A plataforma apresentará opções para você selecionar o time ao qual o agente pertencerá e para definir um nome para o projeto. Faça essas escolhas e clique em 'Continuar'.

4. Em seguida, valide as regras que a plataforma sugeriu com base na sua descrição. Se estiverem corretas, clique em 'Iniciar Desenvolvimento'.

Com isso, seu agente estará criado e pronto para as próximas etapas de configuração e uso.

Aprenda a iniciar a criação de um novo agente já integrado a sistemas externos. Ao fornecer a documentação da API durante a fase de Discovery, a assistente Esther estrutura o fluxo automaticamente considerando os endpoints e dados necessários.

Passo a passo:

1 - Inicie o Discovery: Comece descrevendo brevemente o fluxo ou o agente que você deseja criar. Isso abrirá automaticamente a sala de Discovery.

2 - Acesse a Conexão de APIs: Dentro da sala de Discovery, localize e clique no botão "Conectar APIs", situado no canto inferior esquerdo da tela.

3 - Selecione a Fonte da API: Você terá duas opções:

- Escolher uma API pronta (já disponível na lista da plataforma).

- Inserir a documentação da API específica que você deseja conectar (copiando e colando o texto técnico ou JSON).

4 - Criação Assistida pela Esther: Após inserir a documentação, uma nova conversa será iniciada com a Esther. Ela irá fazer algumas perguntas e montar o fluxo de agente, para posteriormente processar as informações técnicas e criar o fluxo de agentes já com a integração configurada.

Para gerenciar seus agentes, ou seja, editá-los ou excluí-los, siga as instruções:

1. Na área de testes do agente, observe a barra de navegação superior ou lateral. Você encontrará um ícone de lápis, que indica a função 'editar'. Clique neste ícone, localizado próximo ao menu de seleção de agentes.

2. Ao clicar em 'editar', você poderá alterar o nome do agente ou inseri-lo em subgrupos, conforme necessário.

3. Para excluir um agente, clique no ícone de lixeira, que também estará visível nessa mesma área de gerenciamento.

4. Após clicar no ícone de lixeira, uma caixa de confirmação será exibida. É necessário confirmar sua intenção de excluir o agente nesta etapa.

Não, a exclusão de um agente é uma ação irreversível.

Uma vez que a exclusão é confirmada, não há como recuperar o agente. É importante ter certeza de que você realmente deseja remover o agente antes de prosseguir com a confirmação da exclusão.

Para alternar entre os agentes que você já criou, utilize o menu de seleção:

1. Na área de testes da plataforma, localize o menu de seleção (também conhecido como dropdown).

2. Este menu está localizado no topo da página e exibe uma lista de todos os agentes que você tem disponíveis.

3. Basta clicar e selecionar o nome do agente para o qual você deseja alternar. A plataforma carregará automaticamente a área de testes correspondente ao agente escolhido.

Na área de **Testes** de um agente conversacional:

1. Clique em **Ferramentas do Agente**
2. Selecione o card **Conectar Fluxos e Ferramentas**
3. Selecione o **fluxo de origem**

A partir daí, você tem dois caminhos:

**Opção 1 - Automático:**
- Deixe a plataforma definir o nome da ferramenta automaticamente a partir do fluxo
- O sistema insere o trecho necessário no prompt automaticamente

**Opção 2 - Manual:**
- Insira um nome customizado para a ferramenta
- Adicione as instruções no prompt manualmente na localização de sua escolha

---

**Enviar resultado em link:**

Você também pode escolher se quer enviar o resultado em um link - sendo possível gerar links para **documentos** e **planilhas**.

Ao selecionar uma dessas opções, a plataforma já cria automaticamente a configuração para gerar o link e produzir a resposta
personalizada a partir dele.

As instruções (ou prompt) que definem o comportamento de um agente podem ser visualizadas e alteradas na seguinte seção:

1. Dentro da área de testes de um agente específico, procure e clique na aba intitulada 'Instruções'.

2. Nesta aba, você encontrará o prompt completo que governa as ações do agente.

3. Para realizar modificações, clique no botão 'Editar'. Após fazer as alterações desejadas, lembre-se de salvar para que as novas instruções sejam aplicadas.

Sim, é possível restaurar uma versão anterior de um agente. Siga os passos:

1. Na aba 'Instruções' de um agente, localize e clique no ícone de relógio. Este ícone representa o histórico de versionamento do agente.

2. Ao clicar, será exibido um histórico com todas as versões anteriores do agente.

3. Você pode visualizar cada versão para identificar o estado desejado.

4. Para reverter o agente a uma versão específica, clique no botão 'Restaurar' ao lado da versão escolhida. Isso é útil caso uma alteração recente não tenha produzido o comportamento esperado.

É importante compreender a distinção entre a área de testes e a área de ajustes para o uso correto da plataforma:

* A área de testes é onde se encontra a caixa de texto principal no centro da tela, identificada como 'Digite aqui seu input'. Esta área é destinada ao envio dos dados reais que o agente deve processar, sejam eles áudios, textos ou imagens.

* A área de ajustes é a área de chat localizada na lateral direita da tela. Esta área é para interagir com o agente e solicitar modificações em seu comportamento ou regras, como por exemplo: 'Insira uma nova regra para...'.

Não utilize a área de ajustes para enviar os dados de trabalho que o agente deve processar; para isso, use sempre a caixa de texto principal na área de testes.

Para testar um agente conversacional, clique no ícone de robô chamado "Área de Testes" e
selecione o nome do agente específico no menu superior direito. Na área de testes de agentes
conversacionais, você pode enviar mensagens de texto, áudios, imagens e documentos PDF. Cada conversa
completa fica salva e pode ser avaliada em conjunto. Se você desejar avaliar conversas separadamente,
utilize o botão "Reiniciar" sempre que quiser iniciar uma conversa do zero. Isso mantém suas conversas
separadas e organizadas no histórico de testes.

Para testar um agente analítico, clique no ícone de robô chamado "Área de Testes" e
selecione o nome do agente específico que você deseja testar no menu superior direito. Na aba "Enviar",
você pode enviar diversos tipos de input: documentos em PDF, imagens, áudios, texto livre no campo de
mensagem, ou planilhas com dados estruturados. Caso você envie algum documento, imagem ou áudio, haverá um
tempo de processamento inicial enquanto o agente faz a leitura do conteúdo. Após finalizar a extração da
informação, o campo de texto livre será automaticamente preenchido com o conteúdo extraído do material
enviado. Clique no ícone "Enviar Mensagem" para dar início ao trabalho de análise do agente.

Na lateral direita da Área de Testes, você encontrará o histórico de execuções com cada envio
registrado. Quando o agente concluir a análise, aparecerá o link "Ver Resultados" e um ícone de
Download. Você pode fazer download em diversos formatos: xlsx, docx, txt, html, de acordo com o tipo de
resposta do agente. Ao clicar em "Ver Resultados", você será direcionado para a aba Resultados, onde
verá o material inicial enviado na coluna esquerda e a resposta produzida pelo agente na coluna direita.
Para materiais visuais como slides, haverá a opção "Abrir em Nova Aba" para visualização ampliada.

Na Área de Testes, é possível avaliar cada resposta produzida pelo agente. O feedback é
fundamental para o treinamento e melhoria do desempenho do agente. Na aba "Resultados", você deve
avaliar a resposta do agente:

* Aprovar: Se não houver considerações negativas, clique em "Aprovar"
para que a métrica seja computada automaticamente.

* Reprovar: Se clicar em "Reprovar", o campo
"Comentário de Feedback" será acionado. É necessário escrever um feedback detalhado antes de confirmar a
reprovação. Quanto mais específico for seu feedback, mais eficiente será o treinamento do
agente.

Explique em suas próprias palavras por que a resposta não foi adequada: mencione itens que
faltaram, erros cometidos, ou qualquer aspecto que impediu sua satisfação plena com a resposta.

Existem dois modos de processamento de feedback:

Modo Automático: Quando configurado, o
feedback será imediatamente incorporado após você salvá-lo. A plataforma entrará automaticamente em modo
de treino do agente a partir do seu feedback.

Modo Manual: Neste modo, a plataforma não processa o
feedback imediatamente. É necessário que um humano entre no feedback registrado na aba "Feedbacks",
avalie se ele será incorporado e clique no botão "Corrigir com IA" para iniciar o treinamento. Isso
permite manter controle sobre quais feedbacks são realmente relevantes e precisam ser incorporados, sendo
especialmente útil quando múltiplos usuários estão fornecendo feedbacks no projeto.

Para compartilhar seu projeto e permitir que outros usuários testem e forneçam
feedbacks:

1. Clique no botão "Compartilhar"
2. Insira o usuário que deseja adicionar
3. Selecione
o papel de "Auditor"

O usuário com papel de auditor poderá enviar testes e dar feedbacks de forma
livre. Se você quiser revisar os feedbacks antes de incorporá-los, mantenha seu projeto em modo de
feedback manual. Assim, você terá tempo para verificar cada feedback e decidir se irá incorporá-lo
posteriormente.

Sim, o agente aceita áudio como input. Ele faz a transcrição automática do áudio e insere o texto transcrito na caixa de texto. Após o upload do áudio, basta clicar em enviar para que o agente processe o input.

Sim, o agente aceita imagens como input. Você pode fazer o upload clicando no ícone de imagem. Se a imagem contiver texto, o agente fará a extração automática e colocará o texto na caixa de texto. Se a imagem não contiver texto, o agente fará uma descrição detalhada da imagem e transformará essa descrição em texto.

Atualmente, o agente não aceita PDF diretamente. O lançamento dessa funcionalidade está previsto para outubro de 2025. Até lá, você pode transformar o PDF em imagem ou copiar e colar o texto do PDF na caixa de texto.

Sim. Todo agente construído na plataforma possui automaticamente uma API dedicada pronta para ser consumida por sistemas externos.

Como obter o acesso:

1 - Acesse o Fluxo: Vá até o editor do fluxo de agentes o qual você deseja utilizar a api.

2 - Menu Publicar: Clique no botão "Publicar" e selecione a opção "Publicar via API".

3 - Painel de Integração: Nesta tela, você terá acesso a todos os dados necessários para a requisição:

- URL do Agente: O endereço (endpoint) para onde você enviará os dados.

- Chaves de API: Área para gerar e copiar o Token de autenticação seguro.

- Formatos Aceitos: Documentação técnica explicando como enviar diferentes tipos de input (JSON, Imagem, Áudio, etc.).

Resumo: Basta gerar a chave de acesso e utilizar a URL fornecida para enviar o input inicial (dados de entrada). Isso acionará o fluxo do agente remotamente, permitindo a integração com qualquer software ou automação.

Sim ele pode, esta funcionalidade permite que a resposta gerada pelo agente da PrototipeAI seja enviada automaticamente para um sistema externo (como Zoho, Salesforce, entre outros sistemas) através de uma requisição API.

Passo a passo de configuração:

1 - Acesse as Configurações do passo do fluxo: No menu principal, vá até a aba de Configurações.

2 - Envio de Resposta: Localize a seção "Envio de resposta do agente" na parte inferior da tela.

3 - Criar Novo Destino: Clique para adicionar uma nova integração. Você precisará preencher os seguintes campos:

- Nome do Destino: Identificação interna (ex: Integração Zoho Recruit).

- URL da API: O endpoint do sistema externo que receberá os dados.

- Autenticação: Defina o método necessário (ex: Bearer Token, API Key).

- Método HTTP: Geralmente POST ou PUT.

- Caminho da API: O path específico da rota, se houver.

- Variáveis de Rota: Caso a API exija variáveis dinâmicas na URL.

4 - Configuração do Template (O passo mais importante):

Nesta etapa, você estruturará o corpo da requisição (Body).

Você deve montar o JSON exatamente no formato que o sistema externo espera receber.

Utilize a variável da resposta do agente anterior para preencher o conteúdo dinamicamente.

5 - Customização e Salvamento:

Configure cabeçalhos (headers) ou JSONs customizados se necessário.

6 - Clique em Salvar Alterações.

A partir de agora, assim que o agente gerar a análise, o sistema fará o envio (disparo) dessa resposta formatada diretamente para a plataforma conectada.

Sim, você pode cadastrar uma API para que o agente consulte dados durante a execução. Se a API for protegida, é necessário cadastrar o token de autenticação. Isso é feito através de um formulário na interface do sistema, sem necessidade de escrever código.

Sim, você pode trocar os modelos utilizados pelo agente para qualquer um dos principais modelos de mercado, como os da OpenAI ou Google. A troca é feita através de um menu na tela, sem a necessidade de escrever código.

O custo médio por execução é o cálculo feito automaticamente pela plataforma para determinar o custo de uma mensagem ou análise do agente. Ele é baseado na estimativa dos tokens que as instruções do agente possuem e varia conforme o modelo utilizado.

O custo por mensagem inclui tanto o input enviado pelo usuário quanto a resposta do agente. É o custo combinado de ambas as partes, utilizado para calcular o custo médio de uma conversa completa.

Após o agente processar um input, você poderá acessar e baixar os resultados:

1. Depois de enviar um input para o agente, os resultados gerados aparecerão no 'Histórico de Execuções'.

2. Para visualizar os resultados diretamente na tela, clique em 'Ver resultados' na entrada correspondente no histórico.

3. Para baixar os resultados, utilize o botão de 'Download' disponível. Os formatos de exportação incluem CSV, XLSX e DOCX.

O formato da resposta do agente influencia diretamente o tipo de exportação:

* Para exportar um arquivo DOCX com formatação adequada, é necessário solicitar nas instruções do agente que a resposta seja gerada em formato Markdown.

* Para exportar em CSV ou XLSX, você deve solicitar nas instruções do agente que a resposta seja gerada em formato JSON.

Certifique-se de configurar a instrução do agente de acordo com o formato de exportação desejado.

Existem duas formas de exportar o conteúdo gerado pelo agente para um formato Word. A primeira é exportar em JSON, caso você tenha acesso a uma API que fará a criação automática do documento em seu sistema. Caso contrário, você pode solicitar que o agente crie o conteúdo em formato Markdown. Ao informar o agente de que o formato adequado é Markdown, ele habilitará automaticamente um botão para download em DOCX, permitindo que você obtenha o documento no formato desejado.

Não é necessário publicar o agente para ele começar a funcionar. Assim que o agente é concluído, você é redirecionado para a área de testes, onde já pode começar a interagir com ele. O botão 'Publicar' oferece outras opções, como gerar o token de acesso para a API e, futuramente, a publicação automática via WhatsApp.

Os botões de play encontrados em vários lugares da plataforma oferecem vídeos curtos explicativos sobre cada recurso disponível. Eles servem para esclarecer dúvidas rápidas sobre o funcionamento dos itens da plataforma.

A ferramenta 🤝 Transf. para Humano permite que o agente de IA pause a conversa e passe o atendimento para um operador humano dentro do Chatwoot. Quando o operador resolve o ticket, a IA volta a responder automaticamente.

Esta integração funciona em dois sentidos:

• Prototipe.ai → Chatwoot: cria o ticket e envia mensagens do usuário enquanto a IA está pausada.


• Chatwoot → Prototipe.ai: entrega as mensagens do operador humano pra você responder no canal original (WhatsApp, web, etc.) e detecta quando o ticket foi resolvido pra reativar a IA.

A configuração tem 6 etapas, todas rápidas (cerca de 10 minutos no total).

Pré-requisito

• Acesso de Administrador ao Chatwoot


• O step do Prototipe.ai onde a tool será adicionada

---

Etapa 1 — Crie a Inbox API no Chatwoot

A Inbox API é onde os tickets vão aparecer pros operadores.

1. No Chatwoot, vai em Settings → Inboxes → Add Inbox.


2. Escolhe o canal API (ícone de chave inglesa).


3. Preenche:
   
   
   
   • Channel Name: Prototipe.ai (ou o nome que preferires)
   
   
   • Webhook URL: deixa qualquer placeholder por enquanto, ex: https://exemplo.com/temp — você atualiza no final.
   
   
   
   


4. Clica Create Inbox.


5. Na tela seguinte (Add Agents), seleciona quem deve receber esses tickets e clica Add Agents.


6. Pula o último passo ("Voilà").

⚠️ Anota o Inbox ID: depois de criar a inbox, abre ela e olha a URL do navegador — o número que aparece depois de /inbox/ é o teu Inbox ID.

Exemplo: em https://app.chatwoot.com/app/accounts/12/inbox/47 o Inbox ID é 47.

Importante: o token inbox_identifier (string longa tipo u95NU7Bb7NeYKPgoxd1JoniV) que aparece na configuração da inbox não é o Inbox ID — aquele token serve pra outra coisa (SDK público de chat). Use o número da URL.

---

Etapa 2 — Identifique o Account ID e a Base URL

Account ID: na mesma URL da Etapa 1, o número depois de /accounts/.

https://app.chatwoot.com/app/accounts/12/inbox/47

                                 ↑

                            Account ID = 12

Base URL: o domínio raiz do teu Chatwoot, sem barra no final.

• Chatwoot Cloud: https://app.chatwoot.com


• Self-hosted: https://chatwoot.suaempresa.com

---

Etapa 3 — Crie um Agent Bot pra obter o Access Token

⚠️ Recomendamos usar Agent Bot em vez do teu token pessoal. Vantagens:

• Não fica atrelado a uma pessoa específica (sobrevive a saídas/desligamentos da equipe).


• Tem escopo limitado às inboxes onde for atribuído.


• Funciona como uma "conta de serviço" identificável nos logs.

Como criar:

1. Vai em Settings → Integrations → Agent Bots.


2. Clica em New Agent Bot.


3. Preenche:
   
   
   
   • Bot Name: Prototipe.ai Handoff
   
   
   • Description: Integração com Prototipe.ai para transferência humana
   
   
   • Bot URL: deixa em branco.
   
   
   
   


4. Clica Create.


5. Copia o Access Token que aparece — em algumas versões ele só é exibido uma vez. Guarda em local seguro.

Atribui o bot à inbox criada na Etapa 1:

1. Settings → Inboxes → Prototipe.ai (a inbox que criaste)


2. Vai na aba Bot Configuration


3. Seleciona o bot Prototipe.ai Handoff


4. Clica Update

💡 Alternativa: se preferires usar o token pessoal, vai em Profile Settings (clica no teu avatar → Profile Settings) e copia o Access Token da seção homônima. Funciona, mas considera as desvantagens acima.

---

Etapa 4 — Cria a tool 🤝 Transf. para Humano no Prototipe.ai

1. No Prototipe.ai, abre o step do agente onde a tool será adicionada.


2. Clica em Adicionar Nova Ferramenta.


3. Seleciona o card 🤝 Transf. para Humano.


4. Clica Continuar.


5. Preenche o form:
   
   
   
   • Plataforma: Chatwoot
   
   
   • Base URL: a URL da Etapa 2 (ex: https://app.chatwoot.com)
   
   
   • Account ID: o número da Etapa 2 (ex: 12)
   
   
   • Inbox ID: o número da Etapa 1 (ex: 47)
   
   
   • Access Token: o token da Etapa 3
   
   
   
   


6. Clica Confirmar.

A tool é criada e fica visível na seção External Sources do step.

---

Etapa 5 — Pega a URL inbound e cola no Chatwoot

Agora fechamos o ciclo: o Chatwoot precisa saber pra onde mandar as mensagens do operador humano e os eventos de status.

1. No Prototipe.ai, na seção External Sources do step, clica Editar no card 🤝.


2. Vai aparecer um campo amarelo destacado com a URL inbound completa, no formato:
   

   https://app.prototipeai.com/api/v1/integrations/chatwoot/webhooks/<id>?t=<token>

   
   


3. Copia essa URL inteira (incluindo ?t=<token>).

No Chatwoot, configura o webhook — escolhe uma das duas opções:

Opção A (recomendada): Webhook da própria Inbox

1. Settings → Inboxes → Prototipe.ai → aba Configuration


2. No campo Webhook URL, cola a URL copiada


3. Clica Update

Vantagem: o webhook só dispara para essa inbox específica.

Opção B: Webhook account-level

1. Settings → Configurations → Webhooks → Add new webhook endpoint


2. Endpoint: cola a URL copiada


3. Subscriptions: marca apenas
   
   
   
   • ✅ message_created
   
   
   • ✅ conversation_status_changed
   
   
   
   


4. Clica Add

---

Etapa 6 — Atualiza o prompt do agente

Pra IA saber quando chamar a transferência, adiciona no prompt do agente:

Você tem disponível a ferramenta "Transf. para Humano".


Use quando:

- O usuário pedir explicitamente para falar com humano

- Demonstrar frustração extrema ou repetida

- Em casos críticos/sensíveis fora do teu escopo

Após chamar a ferramenta, NÃO continue respondendo. Aguarde o operador humano assumir.

---

Como testar se funcionou

1. No canal do agente (WhatsApp, widget, etc.), envia: "quero falar com humano por favor".


2. No Chatwoot, um novo ticket aparece na inbox Prototipe.ai.


3. No canal do agente, aparece a mensagem: "Sua solicitação foi recebida. Em instantes um atendente humano vai responder por aqui."


4. No Chatwoot, o operador responde no ticket.


5. No canal do agente, a resposta do operador chega como se fosse o agente.


6. No Chatwoot, o operador clica em Resolved quando terminar.


7. No canal do agente, a próxima mensagem volta a ser respondida pela IA.

---

Problemas comuns

O ticket não aparece no Chatwoot

• Confere se o Access Token tá correto e o Agent Bot foi atribuído à inbox.


• Confere se o Account ID e Inbox ID são os números da URL, não o inbox_identifier (string).

A mensagem do operador não chega no canal do usuário

• Confere se a Webhook URL no Chatwoot está exatamente igual ao campo amarelo do Prototipe.ai (incluindo o ?t=...).


• Confere se o webhook tem message_created marcado.

A IA continua respondendo mesmo depois da transferência

• Verifica se a tool foi mesmo criada como Transf. para Humano.


• Espera 5 segundos (cache do projeto pode estar ainda válido).

O ticket não fecha quando o operador resolve

• Confere se conversation_status_changed está marcado nas subscriptions do webhook.

---

Segurança e boas práticas

• O Access Token deve ter escopo mínimo. Use Agent Bot em vez do token pessoal de admin.


• O token inbound (?t=...) é gerado automaticamente pelo Prototipe.ai e validado a cada requisição. Nunca compartilhes essa URL publicamente.


• Em produção, todas as URLs devem ser HTTPS — o Prototipe.ai bloqueia automaticamente URLs apontando pra redes privadas (RFC1918, loopback, link-local).

---

Não usa Chatwoot? Veja a FAQ "Como integrar Transferência Humana via Webhook Genérico (HMAC + API REST)" para integrar com Crisp, Zendesk, n8n, dashboard próprio, etc.

A plataforma Webhook Genérico (HMAC) é a opção pra integrar a Transferência Humana com qualquer sistema que não tenha adapter dedicado: Crisp, Zendesk, Freshdesk, Intercom, n8n, dashboards internos, etc.

Diferente do Chatwoot (que tem integração bidirecional pronta), no Generic Webhook você implementa as duas pontas:

• Prototipe.ai → tua plataforma: recebes eventos via webhook HTTP POST assinado com HMAC-SHA256.


• Tua plataforma → Prototipe.ai: chamas nossa API REST com Bearer token pra pausar a IA, mandar mensagens do operador e devolver controle.

Quando usar Generic Webhook vs Chatwoot

• Use Chatwoot se você quer uma solução pronta de atendimento humano (UI de tickets, agentes, SLA, relatórios) e não quer escrever código.


• Use Generic Webhook se você já tem uma plataforma de atendimento, um dashboard interno ou quer orquestrar via n8n/Zapier. Você controla a UX do operador no teu lado.

---

Visão geral do ciclo

1. A IA decide transferir → Prototipe.ai pausa a conversa e dispara webhook conversation.handed_off pra teu endpoint.


2. Tua plataforma recebe o evento, valida o HMAC, abre um ticket/notifica o operador.


3. Enquanto a IA estiver pausada, cada mensagem nova do usuário dispara message.created no teu endpoint.


4. O operador humano responde no teu lado → você chama POST /agent_messages na nossa API → a mensagem chega no canal do usuário (WhatsApp/widget).


5. Quando o operador encerrar, você chama POST /resume → IA volta a responder. Prototipe.ai dispara conversation.resumed de volta pra confirmar.

---

Etapa 1 — Crie a API Key (autenticação inbound)

Pra tua plataforma chamar nossa API, precisa de uma API Key com permissão handoff.

1. No Prototipe.ai, abre Configurações do Time → API Keys.


2. Clica Nova API Key.


3. Preenche:
   
   
   
   • Nome: Integração HITL — <tua plataforma>
   
   
   • Permissões: marca handoff (obrigatório).
   
   
   • Acesso a projetos: seleciona o projeto onde a tool 🤝 vai rodar.
   
   
   
   


4. Salva e copia o token retornado — ele só aparece uma vez.

⚠️ Importante: API Keys criadas pela UI são team-scoped (têm acesso a vários projetos do time). Por isso, todas as chamadas precisam informar ?slug=<slug-do-projeto> na query string. O slug aparece na URL do projeto.

❌ Não funciona com Generic Webhook:

• API Keys flow-scoped (atreladas a um automation_flow específico) — bloqueadas pra prevenir escalada de escopo. Use team-scoped ou project-scoped.

---

Etapa 2 — Cria a tool 🤝 Transf. para Humano

1. No step do agente, clica Adicionar Nova Ferramenta.


2. Seleciona o card 🤝 Transf. para Humano e clica Continuar.


3. No form:
   
   
   
   • Plataforma: Webhook Genérico (HMAC)
   
   
   • URL do webhook externo: a URL do teu endpoint que vai receber os eventos. Ex: https://api.minhaplataforma.com/webhooks/prototipai. Precisa ser HTTPS público (bloqueamos IPs privados/loopback automaticamente por SSRF).
   
   
   • Segredo HMAC: cola um segredo ou usa o botão gerar pra criar um aleatório. Guarda esse segredo no teu lado — é com ele que você vai verificar a assinatura.
   
   
   • Headers extras (JSON, opcional): se teu endpoint exige headers custom (ex: tenant ID, auth secundária), informa como JSON. Ex: {"X-Tenant-Id": "abc-123"}.
   
   
   
   


4. Clica Confirmar.

---

Etapa 3 — Implementa o endpoint que recebe os webhooks

Eventos enviados pelo Prototipe.ai

Todos chegam como POST no endpoint_url que você configurou, com Content-Type: application/json. O body sempre tem o formato:

{

  "event": "conversation.handed_off",

  "delivered_at": "2026-05-10T22:30:00-03:00",

  "data": { ... }

}

Eventos possíveis:

• conversation.handed_off — IA pausada. data traz conversation, agent_ref (se houver), reason (se houver).


• conversation.resumed — controle devolvido pra IA. data traz conversation e previous_agent_ref.


• message.created — usuário mandou mensagem nova com a IA pausada. data traz conversation e message.

Headers em cada POST

• X-Prototipai-Event: nome do evento (redundante com body.event, útil pra roteamento rápido).


• X-Prototipai-Delivery: UUID único da entrega. Use pra idempotência — se receber o mesmo UUID duas vezes, ignora a segunda (acontece em retries).


• X-Prototipai-Signature: assinatura HMAC-SHA256 do body cru usando o segredo configurado.

Validação da assinatura HMAC

Ruby:

expected = OpenSSL::HMAC.hexdigest('sha256', SEGREDO, request.raw_post)

received = request.headers['X-Prototipai-Signature']

unless Rack::Utils.secure_compare(expected, received.to_s)

  head :unauthorized and return

end

Node.js:

const crypto = require('crypto');

const expected = crypto

  .createHmac('sha256', SEGREDO)

  .update(rawBody)  // bytes crus, ANTES de JSON.parse

  .digest('hex');

const ok = crypto.timingSafeEqual(

  Buffer.from(expected),

  Buffer.from(req.headers['x-prototipai-signature'] || '')

);

if (!ok) return res.status(401).end();

Python:

import hmac, hashlib

expected = hmac.new(SEGREDO.encode(), raw_body, hashlib.sha256).hexdigest()

received = request.headers.get('X-Prototipai-Signature', '')

if not hmac.compare_digest(expected, received):

    abort(401)

⚠️ Cuidados:

• Use o body cru (raw bytes) na assinatura, não o JSON re-serializado.


• Use comparação constant-time (secure_compare / timingSafeEqual / hmac.compare_digest) pra evitar timing attacks.


• Responde rápido (< 10s). Demora além disso conta como timeout.

Retry / response codes

• 2xx → entrega marcada como sucesso.


• 4xx (exceto 429) → não retentamos. Assumimos bug permanente no teu lado.


• 5xx ou 429 → retentamos com backoff exponencial via Sidekiq.

---

Etapa 4 — Implementa a chamada à nossa API REST

Todos os endpoints exigem:

• Authorization: Bearer <TOKEN> (a API Key da Etapa 1)


• ?slug=<slug-do-projeto> na query string

POST /api/v1/conversations/:id/handoff — pausa a IA

POST /api/v1/conversations/:id/handoff?slug=<slug>

Authorization: Bearer <TOKEN>

Content-Type: application/json


{

  "agent_ref": "maria@empresa.com",

  "reason": "cliente irritado, escalando"

}

Ambos os parâmetros (agent_ref, reason) são opcionais. Útil quando você quer disparar o handoff do teu lado (ex: regra de negócio), sem depender da IA decidir.

POST /api/v1/conversations/:id/agent_messages — operador responde

POST /api/v1/conversations/:id/agent_messages?slug=<slug>

Authorization: Bearer <TOKEN>

Content-Type: application/json


{

  "content": "Oi, sou a Maria! Como posso ajudar?",

  "agent_ref": "maria@empresa.com"

}

content obrigatório (máx 8.000 caracteres). A conversa precisa estar em handoff (chame /handoff antes, ou a IA chamou a tool). A mensagem entra no canal original do usuário automaticamente.

POST /api/v1/conversations/:id/resume — devolve pra IA

POST /api/v1/conversations/:id/resume?slug=<slug>

Authorization: Bearer <TOKEN>

Sem body. A IA volta no mesmo estado em que estava antes do handoff (preservamos o lookahead_state automaticamente).

GET /api/v1/conversations/:id/poll — alternativa ao webhook

GET /api/v1/conversations/:id/poll?slug=<slug>&since=2026-05-05T12:00:00Z

Authorization: Bearer <TOKEN>

Retorna até 100 mensagens criadas após since (ISO8601). Suporta ETag/If-None-Match — se nada mudou desde a última chamada, retorna 304 Not Modified sem pesar o banco. Use polling se receber webhooks for inviável (ex: ambiente sem URL pública).

---

Exemplo completo (curl, fluxo do operador)

TOKEN='cole-a-key-aqui'

CONV=123

SLUG='meu-projeto-slug'

BASE='https://app.prototipeai.com'


# 1) Pausa a IA (opcional — a tool da IA já faz isso automaticamente)

curl -X POST "$BASE/api/v1/conversations/$CONV/handoff?slug=$SLUG"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"agent_ref":"maria@x.com","reason":"teste"}'

# 2) Operador responde

curl -X POST "$BASE/api/v1/conversations/$CONV/agent_messages?slug=$SLUG"   -H "Authorization: Bearer $TOKEN"   -H "Content-Type: application/json"   -d '{"content":"Oi, sou a Maria!","agent_ref":"maria@x.com"}'

# 3) Devolve pra IA

curl -X POST "$BASE/api/v1/conversations/$CONV/resume?slug=$SLUG"   -H "Authorization: Bearer $TOKEN"

---

Polling vs Webhook — qual usar?

• Webhook (recomendado): tempo real, baixo custo. Requer endpoint público HTTPS.


• Polling: simples de implementar, funciona em qualquer ambiente. Latência depende do intervalo (recomenda-se 5-10s). Cuidado com rate limit.


• Híbrido: webhook como primário, polling como fallback se você suspeitar de eventos perdidos.

---

Erros comuns

• 401 Token de autenticação não fornecido → faltou o header Authorization: Bearer ….


• 401 Token inválido → key errada, expirada ou revogada.


• 401 Projeto não é válido → faltou o ?slug= na query string (team-scoped key precisa).


• 403 API key não possui permissão handoff → recria a key marcando a permissão handoff.


• 403 API key flow-scoped não pode usar handoff → use uma key team-scoped (com slug) ou project-scoped.


• 409 Conversa já está em handoff → tentou pausar uma conversa já pausada. Trate como idempotente no teu lado.


• 409 Conversa não está em handoff → tentou mandar mensagem ou resume em conv ainda controlada pela IA.


• 404 Conversa não encontrada → o :id não existe ou não pertence ao projeto do slug.


• 400 content é obrigatório / content excede 8000 caracteres → ajusta o payload.

---

Segurança e boas práticas

• Nunca exponha a API Key no frontend. Use no backend, com proxy se precisar.


• Rotaciona o segredo HMAC periodicamente (ou se houver suspeita de vazamento). Edita a tool no Prototipe.ai pra trocar.


• Idempotência: armazene os X-Prototipai-Delivery recentes (24h) e ignore duplicatas. Retries acontecem em falhas transitórias.


• Endpoint público: o Prototipe.ai bloqueia URLs apontando pra redes privadas (RFC1918, loopback, link-local) pra prevenir SSRF.


• Timeouts: tenta responder em < 5s. Limite interno é 10s.


• HTTPS obrigatório em produção.