API de Puntos de Entrada #

Un Punto de Entrada es una regla de enrutamiento: “cuando esto sucede en este canal, entrega la conversación a este Agente”. Conectar un canal hace que los mensajes lleguen a la cuenta y crear un Agente te da algo que puede responder, pero ninguno de los dos decide quién responde al primer mensaje de un extraño. Los Puntos de Entrada sí lo hacen. Para el producto en sí, consulta la guía de Puntos de Entrada.

• URL base — https://api.youraiconnector.com/v1
• Autenticación — tu clave de API (consulta Autenticación)
• Errores y paginación — consulta Errores y paginación

Todos los ejemplos a continuación muestran la forma de consulta ?apiKey= en cURL y el encabezado X-API-Key en JavaScript y Python; cualquiera de los dos funciona en todos los endpoints.

En el explorador de API. Cada endpoint en esta página se encuentra en la especificación OpenAPI publicada, por lo que puede explorar sus campos exactos y ejecutar solicitudes en vivo en el explorador de API.

La única llamada que necesitan la mayoría de las integraciones #

Conecta un canal, crea un Agente y luego apunta el canal al Agente:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "whatsapp", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

Esa es toda la configuración para “este Agente responde WhatsApp”. Todo lo demás en esta página es para reglas más específicas (palabras clave, comentarios, nuevos seguidores), varios números en un canal y leer lo que está configurado.

Cómo se decide el enrutamiento #

Cuando llega un mensaje, la plataforma recorre una escalera fija y el primer paso que decide gana:

1. Un humano ha tomado el control de la conversación — no IA.
2. El contacto ya está asignado a un Agente, manualmente o porque una conversación con ese Agente está en curso — el mismo Agente la mantiene. Los Puntos de Entrada nunca mueven una conversación existente; para entregar un chat a un Agente diferente, asígnalo (en la aplicación o con la acción de Automatizaciones).
3. El contacto está respondiendo a una difusión — el Agente de la difusión responde, o nadie si la difusión no tenía ninguno.
4. Un Punto de Entrada específico coincide. Las reglas de palabras clave superan a las reglas de comentarios, que superan a las reglas de seguidores. Entre dos reglas del mismo tipo, gana la que se haya actualizado más recientemente.
5. El valor predeterminado del canal para el canal en el que llegó el mensaje. Un valor predeterminado limitado al número específico al que escribió el contacto supera al valor predeterminado de todo el canal.
6. Nada coincidió — el mensaje llega a la bandeja de entrada de tu equipo y ningún asistente responde.

Dos cosas suavizan el paso 6. Una cuenta con exactamente un Agente activo y sin valor predeterminado configurado para el canal aún obtiene a ese Agente como respondedor, por lo que una cuenta nueva que conecta WhatsApp y envía un mensaje de prueba no recibe silencio. Ese límite nunca se aplica a un canal que tiene una regla de palabra clave (allí, un mensaje que no coincide con ninguna palabra clave se deja deliberadamente para un humano) y nunca anula un canal que configuraste como nadie (consulta Dejar un canal sin nadie que responda).

Si la escalera está activa para una cuenta, lo informa GET /entry-points/routing-status. Está activada para todas las cuentas hoy; la llamada existe para que una integración pueda verificar en lugar de asumir.

El objeto Punto de Entrada #

{
  "id": "ep3KmQ8vTzXr5nWd",
  "type": "keyword",
  "channels": ["whatsapp", "instagram"],
  "agent_id": "ag7HkQ2ZpLxR3mNb",
  "enabled": true,
  "match_config": {
    "keywords": ["pricing", "quote"]
  },
  "first_response_mode": null,
  "first_response_exact_text": null,
  "public_comment_reply_exact_text": null,
  "created_at": 1700000000000,
  "last_modified_at": 1700000000000
}

Tipos de reglas #

Una regla de palabra clave en un canal sin un valor predeterminado de canal también funciona como una puerta: los mensajes que no coinciden con ninguna de las palabras clave no reciben respuesta automática y simplemente llegan a su bandeja de entrada, incluso en una cuenta con un solo Agente.

Asignar un canal a un Agente #

PUT /entry-points/channel-defaults: hace que un Agente sea el encargado de responder a los nuevos contactos en un canal. Cualquier otro Agente configurado actualmente como predeterminado para ese canal se retira en la misma llamada, por lo que un canal siempre tiene exactamente un encargado de responder. Configurar al Agente que ya es el predeterminado no cambia nada.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ channel: "instagram", agent_id: "ag7HkQ2ZpLxR3mNb" }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"channel": "instagram", "agent_id": "ag7HkQ2ZpLxR3mNb"},
)
data = res.json()

Respuesta

{
  "success": true,
  "entry_point_id": "ep3KmQ8vTzXr5nWd",
  "disabled_entry_point_ids": ["epPrevious1234"]
}

entry_point_id es la regla vigente ahora; disabled_entry_point_ids enumera las reglas retiradas para dejar espacio (vacío cuando no había nada que reemplazar). Solo se ven afectados los contactos con los que nunca ha hablado; cualquier persona que ya esté en una conversación con un Agente mantiene a ese Agente.

Un 400 significa que falta channel o agent_id, el Agente pertenece a otra cuenta o phone_number no es uno de sus números conectados.

Ver quién responde a cada canal #

GET /entry-points/channel-defaults: todos los valores predeterminados de canal en la cuenta, del más nuevo al más antiguo, incluidos los retirados (enabled: false) y un canal configurado deliberadamente para que nadie responda (agent_id: ""). Filtre por enabled usted mismo para obtener la imagen actual.

cURL

curl "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/channel-defaults", {
  headers: { "X-API-Key": "YOUR_API_KEY" },
});
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/entry-points/channel-defaults",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": {},
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    },
    {
      "id": "epAEnhHoozpoGVze",
      "type": "channel_default",
      "channels": ["whatsapp"],
      "agent_id": "agRotterdamBranch",
      "enabled": true,
      "match_config": { "phone_numbers": ["+31685101091"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Esta es la lectura de toda la cuenta. Enumerar las reglas de un Agente con GET /agents/{agentId}/entry-points no puede mostrar un canal configurado para que nadie responda, porque esa regla no pertenece a ningún Agente.

Dejar un canal sin nadie que responda #

DELETE /entry-points/channel-defaults?channel=instagram: retira el valor predeterminado de todo el canal para un canal. El canal se nombra como un parámetro de consulta, no en el cuerpo. Agregue &phone_number=%2B31685101091 para borrar solo el valor predeterminado de ese número y permitir que el número vuelva a quien responda al canal.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram&apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/entry-points/channel-defaults?channel=instagram",
  { 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/entry-points/channel-defaults",
    params={"channel": "instagram"},
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{ "success": true, "disabled_entry_point_ids": ["ep3KmQ8vTzXr5nWd"] }

Es seguro repetir: borrar un canal que no tiene un valor predeterminado es un 200 con una lista vacía. Borrar significa desconfigurar, no silenciar: en una cuenta con exactamente un Agente activo, un canal no configurado sigue recurriendo a ese Agente. Para mantener la IA fuera de un canal por completo, seleccione Nadie responde para él en el panel Quién responde a las nuevas conversaciones de la aplicación (eso escribe un valor predeterminado explícito de “nadie” que el respaldo nunca anula), o pause al Agente con PATCH /agents/{agentId}/active.

Un Agente por número de WhatsApp #

El enrutamiento es por canal de forma predeterminada: todos sus números de WhatsApp comparten un encargado de responder. Con dos o más números conectados en WhatsApp Business o WhatsApp Web, un valor predeterminado puede limitarse a un solo número, por lo que una empresa con un número por sucursal o marca puede asignar a cada uno su propio Agente dentro de una misma cuenta.

Envíe phone_number con la llamada de configuración:

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/channel-defaults?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "whatsapp_web",
    "agent_id": "agRotterdamBranch",
    "phone_number": "+31685101091"
  }'

• El número debe ser uno de sus números conectados en ese canal, escrito tal como aparece en números conectados (E.164 con el +); cualquier otra cosa es un 400.
• La regla se almacena como un valor predeterminado del canal con match_config.phone_numbers: ["+31685101091"]. Un mensaje que llega a ese número va a su Agente; cualquier otro número sigue utilizando el valor predeterminado de todo el canal.
• Establecer o borrar el valor predeterminado de todo el canal no afecta a las reglas con ámbito de número, y viceversa. Borre la regla propia de un número con DELETE /entry-points/channel-defaults?channel=whatsapp_web&phone_number=%2B31685101091.
• Las respuestas siempre salen desde el número al que escribió el contacto, por lo que el contacto sigue hablando con el mismo número y el mismo Agente.

Añadir una regla más específica #

POST /agents/{agentId}/entry-points — crea una regla de palabra clave, comentario o seguidor (o un valor predeterminado de canal, aunque PUT /entry-points/channel-defaults es la mejor opción para eso porque retira al respondedor anterior por usted). El Agente en la ruta siempre gana: una regla nunca puede ser creada para un Agente diferente al que aparece en la URL.

cURL

curl -X POST "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "keyword",
    "channels": ["whatsapp", "instagram"],
    "match_config": { "keywords": ["pricing", "quote"] }
  }'

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "keyword",
      channels: ["whatsapp", "instagram"],
      match_config: { keywords: ["pricing", "quote"] },
    }),
  }
);
const data = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "type": "keyword",
        "channels": ["whatsapp", "instagram"],
        "match_config": {"keywords": ["pricing", "quote"]},
    },
)
data = res.json()

Respuesta (201)

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Una regla de comentario a mensaje directo (DM) que solo reacciona a los comentarios que dicen “LINK” en dos publicaciones específicas, espera dos minutos y envía un primer mensaje fijo:

{
  "type": "instagram_comment",
  "channels": ["instagram"],
  "match_config": {
    "keywords": ["LINK"],
    "post_ids": ["17895695668004550", "17841400008460056"],
    "delay_minutes": 2
  },
  "first_response_mode": "exact_text",
  "first_response_exact_text": "Hi {{first_name}}, here is the link you asked for: https://example.com/guide",
  "public_comment_reply_exact_text": "Sent you a DM!"
}

Deje keywords vacío para enviar un DM a todos los que comenten en las publicaciones vigiladas, y post_ids vacío para vigilar todas las publicaciones. Un 400 indica qué está mal: un type desconocido, un channels vacío, una regla de palabra clave sin palabras clave, o una regla de comentario que no lista su propio canal.

Listar las reglas de un Agente #

GET /agents/{agentId}/entry-points — las reglas que envían conversaciones a este Agente, de la más reciente a la más antigua: sus valores predeterminados de canal, reglas de palabra clave, reglas de comentario y reglas de seguidor. Las reglas retiradas también aparecen, con enabled: false.

cURL

curl "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch(
  "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/agents/ag7HkQ2ZpLxR3mNb/entry-points",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{
  "success": true,
  "entry_points": [
    {
      "id": "ep3KmQ8vTzXr5nWd",
      "type": "keyword",
      "channels": ["whatsapp", "instagram"],
      "agent_id": "ag7HkQ2ZpLxR3mNb",
      "enabled": true,
      "match_config": { "keywords": ["pricing", "quote"] },
      "created_at": 1700000000000,
      "last_modified_at": 1700000000000
    }
  ]
}

Cambiar una regla #

PUT /entry-points/{entryPointId} — cambia una regla. Envíe solo los campos que está cambiando; la configuración anidada puede abordarse elemento por elemento con una clave con puntos como "match_config.keywords". Siempre que el cambio afecte a type, channels o match_config, se vuelve a comprobar toda la regla, por lo que una edición parcial nunca puede dejar una regla inutilizable (cambiar type a keyword sin proporcionar palabras clave será rechazado). Enviar agent_id transfiere la regla a otro de sus Agentes; uno en blanco será rechazado. Los campos de propiedad e identidad se ignoran.

cURL

curl -X PUT "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "match_config": { "keywords": ["pricing", "quote", "demo"] } }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  method: "PUT",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ match_config: { keywords: ["pricing", "quote", "demo"] } }),
});
const data = await res.json();

Python

import requests

res = requests.put(
    "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"match_config": {"keywords": ["pricing", "quote", "demo"]}},
)
data = res.json()

Respuesta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Otras ediciones comunes: { "enabled": false } retira una regla sin eliminarla, y { "agent_id": "agOtherAgent" } la mueve a un Agente diferente. Un cuerpo vacío devuelve 400 con "No fields to update".

Eliminar una regla #

DELETE /entry-points/{entryPointId} — elimina la regla permanentemente. Nada más hace referencia a un Punto de entrada, por lo que no hay nada que separar primero.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd?apiKey=YOUR_API_KEY"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/entry-points/ep3KmQ8vTzXr5nWd", {
  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/entry-points/ep3KmQ8vTzXr5nWd",
    headers={"X-API-Key": "YOUR_API_KEY"},
)
data = res.json()

Respuesta

{ "success": true, "entry_point_id": "ep3KmQ8vTzXr5nWd" }

Para evitar que una regla se active pero mantenerla, establezca enabled en false en su lugar. Los valores predeterminados de canal, en particular, normalmente se retiran en lugar de eliminarse, que es lo que hace DELETE /entry-points/channel-defaults.

Comprobar que el enrutamiento está activo #

GET /entry-points/routing-status — devuelve si la jerarquía de Puntos de entrada decide quién responde en esta cuenta. Se puede leer con acceso de visualización, por lo que un compañero de equipo ve la misma respuesta que el propietario.

curl "https://api.youraiconnector.com/v1/entry-points/routing-status?apiKey=YOUR_API_KEY"

{ "success": true, "cutover_enabled": true }

Hoy en día está true en todas las cuentas. La llamada se mantiene para que una integración pueda verificar antes de decirle a alguien que su cambio de enrutamiento está activo en lugar de asumirlo.

Las llamadas más antiguas con forma de campaña #

Dos endpoints de antes de los Agentes siguen funcionando para cuentas organizadas en torno a campañas. Las nuevas integraciones deben utilizar las llamadas de valores predeterminados de canal anteriores.

• PUT /channel-routing/{channel} con { "campaignId": "cp5NbV8xQrT2wYzA" } — asigna un nombre a una campaña y el Agente de esa campaña se convierte en el encargado de responder del canal. { "campaignId": null } borra el canal. Una campaña solo de salida es rechazada porque no tiene comportamiento de entrada que ofrecer.
• POST /channel-routing/clear con { "channels": ["whatsapp", "instagram"] } — libera varios canales del Agente que los responde en una sola llamada, normalmente antes de dirigirlos a otro lugar. La respuesta enumera released_channels, los que realmente tenían un encargado de responder.

Ambos restablecen en lugar de silenciar: en una cuenta con exactamente un Agente activo, un canal liberado sigue recurriendo a ese Agente.

Errores de la API de Puntos de entrada #

Los endpoints de Punto de entrada devuelven el sobre de error estándar:

{
  "success": false,
  "error": "Entry point 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.

Próximos pasos #

• Puntos de entrada — el concepto, los tipos de reglas y el panel Quién responde a las nuevas conversaciones en la aplicación.
• API de Agentes de IA — cree y configure los Agentes a los que dirigen estas reglas.
• API de Canales — conecte los canales en sí.
• Automatización de comentario a mensaje directo — lo que hacen las reglas de comentarios una vez que se activan.