- Início
- API de chatbot com IA
API de chatbot com IA para as suas aplicações
Quer o assistente da Asyntai numa app, num portal de clientes ou numa ferramenta interna? A API REST recebe a pergunta, procura a resposta no conteúdo do seu site e devolve-a em JSON. Este guia mostra o pedido, os endpoints e os cuidados a ter.
- 50 respostas de IA por mês grátis
- JSON simples
- Sem cartão de crédito
Como funciona a API de chatbot da Asyntai?
O seu servidor envia a pergunta do utilizador para POST /api/v1/chat/, com a chave no cabeçalho X-API-Key. A resposta chega em JSON, escrita a partir do conteúdo que ligou à conta. São três passos:
- Crie a conta e ligue o site, para a IA conhecer o seu negócio.
- Gere a chave da API em Definições, API (planos Starter, Standard e Pro).
- Faça o primeiro pedido a partir do servidor e mostre o campo
responsena sua app.
Widget, API REST ou ligação direta a um modelo de IA?
Há três caminhos para pôr um assistente de IA num produto digital. A escolha depende de onde o chat vai aparecer e de quanto trabalho quer ter com a pesquisa no seu conteúdo.
| Widget no siteuma linha de código | Modelo de IA diretotudo feito por si | API REST da Asyntaio seu ecrã, as nossas respostas | |
|---|---|---|---|
| Onde aparece o chat | No seu site, numa janela pronta. | Onde o programar. | Em qualquer ecrã: app, portal, quiosque, ferramenta interna. |
| De onde vêm as respostas | Do conteúdo do site e da base de conhecimento. | Do que o seu código enviar em cada pedido. | Do mesmo conteúdo que o widget usa. |
| O que tem de construir | Nada. | Pesquisa no conteúdo, histórico, registos e interface. | Só a interface e um pedido HTTP. |
| Histórico da conversa | Tratado pelo widget. | Guardado e enviado por si. | Basta enviar o mesmo session_id. |
| Registos e leads | No painel. | Só o que construir. | No painel e nos endpoints /sessions/ e /leads/. |
Widget no site
- Onde aparece o chat
- No seu site, numa janela pronta.
- De onde vêm as respostas
- Do conteúdo do site e da base de conhecimento.
- O que tem de construir
- Nada.
- Histórico da conversa
- Tratado pelo widget.
- Registos e leads
- No painel.
Modelo de IA direto
- Onde aparece o chat
- Onde o programar.
- De onde vêm as respostas
- Do que o seu código enviar em cada pedido.
- O que tem de construir
- Pesquisa no conteúdo, histórico, registos e interface.
- Histórico da conversa
- Guardado e enviado por si.
- Registos e leads
- Só o que construir.
API REST da Asyntai
- Onde aparece o chat
- Em qualquer ecrã: app, portal, quiosque, ferramenta interna.
- De onde vêm as respostas
- Do mesmo conteúdo que o widget usa.
- O que tem de construir
- Só a interface e um pedido HTTP.
- Histórico da conversa
- Basta enviar o mesmo session_id.
- Registos e leads
- No painel e nos endpoints /sessions/ e /leads/.
Pode usar o widget e a API ao mesmo tempo. Ambos respondem a partir da mesma base de conhecimento, por isso uma alteração no conteúdo chega aos dois.
Como fazer o primeiro pedido à API
O endereço base é https://asyntai.com/api/v1/. O endpoint de chat aceita JSON com um campo obrigatório, message, e dois opcionais.
- 01
Prepare a conta
Crie a conta grátis, indique o endereço do site e confirme no painel que as respostas estão corretas.
- 02
Gere a chave
Num plano pago, abra Definições e depois API e crie a chave. Guarde-a numa variável de ambiente do servidor.
- 03
Envie a mensagem
Faça um POST com
message. Juntesession_idpara manter a conversa ewebsite_idse tiver vários sites. - 04
Mostre a resposta
Leia o campo
responsee mostre-o no seu ecrã. Na primeira resposta, mostre tambémai_disclosure.
curl -X POST https://asyntai.com/api/v1/chat/ \
-H "X-API-Key: A_SUA_CHAVE" \
-H "Content-Type: application/json" \
-d '{"message": "Têm consultas ao sábado?", "session_id": "cliente_4821"}'
Também aceita Authorization: Bearer A_SUA_CHAVE no lugar de X-API-Key.
{
"success": true,
"response": "Sim. Ao sábado atendemos das 9h às 13h, apenas com marcação.",
"session_id": "cliente_4821",
"ai_disclosure": "..."
}
O campo ai_disclosure traz uma frase a avisar que a resposta vem de uma IA, na língua da resposta. Nas mensagens seguintes vem vazio. Todos os campos estão na referência da API.
Que endpoints tem a API REST?
O chat é o ponto de partida, mas a API cobre também os dados que o chatbot recolhe e a configuração da conta. Todos usam a mesma chave.
Chat
POST /chat/Envia uma mensagem e recebe a resposta da IA. É o único endpoint de que precisa para pôr o assistente numa app.
Sessões e conversas
GET /sessions/ · /conversations/Lista as conversas recentes do widget, da API e dos outros canais, e, nas conversas do widget, a página de origem e o país. Depois leia as mensagens de cada sessão. Bom para relatórios no seu próprio sistema.
Leads
GET /leads/Devolve os e-mails e números de telefone que os visitantes deixaram no chat, com o session_id da conversa. Útil para os enviar para um CRM.
Base de conhecimento
/knowledge/Lista, lê e apaga entradas, e adiciona texto, uma página por URL ou uma folha de cálculo CSV ou Excel. Assim o conteúdo do chatbot acompanha o seu sistema.
Sites e instruções
/websites/Cria um agente novo a partir de um domínio, consulta o estado, altera as definições do widget e substitui as instruções da IA, com proteção contra perda de texto.
Webhooks
/webhooks/Recebe um POST no seu servidor quando há uma mensagem nova, uma conversa começa, a IA pede ajuda humana ou um agente assume o chat. Cada envio vem assinado com HMAC-SHA256.
De onde vêm as respostas da API
A API não precisa de receber o seu conteúdo em cada pedido. Para cada pergunta, a Asyntai procura as partes certas na base de conhecimento da conta e escreve a resposta a partir delas.
Análise do site
O crawler segue as ligações e lê o texto das páginas.
URLs individuais
Uma página de cada vez, também pelo endpoint /knowledge/url/.
Ficheiros PDF
Manuais, tabelas e regulamentos, incluindo PDF digitalizados.
Folhas de cálculo
CSV ou Excel, em que cada linha é uma entrada.
Texto simples
Factos que não estão no site, escritos no painel ou enviados pela API.
Ficheiros HTML
Páginas guardadas e documentos em HTML.
Vídeos
A IA responde a partir da transcrição.
Real-Time Data Feed
Um URL com dados que mudam, como stock ou disponibilidade.
Standard e ProAs instruções da conta definem o tom e as regras, e valem tanto para o widget como para a API. O guia da base de conhecimento explica cada fonte.
Exemplos de integração com a API
Três usos frequentes. Em todos, o seu código trata do ecrã e a Asyntai trata da resposta.
A app envia o ID do sócio como session_id. A resposta vem do regulamento em PDF.
Resposta de um artigo de ajuda, mostrada dentro do portal com o design da marca.
A equipa pergunta num painel próprio. A resposta vem de uma folha de cálculo com as condições.
Segurança, limites e códigos de erro
Todos os pedidos usam HTTPS. Mantenha a chave no servidor: quem tiver a chave tem acesso à sua conta pela API. Os erros chegam sempre com "success": false e um campo error com a explicação.
- 401
Chave em falta ou errada
O pedido não trouxe chave, ou a chave não existe. Confirme o cabeçalho e a chave em Definições, API.
- 403
Plano gratuito
A conta está no plano gratuito. A API precisa do plano Starter, Standard ou Pro.
- 429
Limite mensal atingido
As respostas de IA do mês acabaram. O JSON traz
limit_reacheda true até o plano renovar ou subir. - 503
Serviço indisponível
A IA não conseguiu responder naquele momento. Volte a tentar o pedido mais tarde.
Um pedido com JSON inválido ou sem message devolve 400. Os uploads para a base de conhecimento têm um limite diário de caracteres que depende do plano.
Planos e preços da API
A API está em todos os planos pagos. Cada resposta pela API conta como uma resposta de IA do plano, como no widget.
Free
0 USD /mês- 50 respostas de IA por mês
- 1 site
- Teste das respostas no painel
Starter
39 USD /mês- 800 respostas de IA por mês
- 2 sites
- API REST e webhooks
Standard
139 USD /mês- 15.000 respostas de IA por mês
- 3 sites
- Custom tools e User context
Pro
449 USD /mês- 50.000 respostas de IA por mês
- 20 sites
- Sem marca Asyntai
Todas as funções de cada plano estão na página de preços.
Perguntas frequentes sobre a API de chatbot
Em que plano está disponível a API?
A API REST está nos planos Starter, Standard e Pro. No plano gratuito pode criar a conta, ligar o site e testar as respostas no painel, mas um pedido à API devolve o código 403.
Como envio a chave da API?
No cabeçalho X-API-Key ou no cabeçalho Authorization com o formato Bearer seguido da chave. A chave gera-se no painel, em Definições e depois API.
Como mantenho o contexto de uma conversa?
Envie o mesmo session_id em todas as mensagens do mesmo utilizador. A IA usa as mensagens anteriores dessa sessão para entender a pergunta seguinte. Sem session_id, os pedidos da conta partilham uma sessão por site.
Posso chamar a API diretamente a partir do browser?
Não deve. Quem vê a chave pode usar a sua conta. Faça o pedido a partir do seu servidor e envie para a página ou para a app só o texto da resposta.
Que linguagens de programação posso usar?
Qualquer linguagem que faça pedidos HTTPS com JSON: Python, JavaScript ou Node.js, PHP, Java, C#, Go, Ruby e outras. A documentação tem exemplos em cURL, Python e JavaScript.
As respostas da API são iguais às do widget?
Sim. A API usa o mesmo conteúdo, as mesmas instruções e o mesmo site da conta. As conversas feitas pela API aparecem nos registos de chat com a origem api.
O que acontece quando chego ao limite do plano?
A API devolve o código 429 com limit_reached a true. Cada resposta da API conta como uma resposta de IA do seu plano mensal, tal como no widget.
Posso adicionar conteúdo à base de conhecimento pela API?
Sim. Os endpoints /knowledge/text/, /knowledge/url/ e /knowledge/spreadsheet/ adicionam texto, uma página ou uma folha de cálculo CSV ou Excel. Há um limite diário de caracteres conforme o plano.
Comece pelo conteúdo, depois ligue a API
Crie a conta grátis com 50 respostas de IA por mês e teste as respostas no painel. Quando estiver satisfeito, ative um plano pago e gere a chave.