Referencia API
Cree integraciones personalizadas con la API REST de Asyntai
Plan de pago requerido: El acceso a la API está disponible en los planes Starter, Standard y Pro. Ver precios
Descripción general
La API de Asyntai le permite integrar soporte al cliente con IA en cualquier aplicación. Envíe mensajes y reciba respuestas inteligentes entrenadas con el contenido de su sitio web y base de conocimiento.
Autenticación
Todas las solicitudes API requieren autenticación usando su clave API. Puede obtener su clave API desde la página de Configuración API.
Incluya su clave API en las solicitudes usando uno de estos métodos:
- Encabezado Authorization (recomendado):
Authorization: Bearer TU_CLAVE_API - Encabezado X-API-Key:
X-API-Key: TU_CLAVE_API
Mantenga su clave API en secreto. Cualquiera con su clave puede acceder a su cuenta a través de la API. Nunca la expongas en código del lado del cliente.
URL base
https://asyntai.com/api/v1/
Endpoints
POST /chat/
Envíe un mensaje y recibe una respuesta generada por IA.
Cuerpo de la solicitud
{
"message": "What are your business hours?",
"session_id": "user_123", // optional
"website_id": 1 // optional
}
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
message |
string | Sí | El mensaje del usuario para enviar a la IA |
session_id |
string | No | Identificador único de la conversación. Use el mismo session_id para mantener el historial de la conversación. |
website_id |
integer | No | ID de sitio web específico. Si no se proporciona, usa tu sitio web principal. |
Respuesta
{
"success": true,
"response": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
"session_id": "user_123"
}
Ejemplo (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"}'
Ejemplo (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"])
Ejemplo (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/
Lista todos los sitios web asociados a su cuenta.
Respuesta
{
"success": true,
"websites": [
{
"id": 1,
"name": "My Website",
"domain": "example.com",
"is_primary": true
}
]
}
Ejemplo (cURL)
curl https://asyntai.com/api/v1/websites/ \
-H "Authorization: Bearer YOUR_API_KEY"
GET /conversations/
Recupera el historial de conversación para una sesión específica.
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
session_id |
string | Sí | El ID de sesión para recuperar el historial |
limit |
integer | No | Máximo de mensajes a devolver (predeterminado: 50, máx.: 100) |
Respuesta
{
"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"
}
]
}
Ejemplo (cURL)
curl "https://asyntai.com/api/v1/conversations/?session_id=user_123&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /sessions/
Lista sus sesiones de chat recientes. Use esto para descubrir IDs de sesión, que luego puede pasar a /conversations/ para recuperar el historial completo de mensajes.
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
limit |
integer | No | Número de sesiones recientes a devolver (por defecto: 20, máx: 100) |
website_id |
string | No | Filtrar sesiones por un ID de sitio web específico |
source |
string | No | Filtrar por fuente de sesión: widget, api, whatsapp, instagram, messenger, gorgias, freshchat, zapier |
Respuesta
{
"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"
}
]
}
Ejemplo (cURL)
curl "https://asyntai.com/api/v1/sessions/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /leads/
Recuperar leads recopilados — direcciones de correo electrónico y números de teléfono enviados por visitantes durante conversaciones de chat.
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
limit |
integer | No | Número de leads a devolver (predeterminado: 50, máx: 100) |
website_id |
string | No | Filtrar leads por un ID de sitio web específico |
Respuesta
{
"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 | Descripción |
|---|---|---|
session_id |
string | El ID de sesión del chat. Páselo a /conversations/ para ver el historial completo del chat. |
email |
cadena o null | Dirección de correo electrónico proporcionada por el visitante, o null si no se recopiló |
phone |
cadena o null | Número de teléfono proporcionado por el visitante, o null si no se recopiló |
page_url |
cadena o null | La URL de la página donde el visitante estaba chateando |
started_at |
string | Marca de tiempo ISO 8601 de cuándo comenzó la sesión de chat |
Ejemplo (cURL)
curl "https://asyntai.com/api/v1/leads/?limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
Ejemplo (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/
Obtén la información de su cuenta y estadísticas de uso.
Respuesta
{
"success": true,
"account": {
"email": "you@example.com",
"plan": "starter",
"messages_used": 150,
"messages_limit": 2500
}
}
Ejemplo (cURL)
curl https://asyntai.com/api/v1/account/ \
-H "Authorization: Bearer YOUR_API_KEY"
¿Múltiples sitios web? Los endpoints de la base de conocimiento usan su sitio web principal por defecto. Si tiene múltiples sitios web, envíe website_id para seleccionar uno específico. Puedes encontrar tus IDs de sitio web usando GET /websites/.
Límites diarios de carga: Las cargas a la base de conocimiento (texto, URL, hoja de cálculo) están sujetas a un límite diario de caracteres según su plan. Esto se aplica al total de contenido cargado en todos los endpoints de la base de conocimiento por día.
| Plan | Caracteres/día |
|---|---|
| Starter | 100,000 |
| Standard | 500,000 |
| Pro | 2,000,000 |
GET /knowledge/
Lista las entradas de su base de conocimiento. Estos son los contenidos que su chatbot IA usa para responder preguntas.
Parámetros de consulta
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
limit |
integer | No | Número de entradas a devolver (predeterminado: 50, máx.: 100) |
website_id |
string | No | Filtrar por ID de sitio web (por defecto es su sitio web principal) |
Respuesta
{
"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"
}
]
}
Ejemplo (cURL)
curl "https://asyntai.com/api/v1/knowledge/?limit=10" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /knowledge/text/
Añada contenido de texto personalizado a su base de conocimiento. La IA usará esto para responder las preguntas de los visitantes.
Cuerpo de la solicitud
{
"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 | Requerido | Descripción |
|---|---|---|---|
title |
string | Sí | Un título para esta entrada de conocimiento |
content |
string | Sí | El contenido de texto (mínimo 10 caracteres) |
website_id |
string | No | Sitio web de destino (por defecto es su sitio web principal) |
Respuesta
{
"success": true,
"id": "abc-123-def",
"title": "Return Policy",
"chunks_created": 1
}
Ejemplo (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/
Añada una página web a su base de conocimiento. El contenido será obtenido y extraído automáticamente.
Cuerpo de la solicitud
{
"url": "https://example.com/faq",
"website_id": "123"
}
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
url |
string | Sí | La URL de la que obtener el contenido |
website_id |
string | No | Sitio web de destino (por defecto es su sitio web principal) |
Respuesta
{
"success": true,
"id": "abc-123-def",
"title": "FAQ - Example",
"url": "https://example.com/faq",
"chunks_created": 5
}
Ejemplo (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/
Suba un archivo CSV o Excel (.xlsx) a su base de conocimiento. Cada fila se convierte en una entrada de conocimiento separada, ideal para catálogos de productos, listas de preguntas frecuentes, tablas de precios y directorios.
Solicitud
Envía como multipart/form-data (carga de archivo), no JSON.
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
file |
archivo | Sí | Un archivo .csv o .xlsx. La primera fila debe ser encabezados de columna. Máximo de filas por carga: Starter 500, Standard 2,000, Pro 10,000. Las filas excedentes se truncan. |
website_id |
string | No | Sitio web de destino (por defecto es su sitio web principal) |
Respuesta
{
"success": true,
"id": "abc-123-def",
"title": "products.csv",
"rows_processed": 15,
"chunks_created": 15
}
Ejemplo (cURL)
curl -X POST "https://asyntai.com/api/v1/knowledge/spreadsheet/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "file=@products.csv"
DELETE /knowledge/{id}/
Elimina una entrada de la base de conocimiento. El id se puede encontrar en la respuesta de GET /knowledge/.
Respuesta
{
"success": true,
"message": "Knowledge base entry deleted"
}
Ejemplo (cURL)
curl -X DELETE "https://asyntai.com/api/v1/knowledge/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Consejo: También puede gestionar webhooks desde la Configuración API página sin escribir código.
GET /webhooks/
Lista sus webhooks registrados.
Respuesta
{
"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"
}
]
}
Ejemplo (cURL)
curl "https://asyntai.com/api/v1/webhooks/" \
-H "Authorization: Bearer YOUR_API_KEY"
POST /webhooks/
Registra un nuevo webhook para recibir notificaciones de eventos en tiempo real.
Eventos disponibles
| Evento | Descripción |
|---|---|
message.received |
Un visitante envió un mensaje y recibió una respuesta |
conversation.started |
Se inició una nueva sesión de chat |
escalation.requested |
La IA activó una transferencia a un agente humano |
takeover.started |
Un agente humano tomó el control de una sesión de chat |
Cuerpo de la solicitud
{
"url": "https://example.com/webhook",
"events": ["message.received", "escalation.requested"],
"website_id": "123"
}
| Parámetro | Tipo | Requerido | Descripción |
|---|---|---|---|
url |
string | Sí | La URL HTTPS para recibir solicitudes POST del webhook |
events |
matriz | Sí | Lista de eventos a los que suscribirse (ver tabla anterior) |
website_id |
string | No | Sitio web de destino (por defecto es su sitio web principal) |
Respuesta
{
"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"
}
}
Verificación de webhooks: Cada webhook incluye un secret (mostrado solo al crearlo). Cada POST a su URL incluye un encabezado X-Webhook-Signature — un HMAC-SHA256 del cuerpo de la solicitud firmado con su secreto.
Ejemplo (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}/
Elimina un webhook. El id se puede encontrar en la respuesta de GET /webhooks/.
Respuesta
{
"success": true,
"message": "Webhook deleted"
}
Ejemplo (cURL)
curl -X DELETE "https://asyntai.com/api/v1/webhooks/abc-123-def/" \
-H "Authorization: Bearer YOUR_API_KEY"
Respuestas de error
Todas las respuestas de error siguen este formato:
{
"success": false,
"error": "Error message describing what went wrong"
}
| Código de estado | Descripción |
|---|---|
400 |
Solicitud incorrecta - Parámetros no válidos o campos obligatorios faltantes |
401 |
No autorizado - Clave API inválida o faltante |
429 |
Demasiadas solicitudes - Límite de mensajes alcanzado para su plan |
503 |
Servicio no disponible - Servicio de IA temporalmente no disponible |
Límites de frecuencia
El uso de la API está limitado por su plan de suscripción:
- Free: 100 mensajes/mes
- Starter ($39/mes): 2,500 mensajes/mes
- Standard ($139/mes): 15,000 mensajes/mes
- Pro ($449/mes): 50,000 mensajes/mes
¿Necesita ayuda?
Si tiene alguna pregunta o encuentras problemas, contáctanos en hello@asyntai.com.