Acceso a la API #

Una API (Interfaz de Programación de Aplicaciones) es una forma en la que diferentes sistemas de software pueden comunicarse entre sí. La API de Your AI Connector le permite a usted (o a su desarrollador) crear contactos, enviar mensajes, gestionar listas y recibir mensajes entrantes desde canales personalizados automáticamente, todo ello sin utilizar el panel de control.

¿Por qué usar la API? Si desea conectar la aplicación a una herramienta que no tiene una integración nativa, o si necesita automatizar tareas repetitivas a gran escala, la API es la forma de hacerlo.

Generación de su clave API #

1. En la barra lateral izquierda, haga clic en Configuración (icono de engranaje).
2. En la barra lateral de Configuración, bajo el grupo Integraciones, haga clic en Clave de API.

3. Si aún no tienes una clave, haz clic en Generate API key.
4. Si ya tienes una, se mostrará enmascarada bajo Your key. Si tu clave lo permite, haz clic en Show para revelarla y, a continuación, en Copy para copiarla; verás un aviso de confirmación.
5. Guarda la clave en un lugar seguro; la necesitarás para cada solicitud a la API.

Miembros del equipo: la clave de API pertenece al propietario de la cuenta, por lo que si ha iniciado sesión como miembro invitado del equipo (incluido un administrador), la sección mostrará una nota en lugar de la clave. Inicie sesión como propietario de la cuenta para verla, copiarla o regenerarla; esto también se aplica a las claves con ámbito.

Dónde encontrarla: Clave de API es su propia sección bajo Configuración → Integraciones, separada de Webhooks. Si una guía o un colega le indica que busque la clave en “Webhooks”, busque en la sección de al lado.

URL base #

Todas las solicitudes a la API utilizan la siguiente dirección web base:

https://api.youraiconnector.com/v1/

Autenticación #

Cada solicitud debe incluir su clave de API para que la plataforma sepa que es usted. La forma más sencilla es añadirla al final de la dirección web:

https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY

También puede enviar la clave como un encabezado de solicitud en lugar de en la URL (recomendado para producción, para que la clave no termine en los registros del servidor):

X-API-Key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

Todas las solicitudes deben utilizar una conexión segura (HTTPS). Las solicitudes inseguras (HTTP) son rechazadas.

¿Busca las guías completas para desarrolladores? Esta página es una introducción rápida que cubre las operaciones más comunes. Para obtener guías completas paso a paso (todos los recursos, con ejemplos en cURL, JavaScript y Python), consulte Introducción a la API y la Referencia de la API.

Operaciones comunes de la API #

Crear un contacto #

Solicitud:

POST https://api.youraiconnector.com/v1/contacts?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "phoneNumber": "+15551234567",
  "email": "jane@example.com"
}

Campos obligatorios: un phoneNumber (con código de país) es siempre obligatorio para crear un contacto. Una dirección de correo electrónico por sí sola no es suficiente; una solicitud sin un número de teléfono válido será rechazada. El correo electrónico es opcional.

Respuesta:

{
  "success": true,
  "data": {
    "message": "Successfully created new contact",
    "contactId": "abc123xyz",
    "listsAdded": []
  }
}

Guarde data.contactId; lo necesitará para la llamada “Añadir un contacto a una lista”.

Añadir un contacto a una lista #

POST https://api.youraiconnector.com/v1/contacts/lists?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "contactId": "abc123xyz",
  "listId": "YOUR_LIST_ID"
}

Encuentra el ID de una lista en la aplicación en Contactos → Listas, desde el menú de la fila de la lista (Copiar ID de lista).

Actualizar un contacto #

PUT https://api.youraiconnector.com/v1/contacts/YOUR_CONTACT_ID?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customFields": { "company": "Acme Inc" }
}

Solo se modifican los campos que usted incluya. Esta es también la forma de cargar de forma masiva valores de campos personalizados después de una importación; consulte Campos personalizados, perfil de cliente potencial y notas. Detalles completos en la API de contactos.

Enviar un mensaje (Canal personalizado) #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "fromId": "external-contact-id",
    "customChannel": "my-channel",
    "body": "Hello Jane! Your order has been shipped.",
    "campaignId": "optional-campaign-id",
    "firstName": "Jane",
    "lastName": "Smith"
  }
}

Recibir mensajes entrantes (Canal personalizado) #

Acepte mensajes de sistemas externos como un canal personalizado. Así es como integraciones como GoHighLevel envían mensajes a Your AI Connector. Consulte Canales personalizados para obtener todos los detalles.

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY
Content-Type: application/json

{
  "customData": {
    "messageSid": "unique-message-id",
    "fromId": "external-contact-id",
    "toId": "your-user-id",
    "body": "Customer's message here",
    "channel": "custom",
    "status": "received"
  },
  "messageType": "text"
}

Resumen de operaciones disponibles #

Limitación de tasa (Rate Limiting) #

The API enforces rate limits to ensure platform stability. Exceeding your limit returns 429 Too Many Requests — back off and retry after the time indicated in the response headers. For high-volume use cases (bulk imports), use the built-in import feature or email hi@youraiconnector.com for guidance.

Mejores prácticas #

• Almacena tu clave de API de forma segura: usa un gestor de contraseñas o una configuración del lado del servidor, nunca código del lado del cliente que un visitante del navegador pueda leer.
• Incluye siempre el código de país en los números de teléfono (+1 para EE. UU., +44 para el Reino Unido, +31 para los Países Bajos).
• Gestiona los errores correctamente: comprueba los códigos de estado y lee los mensajes de error devueltos.
• Gestiona los duplicados: un número de teléfono duplicado devuelve { "success": false, "error_code": 409 } en lugar de un nuevo contacto. Busca primero el contacto si necesitas trabajar con él.
• Prueba con un conjunto de datos pequeño antes de realizar operaciones masivas.

Respuestas de error #

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Phone number must include a valid country code."
  }
}

Próximos pasos #

• Webhooks: recibe notificaciones en tiempo real desde la aplicación (una sección separada de tu clave de API).
• Conectar asistentes de IA (MCP): usa la misma clave de API para permitir que Claude gestione tu cuenta.
• Formularios de clientes potenciales de Facebook: usa la API con plataformas de automatización para captar clientes potenciales.
• Integración con GoHighLevel: un ejemplo completo de integración de API bidireccional.