Volver al panel

Documentación

Aprende a usar Asyntai

Referencia API

Cree integraciones personalizadas con la API REST de Asyntai

Obtener clave API

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 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 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
Starter100,000
Standard500,000
Pro2,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 Un título para esta entrada de conocimiento
content string 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 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 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 La URL HTTPS para recibir solicitudes POST del webhook
events matriz 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.