API de preguntas frecuentes (FAQs) #

Las preguntas frecuentes (FAQs) son las entradas de preguntas y respuestas que utiliza tu bot de IA al responder a los clientes. Cada FAQ pertenece a tu cuenta y puede vincularse a una o más campañas, de modo que la misma respuesta pueda reutilizarse en cualquier lugar donde sea relevante. La API de FAQs te permite gestionar esa biblioteca mediante programación: crear, actualizar, importar de forma masiva, reordenar y vincular FAQs a campañas desde tu propio código.

Todos los endpoints a continuación son relativos a la URL base https://api.youraiconnector.com/v1. Cada solicitud debe estar autenticada; consulta Acceso a la API y Autenticación. El acceso a la API es una función de pago; sin ella, las solicitudes se rechazan con un 403.

Cómo utiliza el bot una FAQ: Cuando creas o cambias una FAQ, la plataforma prepara sus datos de búsqueda (utilizados para hacer coincidir la FAQ con las preguntas entrantes) en segundo plano. Esto suele completarse en unos pocos segundos, tras lo cual el bot comienza a utilizar la entrada automáticamente.

El objeto FAQ #

Cada FAQ que devuelve la API tiene esta estructura:

Los campos que puedes establecer son: question, answer, is_active, is_global, category, tags y order_index. La plataforma gestiona todo lo demás (datos de búsqueda, recuentos de uso, marcas de tiempo); cualquier otro campo en el cuerpo de tu solicitud será ignorado.

Listar FAQs #

GET /faqs

Devuelve las FAQs de tu cuenta, empezando por las más recientes. Opcionalmente, filtra por una sola campaña o por estado activo.

Parámetros de consulta

cURL

curl "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs?campaign_id=campaign123&limit=50",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();
console.log(data.faqs, data.next_cursor);

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs",
    params={"campaign_id": "campaign123", "limit": 50},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()
print(data["faqs"], data["next_cursor"])

Respuesta

{
  "success": true,
  "faqs": [
    {
      "id": "aBcD1234eFgH5678",
      "question": "How long does shipping take?",
      "answer": "Standard shipping takes 3-5 business days.",
      "category": "shipping",
      "tags": ["logistics", "delivery"],
      "is_active": true,
      "is_global": false,
      "usage_count": 12,
      "order_index": 0,
      "campaign_ids": ["campaign123"],
      "created_at": "2026-01-01T12:00:00.000Z",
      "updated_at": "2026-01-02T08:30:00.000Z"
    }
  ],
  "next_cursor": "aBcD1234eFgH5678"
}

Cuando next_cursor es null, no hay más resultados.

Obtener una pregunta frecuente #

GET /faqs/{faqId}

Devuelve una única pregunta frecuente por su ID.

cURL

curl "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const { faq } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
faq = res.json()["faq"]

Respuesta

{
  "success": true,
  "faq": {
    "id": "aBcD1234eFgH5678",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"],
    "is_active": true,
    "is_global": false,
    "usage_count": 12,
    "order_index": 0,
    "campaign_ids": ["campaign123"],
    "created_at": "2026-01-01T12:00:00.000Z",
    "updated_at": "2026-01-02T08:30:00.000Z"
  }
}

Crear una pregunta frecuente #

POST /faqs

Crea una nueva pregunta frecuente y la vincula a una campaña.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "question": "How long does shipping take?",
    "answer": "Standard shipping takes 3-5 business days.",
    "category": "shipping",
    "tags": ["logistics"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    question: "How long does shipping take?",
    answer: "Standard shipping takes 3-5 business days.",
    category: "shipping",
    tags: ["logistics"],
  }),
});
const { faq_id } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "tags": ["logistics"],
    },
)
faq_id = res.json()["faq_id"]

Respuesta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Actualizar una pregunta frecuente #

PUT /faqs/{faqId}

Actualiza parcialmente una pregunta frecuente. Solo se modifican los campos editables proporcionados; todo lo demás mantiene su valor actual. Cambiar question o answer actualiza automáticamente los datos de búsqueda de la pregunta frecuente en segundo plano.

Si envía question o answer, deben ser cadenas no vacías. Si no se envían campos editables reconocidos, se devuelve un 400.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_active": false }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
  {
    method: "PUT",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ is_active: false }),
  }
);
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"is_active": False},
)
data = res.json()

Respuesta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678"
}

Eliminar una pregunta frecuente #

DELETE /faqs/{faqId}

Elimina permanentemente una pregunta frecuente. Opcionalmente, pase campaign_id como parámetro de consulta para eliminar también la pregunta frecuente de la lista de preguntas frecuentes de esa campaña.

Parámetros de consulta

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678?campaign_id=campaign123",
  { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.delete(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678",
    params={"campaign_id": "campaign123"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{
  "success": true
}

Eliminación masiva de preguntas frecuentes #

POST /faqs/bulk-delete

Elimina hasta 500 preguntas frecuentes en una sola solicitud. Cuando se proporciona campaign_id, las preguntas frecuentes eliminadas también se retiran de la lista de preguntas frecuentes de esa campaña.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/bulk-delete?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/bulk-delete", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    faq_ids: ["faqId1", "faqId2"],
    campaign_id: "campaign123",
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/bulk-delete",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"faq_ids": ["faqId1", "faqId2"], "campaign_id": "campaign123"},
)
data = res.json()

Respuesta

{
  "success": true,
  "deleted_count": 2
}

Preguntas frecuentes sobre importación #

POST /faqs/import

Importa en bloque hasta 500 preguntas frecuentes y las vincula todas a una campaña. Los elementos cuyo question coincida con una pregunta frecuente existente en su biblioteca (sin distinguir entre mayúsculas y minúsculas) actualizan dicha pregunta frecuente en lugar de crear un duplicado.

Consejo de rendimiento: La búsqueda de duplicados analiza toda su biblioteca de preguntas frecuentes, por lo que las bibliotecas muy grandes ralentizan las importaciones. Es preferible realizar menos importaciones de mayor tamaño que muchas pequeñas.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/import?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "faqs": [
      { "question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide." },
      { "question": "What is your return policy?", "answer": "You can return any item within 30 days." }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/import", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    faqs: [
      {
        question: "Do you ship internationally?",
        answer: "Yes, we ship to most countries worldwide.",
      },
      {
        question: "What is your return policy?",
        answer: "You can return any item within 30 days.",
      },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/import",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "faqs": [
            {"question": "Do you ship internationally?", "answer": "Yes, we ship to most countries worldwide."},
            {"question": "What is your return policy?", "answer": "You can return any item within 30 days."},
        ],
    },
)
data = res.json()

Respuesta

{
  "success": true,
  "faq_ids": ["aBcD1234eFgH5678", "iJkL9012mNoP3456"],
  "imported_count": 2
}

faq_ids son los ID de las preguntas frecuentes creadas o actualizadas, en el orden en que los proporcionó.

Reordenar preguntas frecuentes #

POST /faqs/reorder

Establece el orden de visualización de las preguntas frecuentes de una campaña. Proporcione la lista completa de los ID de las preguntas frecuentes en el orden deseado; la posición de cada pregunta frecuente se actualiza para coincidir con su lugar en la matriz.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/reorder?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign123",
    "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/reorder", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaign_id: "campaign123",
    ordered_faq_ids: ["faqId2", "faqId1", "faqId3"],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/reorder",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign123",
        "ordered_faq_ids": ["faqId2", "faqId1", "faqId3"],
    },
)
data = res.json()

Respuesta

{
  "success": true
}

Si la campaña o cualquiera de los ID de las preguntas frecuentes no se encuentran en su cuenta, la solicitud devuelve 404 One or more FAQs were not found.

Vincular una pregunta frecuente a una campaña #

POST /faqs/{faqId}/link

Vincula una pregunta frecuente existente a una campaña adicional. Una pregunta frecuente puede ser compartida por cualquier número de campañas, por lo que la misma respuesta solo necesita mantenerse una vez.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/link",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Respuesta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Desvincular una FAQ de una campaña #

POST /faqs/{faqId}/unlink

Elimina una FAQ de una campaña sin borrar la FAQ en sí. La FAQ permanece en su biblioteca y sigue vinculada a cualquier otra campaña.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "campaign_id": "campaign456" }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ campaign_id: "campaign456" }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/unlink",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"campaign_id": "campaign456"},
)
data = res.json()

Respuesta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "campaign_id": "campaign456"
}

Reconstruir los datos de búsqueda de una FAQ #

POST /faqs/{faqId}/rebuild-embeddings

Pone en cola una reconstrucción de los datos que utiliza el bot de IA para encontrar esta FAQ (sus datos de búsqueda semántica y por palabras clave). Esto es útil si una FAQ no aparece en las respuestas como se esperaba. La reconstrucción se ejecuta en segundo plano y suele completarse en unos segundos; es posible que la FAQ se excluya temporalmente de las respuestas de la IA mientras se reconstruye.

Este endpoint devuelve 202 Accepted porque el trabajo continúa después de que se envía la respuesta. El status es siempre "processing": vuelva a consultar la FAQ más tarde si necesita confirmar que se ha completado.

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
  { method: "POST", headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/rebuild-embeddings",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{
  "success": true,
  "faq_id": "aBcD1234eFgH5678",
  "status": "processing"
}

Gestión de preguntas frecuentes asistida por IA #

Los endpoints a continuación van más allá del CRUD simple: llaman a las mismas herramientas de asistencia por IA que utiliza el editor de preguntas frecuentes del panel de control, lo que permite encontrar duplicados, generar entradas a partir de un documento y relacionar preguntas frecuentes con tareas abiertas de brechas de conocimiento. Los cuerpos de las solicitudes en este conjunto utilizan nombres de campo camelCase (campaignId, taskId, sourceIds…), que coinciden con las estructuras de solicitud de la propia aplicación, en lugar de los snake_case utilizados en otras partes de esta página; copie los ejemplos a continuación en lugar de intentar adivinar un nombre de campo.

Bifurcar una pregunta frecuente en una copia exclusiva para una campaña #

POST /faqs/{faqId}/fork-for-campaign

Crea una nueva pregunta frecuente que es una copia de una existente, limitada a una sola campaña, y vuelve a vincular esa campaña a la nueva copia en lugar de a la original. Utilice esto cuando desee personalizar una respuesta para una campaña sin cambiarla en todos los demás lugares donde se utiliza la pregunta frecuente original. La pregunta frecuente original permanece en su lugar; solo pierde el enlace de esta campaña.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_id": "campaign456",
    "question": "How long does shipping take to the EU?",
    "answer": "For EU orders, shipping takes 7-10 business days."
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      campaign_id: "campaign456",
      question: "How long does shipping take to the EU?",
      answer: "For EU orders, shipping takes 7-10 business days.",
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/aBcD1234eFgH5678/fork-for-campaign",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaign_id": "campaign456",
        "question": "How long does shipping take to the EU?",
        "answer": "For EU orders, shipping takes 7-10 business days.",
    },
)
data = res.json()

Respuesta — 201 Created

{
  "success": true,
  "faq_id": "nEwFaQiD9012mNoP",
  "campaign_id": "campaign456",
  "original_faq_id": "aBcD1234eFgH5678"
}

Encontrar preguntas frecuentes casi duplicadas #

POST /faqs/dedupe

Inicia un trabajo en segundo plano que escanea su biblioteca de preguntas frecuentes en busca de entradas casi duplicadas o superpuestas y las fusiona o elimina cuando tiene confianza en el resultado. Es útil después de una importación masiva o después de que varias rondas de preguntas frecuentes generadas por IA hayan dejado la biblioteca con superposiciones. Solo se puede ejecutar un trabajo de deduplicación por cuenta a la vez; iniciar un segundo mientras un trabajo aún se está ejecutando devuelve 409.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={},
)
data = res.json()

Respuesta — 202 Accepted

{
  "success": true,
  "job_id": "dedupJob_aBc123"
}

El trabajo se ejecuta en segundo plano y normalmente tarda unos minutos en una biblioteca grande. No hay un endpoint de estado independiente; vuelva a consultar GET /faqs después de una breve espera para ver qué ha cambiado. Cuando termine de revisar el resultado, llame al endpoint de descartar a continuación para borrarlo.

Descartar un resultado de verificación de duplicados #

POST /faqs/dedupe/dismiss

Borra el trabajo de deduplicación finalizado para que deje de mostrarse como un resultado activo. Es idempotente: es seguro llamarlo incluso si no hay nada que descartar. Devuelve 409 si el trabajo aún está queued o processing (no puede descartar una ejecución que no ha terminado).

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/dedupe/dismiss", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/dedupe/dismiss",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{ "success": true }

Generar preguntas frecuentes a partir de documentos cargados #

POST /faqs/generate-from-documents

Lee uno o más documentos que ya se encuentren en el almacenamiento de archivos de su cuenta y hace que la IA redacte preguntas frecuentes a partir de su contenido, comparando los borradores con su biblioteca existente para reutilizar o actualizar entradas en lugar de crear duplicados. Los resultados no se escriben de inmediato; se almacenan como un conjunto de cambios pendientes en la campaña para que usted los revise, y luego se aplican (o descartan) con Aplicar cambios de preguntas frecuentes revisados a continuación. Esto consume créditos, ya que es una pasada de generación de IA sobre el texto del documento.

Este endpoint no transporta el archivo: storagePath debe apuntar a un archivo que ya esté en su propia carpeta de cargas (users/{your user id}/uploads/), siguiendo la misma convención que Importar un documento cargado en la API de la Base de conocimientos.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/generate-from-documents?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "uploadedFiles": [
      { "storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/generate-from-documents", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    uploadedFiles: [
      { storagePath: "users/abc123uid/uploads/handbook.pdf", fileName: "handbook.pdf", mimeType: "application/pdf" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/generate-from-documents",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "uploadedFiles": [
            {"storagePath": "users/abc123uid/uploads/handbook.pdf", "fileName": "handbook.pdf", "mimeType": "application/pdf"},
        ],
    },
)
data = res.json()

Respuesta — 202 Accepted

{
  "success": true,
  "faqCount": 6,
  "reusedCount": 2,
  "modifiedCount": 1,
  "newCount": 3
}

faqCount es el número total de cambios propuestos a la espera de revisión; reusedCount, modifiedCount y newCount desglosan eso en preguntas frecuentes que coincidieron con una entrada existente sin cambios, aquellas que la IA propone editar y las completamente nuevas. Los archivos cargados se eliminan del almacenamiento una vez que finaliza el procesamiento, independientemente de si tiene éxito o no.

Aplicar cambios de preguntas frecuentes revisados #

POST /faqs/apply-optimization

Aplica (o descarta) un conjunto pendiente de cambios de preguntas frecuentes propuestos por la IA, del tipo producido por Generar preguntas frecuentes a partir de documentos arriba, o por la revisión de optimización de preguntas frecuentes del panel de control. Usted elige exactamente qué cambios propuestos aceptar; todo lo que no mencione se deja intacto (un cambio omitido nunca se trata como un rechazo que elimine algo).

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/apply-optimization?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "campaignId": "campaign123",
    "acceptedChanges": [
      { "action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days." },
      { "action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId" }
    ]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/apply-optimization", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    campaignId: "campaign123",
    acceptedChanges: [
      { action: "create_new", question: "Do you ship to the EU?", answer: "Yes, EU shipping takes 7-10 business days." },
      { action: "remove", faq_ref_path: "users/abc123uid/faqs/oldFaqId" },
    ],
  }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/apply-optimization",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "campaignId": "campaign123",
        "acceptedChanges": [
            {"action": "create_new", "question": "Do you ship to the EU?", "answer": "Yes, EU shipping takes 7-10 business days."},
            {"action": "remove", "faq_ref_path": "users/abc123uid/faqs/oldFaqId"},
        ],
    },
)
data = res.json()

Respuesta

{
  "success": true,
  "message": "Applied 2 FAQ changes",
  "faq_count": 7
}

faq_count es el recuento total de preguntas frecuentes vinculadas de la campaña (o del Agente) después de la aplicación. Si no había ningún conjunto de cambios pendiente que aplicar, la respuesta es { "success": true, "message": "No pending FAQ changes to apply" }.

Encontrar preguntas frecuentes similares a una tarea #

POST /faqs/similar-for-task

Clasifica su biblioteca de preguntas frecuentes por relevancia respecto a la pregunta de una tarea de brecha de conocimiento; es la misma búsqueda que utiliza el selector “Usar una pregunta frecuente existente” del panel de control. Solo lectura. taskId debe apuntar a una tarea de tipo faq_update.

Este endpoint siempre responde 200, incluso ante un fallo esperado como una tarea desconocida; compruebe success en el cuerpo en lugar del estado HTTP.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/similar-for-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "limit": 10 }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/similar-for-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", limit: 10 }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/similar-for-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "limit": 10},
)
data = res.json()

Respuesta

{
  "success": true,
  "data": {
    "task_id": "task789",
    "matches": [
      {
        "faq_id": "aBcD1234eFgH5678",
        "question": "How long does shipping take?",
        "answer": "Standard shipping takes 3-5 business days.",
        "category": "shipping",
        "created_at": "2026-01-01T12:00:00.000Z",
        "similarity": 0.81,
        "embedding_similarity": 0.81,
        "keyword_similarity": 0.6,
        "bm25_score": 4.2,
        "distance": 0.19
      }
    ]
  }
}

Las coincidencias se ordenan por similarity (coincidencia semántica cuando está disponible, superposición de palabras clave en caso contrario), primero las mejores. En un fallo leve, la forma es { "success": false, "error": "...", "error_code": 404 }; error_code refleja lo que sería normalmente el estado HTTP.

Resolver una tarea con una FAQ existente #

POST /faqs/resolve-task

Resuelve una tarea de brecha de conocimiento vinculándola a una FAQ que ya tiene (en lugar de escribir una nueva), envía la respuesta de esa FAQ al contacto que provocó la brecha y marca la tarea como completada. Utilice esto después de que Buscar FAQs similares a una tarea encuentre una FAQ existente que ya cubra la pregunta.

Al igual que el endpoint anterior, este siempre responde 200; compruebe success en el cuerpo.

Campos de la solicitud

cURL

curl -X POST "https://api.youraiconnector.com/v1/faqs/resolve-task?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskId": "task789", "faqId": "aBcD1234eFgH5678" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/faqs/resolve-task", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ taskId: "task789", faqId: "aBcD1234eFgH5678" }),
});
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/faqs/resolve-task",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"taskId": "task789", "faqId": "aBcD1234eFgH5678"},
)
data = res.json()

Respuesta

{
  "success": true,
  "data": {
    "task_id": "task789",
    "faq_id": "aBcD1234eFgH5678",
    "follow_up_status": "published"
  }
}

follow_up_status le indica qué sucedió con el seguimiento del contacto: published (enviado de inmediato), queued (la IA ya estaba respondiendo a ese contacto, por lo que se enviará a continuación), skipped_no_contact (la tarea no tiene un contacto vinculado) o skipped_no_campaign (no hay ninguna campaña a través de la cual enviarlo).

Errores de la API de preguntas frecuentes #

Los endpoints de preguntas frecuentes devuelven el sobre de error estándar:

{
  "success": false,
  "error": "FAQ not found"
}

Los códigos compartidos que puede devolver cualquier endpoint — 401, 403 (su plan no incluye acceso a la API), 429 (límite de tasa) y 500 — se enumeran con orientación sobre reintentos en Errores y paginación.

POST /faqs/similar-for-task y POST /faqs/resolve-task son las dos excepciones en esta página: responden 200 incluso ante un fallo esperado (tarea desconocida, tipo de tarea incorrecto) y colocan el estado real en el error_code del cuerpo; consulte cada endpoint anterior.

Relacionado #

• API de campañas: las campañas a las que están vinculadas sus FAQs.
• API de base de conocimientos: importe sitios web y documentos a FAQs automáticamente y agrupe FAQs en grupos de conocimiento reutilizables.
• Acceso a la API: genere su clave de API.
• Autenticación: todas las formas de proporcionar su clave.