1. Início
  2. API de chatbot com IA
Guia Atualizado em novembro de 2026

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
Resposta rápida

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:

  1. Crie a conta e ligue o site, para a IA conhecer o seu negócio.
  2. Gere a chave da API em Definições, API (planos Starter, Standard e Pro).
  3. Faça o primeiro pedido a partir do servidor e mostre o campo response na 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.

  1. 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.

  2. 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.

  3. 03

    Envie a mensagem

    Faça um POST com message. Junte session_id para manter a conversa e website_id se tiver vários sites.

  4. 04

    Mostre a resposta

    Leia o campo response e mostre-o no seu ecrã. Na primeira resposta, mostre também ai_disclosure.

Pedido com cURL
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.

Resposta JSON
{
  "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 Pro

As 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.

App de ginásio
Posso congelar a mensalidade durante as férias?
Sim. Pode congelar a inscrição até 30 dias por ano, com um pedido na receção ou por e-mail, com 5 dias de antecedência.

A app envia o ID do sócio como session_id. A resposta vem do regulamento em PDF.

Portal de clientes
Como peço a segunda via de uma fatura?
Na área Faturas, escolha o mês e clique em Descarregar PDF. As faturas dos últimos 24 meses ficam disponíveis.

Resposta de um artigo de ajuda, mostrada dentro do portal com o design da marca.

Ferramenta interna
Qual é o prazo de devolução para encomendas de empresas?
Para clientes empresariais, o prazo é de 30 dias a contar da entrega, com a guia de transporte original.

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.

  1. 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.

  2. 403

    Plano gratuito

    A conta está no plano gratuito. A API precisa do plano Starter, Standard ou Pro.

  3. 429

    Limite mensal atingido

    As respostas de IA do mês acabaram. O JSON traz limit_reached a true até o plano renovar ou subir.

  4. 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.