Em resumo
- O mesmo agente, em qualquer tela.As respostas vêm do mesmo conhecimento, das mesmas instruções e regras do chat do seu site.
- Transmitida palavra por palavra.Peça um stream e a resposta chega conforme é escrita, no formato AI SDK UI Message Stream.
- As fontes vêm junto.Cada resposta inclui as fontes citadas, com títulos e links para páginas da web.
- Novas tentativas nunca cobram em dobro.Tente de novo com a mesma Idempotency-Key e você recebe a resposta já registrada, não uma segunda resposta.
Seu site não é o único lugar em que as pessoas têm perguntas. A equipe de suporte quer respostas dentro do seu helpdesk, os clientes querem ajuda dentro do seu app para celular, e o seu produto pode precisar de um agente na própria interface. A API de chat permite usar o seu agente da OneType em qualquer lugar de onde você consiga fazer uma requisição HTTPS, sem o widget do site.
Duas chamadas até uma resposta com fontes
- Crie uma chave com a permissão conversations.write.
- Abra uma conversa para um agente com POST /v1/conversations.
- Envie a mensagem do visitante com POST /v1/conversations/{id}/messages.
- Leia a resposta: partes de texto mais uma parte de fonte para cada fonte citada.
Cada resposta é escrita, registrada e contada exatamente como uma resposta no chat do seu site. A conversa aparece na sua caixa de entrada ao lado das conversas do seu site, e ao abri-la você vê que ela veio pela API, para que a sua equipe veja tudo em um só lugar.
Streaming
Envie stream: true e a resposta chega como server-sent events enquanto é escrita, para que a sua interface mostre as palavras conforme aparecem. O formato é o AI SDK UI Message Stream, versão 1. Se você usa o Vercel AI SDK no seu servidor, pode repassar a resposta direto ao hook de chat dele. A streaming termina com um evento finish que informa como a interação terminou, e uma marca done final.
Novas tentativas seguras
As redes caem. Envie um cabeçalho Idempotency-Key em cada mensagem. Se você tentar de novo com a mesma chave, recebe a resposta já registrada em vez de uma segunda resposta. Tentar de novo um stream que já terminou devolve a resposta registrada em JSON. Desconectar não cancela uma resposta: ela continua sendo escrita e registrada, então nada se perde.
Limites
Cada chave pode enviar até 20 mensagens de chat a cada 10 segundos, dentro do limite geral de 100 requisições a cada 10 segundos, igual em todos os planos pagos. As chaves são só para servidores, então a API de chat pertence ao seu backend, não a uma página da web. As chaves de API exigem Premium ou Enterprise. O plano Free não tem.
O que as pessoas constroem com ela
- Um painel de ajuda dentro do seu app web ou para celular, alimentado pelo seu backend.
- Um agente dentro de uma ferramenta interna, para que a equipe receba respostas com fontes a partir dos seus documentos.
- Um chatbot em outra ferramenta de mensagens que você administra, encaminhando perguntas ao seu agente.
- Verificações automatizadas que fazem ao seu agente um conjunto fixo de perguntas e leem o resultado.
Em todos os casos, as respostas seguem as mesmas instruções, o mesmo conhecimento e as mesmas regras de segurança que você definiu no painel, e uma resposta em streaming termina informando como a interação terminou.
As respostas chegam com as fontes como partes separadas, cada uma com título e, para páginas da web, um link, para que a sua interface mostre as citações do jeito que preferir. Cada mensagem também informa se foi escrita por IA, o que ajuda a rotulá-la com clareza para os seus usuários.