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

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.

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"

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.

Cuerpo de la solicitud

Campo Tipo Descripción
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.

Respuesta

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

Ejemplo (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.

Respuesta

{
  "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.

Ejemplo (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 Ajustes Examples
Any paid plan 25 widget_color, ai_support_name, initial_message
Desde el plan Starter 22 profile_picture, conversation_starters_enabled
Desde el plan Standard 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}'

Cuerpo de la solicitud

Campo Tipo Descripción
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/

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",
      "sender_type": "ai",
      "agent_name": null,
      "response_time_ms": 1840.5
    }
  ]
}

Una pregunta y su respuesta se guardan en un mismo registro, por lo que ambas llevan el mismo timestamp. No reste uno del otro para medir la velocidad de respuesta, porque el resultado siempre es cero. Use response_time_ms, que es el tiempo real que tardó la respuesta, en milisegundos.

sender_type es ai cuando respondió el chatbot y human cuando uno de sus agentes tomó el control del chat. agent_name contiene el nombre visible de ese agente.

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",
      "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 marca de tiempo para informes

Campo Descripción
started_at Cuándo abrió el visitante el chat. Solo está disponible para sesiones del widget, porque las sesiones creadas a través de la API nunca abren un widget.
first_message_at Cuándo se guardó el primer mensaje de la conversación.
first_response_time_ms Cuánto tardó la primera respuesta, en milisegundos. Use esto para el tiempo de primera respuesta.
first_human_response_at Cuándo envió uno de sus agentes la primera respuesta. El valor es null cuando el chatbot gestionó toda la conversación.
taken_over_at Cuándo tomó un agente el control del chat de manos del chatbot.
last_message_at Cuándo se guardó el último mensaje de la conversación.
ended_at Cuándo salió el visitante del chat. Un chat no tiene estado resuelto ni cerrado, porque un visitante siempre puede volver y hacer otra pregunta.

Todas las marcas de tiempo están en UTC y usan el formato ISO 8601. No se puede cambiar la zona horaria. Convierta los valores en su propia herramienta de informes.

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": "[email protected]",
      "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": "[email protected]",
    "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
Starter300,000
Standard1,500,000
Pro6,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 "[email protected]"

GET /knowledge/{id}/

Lee una entrada de la base de conocimiento, incluido el texto guardado para ella. El valor id procede de la respuesta de GET /knowledge/.

Se devuelve el contenido de las entradas que usted añadió: texto, archivos, hojas de cálculo, URLs individuales y vídeos. El rastreo de un sitio web aparece en la lista, pero sus páginas no se devuelven, porque la fuente es su propio sitio web público. En ese caso content es null y el campo reason explica el motivo.

Respuesta

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

Ejemplo (cURL)

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

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 [email protected].