Voltar ao Painel

Documentação

Aprenda a usar o Asyntai

Referência da API

Crie integrações personalizadas com a API REST do Asyntai

Obter Chave da API

Plano Pago Necessário: O acesso à API está disponível nos planos Starter, Standard e Pro. Ver preços

Visão Geral

The Asyntai API allows you to integrate AI-powered customer support into any application. Send messages and receive intelligent responses grounded in your website content and knowledge base.

Autenticação

Todas as requisições da API requerem autenticação usando sua chave da API. Você pode obter sua chave da API na página Configurações da API.

Inclua sua chave da API nas requisições usando um destes métodos:

  • Cabeçalho Authorization (recomendado): Authorization: Bearer YOUR_API_KEY
  • Cabeçalho X-API-Key: X-API-Key: YOUR_API_KEY

Mantenha sua chave da API em segredo. Qualquer pessoa com sua chave pode acessar sua conta pela API. Nunca a exponha em código do lado do cliente.

URL Base

https://asyntai.com/api/v1/

Endpoints

POST /chat/

Envie uma mensagem e receba uma resposta gerada por IA.

Corpo da Requisição

{
  "message": "What are your business hours?",
  "session_id": "user_123",      // optional
  "website_id": 1                 // optional
}
Parâmetro Tipo Obrigatório Descrição
message string Sim A mensagem do usuário para enviar à IA
session_id string Não Identificador único da conversa. Use o mesmo session_id para manter o histórico da conversa.
website_id integer Não ID específico do site. Se não fornecido, usa seu site principal.

Resposta

{
  "success": true,
  "response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
  "session_id": "user_123"
}

Exemplo (cURL)

curl -X POST https://asyntai.com/api/v1/chat/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are your business hours?", "session_id": "user_123"}'

Exemplo (Python)

import requests

response = requests.post(
    "https://asyntai.com/api/v1/chat/",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "message": "What are your business hours?",
        "session_id": "user_123"
    }
)

data = response.json()
print(data["response"])

Exemplo (JavaScript)

const response = await fetch("https://asyntai.com/api/v1/chat/", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your business hours?",
    session_id: "user_123"
  })
});

const data = await response.json();
console.log(data.response);

GET /websites/

Listar todos os sites associados à sua conta.

Resposta

{
  "success": true,
  "websites": [
    {
      "id": 1,
      "name": "My Website",
      "domain": "example.com",
      "is_primary": true
    }
  ]
}

Exemplo (cURL)

curl https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /websites/

Create a new AI agent. This does the same thing as adding a website in your dashboard: it makes the agent, reads your site, and writes the first draft of the AI instructions.

Use this to set up customers from your own software. You get back the widget ID and the code to put on the website.

Corpo da Requisição

Campo Tipo Descrição
domain string Required. The website address, for example example.com
name string Optional. A display name for the agent. Useful when one website has several agents.
crawl boolean Optional, true by default. Set it to false to create the agent without reading the website. Nothing is crawled and no instructions are written.
force boolean Optional, false by default. Set it to true to add a website you already have. The copy is stored with a number after it.

Resposta

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "crawl_started": true,
    "instructions_status": "generating",
    "job_id": "8f2c1e90-..."
  },
  "embed_code": "<script>...</script>"
}

Exemplo (cURL)

curl -X POST https://asyntai.com/api/v1/websites/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "example.com", "name": "Support agent"}'

Reading a website takes a few minutes, so this call answers straight away. Check when the agent is ready with the next endpoint.

Errors

Code Meaning
403 You have reached the number of websites your plan allows. The answer tells you the limit.
409 Your account already has this website. Send force as true to add it again.

GET /websites/{id}/

Get one website and see whether it is ready. Use this after you create an agent, to wait until the website has been read and the AI instructions are written.

Resposta

{
  "success": true,
  "website": {
    "id": 42,
    "domain": "example.com",
    "name": "Support agent",
    "widget_id": "asyntai_ab12cd34ef56",
    "is_primary": true,
    "created_at": "2026-08-11T09:12:00+00:00",
    "ready": true,
    "instructions": {
      "status": "completed",
      "has_instructions": true,
      "characters": 3421
    },
    "crawl": {
      "job_id": "8f2c1e90-...",
      "status": "completed",
      "pages_crawled": 47,
      "pages_found": 50,
      "max_pages": 50,
      "completed_at": "2026-08-11T09:15:31+00:00",
      "error": ""
    },
    "knowledge_items": 47
  },
  "embed_code": "<script>...</script>"
}

The ready field is true when nothing is still running. A crawl that failed also counts as ready, because it has finished. Look at the crawl status to see what happened.

Exemplo (cURL)

curl https://asyntai.com/api/v1/websites/42/ \
  -H "Authorization: Bearer YOUR_API_KEY"

GET PATCH /websites/{id}/settings/

Read or change the chat widget settings for one website. These are the same settings you see on the Customize page: colours, the name of the assistant, the first message, lead capture, and everything else.

Reading the settings

A GET request returns every setting with its current value, plus a locked list. Locked shows the settings your plan cannot change, and which plans they need.

{
  "success": true,
  "settings": {
    "ai_support_name": "AI Assistant",
    "widget_color": "#6366f1",
    "initial_message": "Hi, how can I help you?",
    "hide_branding": false,
    "...": "..."
  },
  "locked": {
    "hide_branding": ["pro", "enterprise"],
    "widget_style": ["pro", "enterprise"]
  }
}

Changing the settings

A PATCH request changes only the settings you send. Everything you leave out stays as it is.

curl -X PATCH https://asyntai.com/api/v1/websites/42/settings/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ai_support_name": "Ava", "widget_color": "#0f172a", "use_emoji": true}'
{
  "success": true,
  "updated": ["ai_support_name", "use_emoji", "widget_color"],
  "settings": { "...": "..." },
  "locked": { "...": "..." }
}

Plans

Each setting needs its own plan, the same as in the dashboard. For example, hiding the Asyntai branding needs the Pro plan, and voice input needs Standard.

Plan needed Configurações Examples
Any paid plan 25 widget_color, ai_support_name, initial_message
Starter e acima 22 profile_picture, conversation_starters_enabled
Standard e acima 25 speech_to_text_enabled, image_vision_enabled, escalation_enabled
Pro 6 hide_branding, widget_style

If you send a setting your plan does not allow, the whole request is refused with code 403 and nothing is saved. The same happens if any value is wrong, for example a colour that is not a hex code. Your settings never end up half changed.

GET PUT /websites/{id}/instructions/

Read or replace the AI instructions for one website. These are the rules that tell the assistant who it is, what it may say, and what it must not say. They are the same instructions you edit in the dashboard.

Reading

{
  "success": true,
  "instructions": "You are the support agent for Acme Tools...",
  "characters": 1979,
  "version": 7,
  "mode": "instructions",
  "ask_questions": true,
  "generation_status": "completed",
  "being_edited_by": null
}

Replacing

A PUT request replaces the whole text, the same as saving in the dashboard. There is no append mode. To add a paragraph, read the instructions, add your text, then write it back.

curl -X PUT https://asyntai.com/api/v1/websites/42/instructions/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instructions": "You are the support agent for Acme Tools...", "version": 7}'

Corpo da Requisição

Campo Tipo Descrição
instructions string Required. The complete new text. It replaces everything that was there.
version number Optional but recommended. The version you read. If somebody changed the instructions since then, your write is refused instead of overwriting their work.
mode string Optional. Either instructions or general.
ask_questions boolean Optional. Whether the assistant asks a follow-up question at the end of its answers.
force boolean Optional, false by default. Needed only when your new text is less than half the length of the current text.

How your instructions are protected

Instructions can take hours to write, so a write can be refused to protect them:

Code Meaning
400 Your new text is less than half the length of the current text. This catches a script that sends empty or cut-off text over instructions somebody spent hours on. Send force as true if you meant it.
409 The instructions changed after you read them. Read them again, apply your change, then write.
423 Somebody is editing the instructions in the dashboard right now. The answer tells you who. Try again in a couple of minutes.

Every change also saves a copy of the previous text, so an earlier version can always be restored from the dashboard.

GET /conversations/

Recupere o histórico de conversa de uma sessão específica.

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
session_id string Sim O ID da sessão para recuperar o histórico
limit integer Não Máximo de mensagens a retornar (padrão: 50, máx: 100)

Resposta

{
  "success": true,
  "session_id": "user_123",
  "messages": [
    {
      "role": "user",
      "content": "What are your business hours?",
      "timestamp": "2024-01-15T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "timestamp": "2024-01-15T10:30:01Z",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Uma pergunta e a sua resposta são guardadas num único registo, por isso ambas têm o mesmo timestamp. Não subtraia uma da outra para medir a velocidade da resposta, porque o resultado é sempre zero. Use response_time_ms, que é o tempo real que a resposta demorou, em milissegundos.

sender_type é ai quando o chatbot respondeu e human quando um dos seus agentes assumiu a conversa. agent_name contém o nome apresentado desse agente.

Exemplo (cURL)

curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /sessions/

Liste suas sessões de chat recentes. Use isso para descobrir IDs de sessão, que você pode passar para /conversations/ para recuperar o histórico completo de mensagens.

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
limit integer Não Número de sessões recentes a retornar (padrão: 20, máx: 100)
website_id string Não Filtre sessões por um ID de site específico
source string Não Filtrar por origem da sessão: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier

Resposta

{
  "success": true,
  "sessions": [
    {
      "session_id": "session_abc123def",
      "source": "widget",
      "message_count": 5,
      "first_message": "What are your business hours?",
      "first_message_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T10:35:00Z",
      "first_response_time_ms": 1840.5,
      "first_human_response_at": null,
      "started_at": "2024-01-15T10:29:58Z",
      "ended_at": "2024-01-15T10:41:12Z",
      "taken_over_at": null,
      "website_domain": "example.com"
    }
  ]
}

Campos de data e hora para relatórios

Campo Descrição
started_at Quando o visitante abriu a conversa. Disponível apenas para sessões do widget, porque as sessões criadas através da API nunca abrem um widget.
first_message_at Quando a primeira mensagem da conversa foi guardada.
first_response_time_ms Quanto tempo demorou a primeira resposta, em milissegundos. Use isto para o tempo de primeira resposta.
first_human_response_at Quando um dos seus agentes enviou a primeira resposta. O valor é null quando o chatbot tratou de toda a conversa.
taken_over_at Quando um agente assumiu a conversa do chatbot.
last_message_at Quando a última mensagem da conversa foi guardada.
ended_at Quando o visitante saiu da conversa. Uma conversa não tem estado resolvido nem fechado, porque um visitante pode sempre voltar e fazer outra pergunta.

Todas as datas e horas estão em UTC e usam o formato ISO 8601. Não é possível alterar o fuso horário. Converta os valores na sua própria ferramenta de relatórios.

Exemplo (cURL)

curl "https://asyntai.com/api/v1/sessions/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

GET /leads/

Recuperar leads coletados — endereços de e-mail e números de telefone enviados por visitantes durante conversas de chat.

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
limit integer Não Número de leads a retornar (padrão: 50, máx: 100)
website_id string Não Filtrar leads por um ID de site específico

Resposta

{
  "success": true,
  "leads": [
    {
      "session_id": "session_abc123def",
      "email": "[email protected]",
      "phone": "+1234567890",
      "page_url": "https://example.com/pricing",
      "started_at": "2024-01-15T10:30:00Z"
    }
  ]
}
Campo Tipo Descrição
session_id string O ID da sessão de chat. Passe-o para /conversations/ para ver o histórico completo do chat.
email string ou null Endereço de e-mail fornecido pelo visitante, ou null se não coletado
phone string ou null Número de telefone fornecido pelo visitante, ou null se não coletado
page_url string ou null A URL da página onde o visitante estava conversando
started_at string Carimbo de data/hora ISO 8601 de quando a sessão de chat começou

Exemplo (cURL)

curl "https://asyntai.com/api/v1/leads/?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exemplo (Python)

import requests

response = requests.get(
    "https://asyntai.com/api/v1/leads/",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={"limit": 20}
)

leads = response.json()["leads"]
for lead in leads:
    print(f"{lead['email'] or ''} | {lead['phone'] or ''}")

GET /account/

Obtenha as informações da sua conta e estatísticas de uso.

Resposta

{
  "success": true,
  "account": {
    "email": "[email protected]",
    "plan": "starter",
    "messages_used": 150,
    "messages_limit": 2500
  }
}

Exemplo (cURL)

curl https://asyntai.com/api/v1/account/ \
  -H "Authorization: Bearer YOUR_API_KEY"

Vários sites? Os endpoints da base de conhecimento usam seu site principal por padrão. Se você tem vários sites, passe website_id para direcionar um específico. Você pode encontrar os IDs do seu site usando GET /websites/.

Limites diários de upload: Os uploads da base de conhecimento (texto, URL, planilha) estão sujeitos a um limite diário de caracteres baseado no seu plano. Isso se aplica ao total de conteúdo enviado em todos os endpoints da base de conhecimento por dia.

Plano Caracteres/dia
Starter300.000
Standard1.500.000
Pro6.000.000

GET /knowledge/

Liste suas entradas da base de conhecimento. Estas são as fontes de conteúdo que seu chatbot de IA usa para responder perguntas.

Parâmetros de Consulta

Parâmetro Tipo Obrigatório Descrição
limit integer Não Número de entradas a retornar (padrão: 50, máx: 100)
website_id string Não Filtre por ID do site (padrão: seu site principal)

Resposta

{
  "success": true,
  "entries": [
    {
      "id": "abc-123-def",
      "type": "text",
      "title": "Business Hours",
      "description": "Manual text content (150 words)",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ghi-456-jkl",
      "type": "url",
      "title": "About Us - Example",
      "description": "Content from https://example.com/about",
      "created_at": "2024-01-14T09:00:00Z"
    }
  ]
}

Exemplo (cURL)

curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /knowledge/text/

Adicione conteúdo de texto personalizado à sua base de conhecimento. A IA usará isso para responder perguntas dos visitantes.

Corpo da Requisição

{
  "title": "Return Policy",
  "content": "We offer a 30-day return policy on all items. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
  "website_id": "123"
}
Parâmetro Tipo Obrigatório Descrição
title string Sim Um título para esta entrada de conhecimento
content string Sim O conteúdo de texto (mínimo 10 caracteres)
website_id string Não Site de destino (padrão: seu site principal)

Resposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "Return Policy",
  "chunks_created": 1
}

Exemplo (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/text/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Return Policy", "content": "We offer a 30-day return policy..."}'

POST /knowledge/url/

Adicione uma página web à sua base de conhecimento. O conteúdo será buscado e extraído automaticamente.

Corpo da Requisição

{
  "url": "https://example.com/faq",
  "website_id": "123"
}
Parâmetro Tipo Obrigatório Descrição
url string Sim A URL para buscar o conteúdo
website_id string Não Site de destino (padrão: seu site principal)

Resposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "FAQ - Example",
  "url": "https://example.com/faq",
  "chunks_created": 5
}

Exemplo (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/url/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/faq"}'

POST /knowledge/spreadsheet/

Faça upload de uma planilha CSV ou Excel (.xlsx) para sua base de conhecimento. Cada linha se torna uma entrada de conhecimento separada, ideal para catálogos de produtos, listas de FAQ, tabelas de preços e diretórios.

Requisição

Envie como multipart/form-data (upload de arquivo), não JSON.

Parâmetro Tipo Obrigatório Descrição
file arquivo Sim Um arquivo .csv ou .xlsx. A primeira linha deve conter os cabeçalhos das colunas. Máximo de linhas por upload: Starter 500, Standard 2.000, Pro 10.000. Linhas excedentes são truncadas.
website_id string Não Site de destino (padrão: seu site principal)

Resposta

{
  "success": true,
  "id": "abc-123-def",
  "title": "products.csv",
  "rows_processed": 15,
  "chunks_created": 15
}

Exemplo (cURL)

curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

GET /knowledge/{id}/

Leia uma entrada da base de conhecimento, incluindo o texto guardado para ela. O valor id vem da resposta de GET /knowledge/.

O conteúdo é devolvido para as entradas que você adicionou: texto, ficheiros, folhas de cálculo, URLs individuais e vídeos. O rastreio de um site aparece na lista, mas as suas páginas não são devolvidas, porque a origem é o seu próprio site público. Nesse caso, content é null e o campo reason explica o motivo.

Resposta

{
  "success": true,
  "id": "abc-123-def",
  "type": "text",
  "title": "Business Hours",
  "description": "Manual text content (150 words)",
  "created_at": "2024-01-15T10:30:00Z",
  "chunks_count": 3,
  "content": "We are open Monday to Friday, 9am to 5pm...",
  "content_available": true,
  "char_count": 43
}

Exemplo (cURL)

curl "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

DELETE /knowledge/{id}/

Exclua uma entrada da base de conhecimento. O id pode ser encontrado na resposta do GET /knowledge/.

Resposta

{
  "success": true,
  "message": "Knowledge base entry deleted"
}

Exemplo (cURL)

curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Dica: Você também pode gerenciar webhooks na Configurações da API página sem escrever nenhum código.

GET /webhooks/

Liste seus webhooks registrados.

Resposta

{
  "success": true,
  "webhooks": [
    {
      "id": "abc-123-def",
      "url": "https://example.com/webhook",
      "events": ["message.received", "escalation.requested"],
      "is_active": true,
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Exemplo (cURL)

curl "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /webhooks/

Registre um novo webhook para receber notificações de eventos em tempo real.

Eventos Disponíveis

Evento Descrição
message.received Um visitante enviou uma mensagem e recebeu uma resposta
conversation.started Uma nova sessão de chat foi iniciada
escalation.requested A IA acionou um escalonamento para um atendente humano
takeover.started Um atendente humano assumiu uma sessão de chat

Corpo da Requisição

{
  "url": "https://example.com/webhook",
  "events": ["message.received", "escalation.requested"],
  "website_id": "123"
}
Parâmetro Tipo Obrigatório Descrição
url string Sim A URL HTTPS para receber requisições POST do webhook
events array Sim Lista de eventos para se inscrever (veja a tabela acima)
website_id string Não Site de destino (padrão: seu site principal)

Resposta

{
  "success": true,
  "webhook": {
    "id": "abc-123-def",
    "url": "https://example.com/webhook",
    "events": ["message.received", "escalation.requested"],
    "secret": "whsec_abc123...",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Verificando webhooks: Cada webhook inclui um secret (mostrado apenas na criação). Cada POST para sua URL inclui um X-Webhook-Signature header — um HMAC-SHA256 do corpo da requisição assinado com seu segredo.

Exemplo (cURL)

curl -X POST "https://asyntai.com/api/v1/webhooks/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/webhook", "events": ["message.received"]}'

DELETE /webhooks/{id}/

Exclua um webhook. O id pode ser encontrado na resposta do GET /webhooks/.

Resposta

{
  "success": true,
  "message": "Webhook deleted"
}

Exemplo (cURL)

curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
  -H "Authorization: Bearer YOUR_API_KEY"

Respostas de Erro

Todas as respostas de erro seguem este formato:

{
  "success": false,
  "error": "Error message describing what went wrong"
}
Código de Status Descrição
400 Requisição Inválida - Parâmetros inválidos ou campos obrigatórios ausentes
401 Não Autorizado - Chave da API inválida ou ausente
429 Muitas Requisições - Limite de mensagens atingido para seu plano
503 Serviço Indisponível - Serviço de IA temporariamente indisponível

Limites de Taxa

O uso da API é limitado pelo seu plano de assinatura:

  • Free: 100 mensagens/mês
  • Starter ($39/mês): 2.500 mensagens/mês
  • Standard ($139/mês): 15.000 mensagens/mês
  • Pro ($449/mês): 50.000 mensagens/mês

Precisa de Ajuda?

Se você tiver alguma dúvida ou encontrar problemas, entre em contato conosco em [email protected].