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

A API do Asyntai permite integrar suporte ao cliente com IA em qualquer aplicação. Envie mensagens e receba respostas inteligentes treinadas no conteúdo do seu site e base de conhecimento.

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"

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"
    }
  ]
}

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",
      "website_domain": "example.com"
    }
  ]
}

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": "visitor@example.com",
      "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": "you@example.com",
    "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
Starter100.000
Standard500.000
Pro2.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 "file=@products.csv"

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 hello@asyntai.com.