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.

Claves con ámbito: claves adicionales para una tarea específica #

Su clave principal puede hacerlo todo, por lo que no es la clave que debe entregar a un informe, un panel de control de cliente o una configuración independiente de entorno de pruebas y desarrollo. Para ello, cree claves con ámbito en la tarjeta Claves con ámbito, en la misma sección Clave de API debajo de Su clave:

1. Haga clic en Nueva clave.
2. Asígnele un Nombre que pueda reconocer más tarde, por ejemplo, “Sandbox” o “Panel de control del cliente Acme”.
3. En Qué puede ver, marque solo las áreas que necesite.
4. En Qué puede hacer, deje marcada la opción Solo lectura a menos que la herramienta deba realizar cambios. Una clave que puede realizar cambios puede enviar mensajes y editar su configuración.
5. Opcionalmente, establezca Solicitudes por minuto (su propio límite, para que nunca ralentice sus otras integraciones) y una fecha de Caduca el.
6. Haga clic en Crear clave y cópiela inmediatamente. Las claves con ámbito se muestran solo una vez; si pierde una, revóquela y cree otra.

Puede crear tantas como necesite. Cada clave de la lista muestra cuándo se utilizó por última vez, y Revocar clave hace que deje de funcionar inmediatamente. Crear o revocar una clave con ámbito nunca afecta a su clave principal. Las opciones completas, incluidas las claves limitadas a subcuentas específicas, se encuentran en la página de claves de API de la referencia de la API.

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) #

La API aplica límites de tasa para garantizar la estabilidad de la plataforma. Exceder su límite devuelve 429 Too Many Requests: deténgase y vuelva a intentarlo después del tiempo indicado en los encabezados de respuesta. Para casos de uso de gran volumen (importaciones masivas), utilice la función de importación integrada o envíe un correo electrónico a hi@youraiconnector.com para obtener orientación.

Mejores prácticas #

• Almacene su clave de API de forma segura: utilice 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.
• Incluya 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).
• Gestione los errores correctamente: compruebe los códigos de estado y lea los mensajes de error devueltos.
• Gestione los duplicados: un número de teléfono duplicado devuelve { "success": false, "error_code": 409 } en lugar de un nuevo contacto, con el ID del contacto existente en contactId.
• Pruebe 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.