Referência da API
Crie integrações personalizadas com a API REST do Asyntai
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 |
|---|---|
| Starter | 100.000 |
| Standard | 500.000 |
| Pro | 2.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.