Claves de integración
Las conexiones de voz llegan a tus agentes mediante una URL de WebSocket a la que podría llamar cualquier persona que la conozca. Las claves de integración hacen que VirtuAI acepte esas conexiones solo cuando incluyen una clave de tu espacio de trabajo.
Adminístralas en Manage > Integrations. Se necesita settings.manage.
Qué cubre la aplicación obligatoria
Sección titulada «Qué cubre la aplicación obligatoria»Con Key Enforcement activado, esta conexión debe incluir una clave válida:
| Extremo | Cómo enviar la clave |
|---|---|
| WebSocket de voz | Encabezado X-API-Key o el parámetro de consulta api_key |
El widget de voz web no envía una clave, así que no puede conectarse mientras la aplicación obligatoria está activada.
Todas las demás vías de entrada se verifican con el mecanismo propio de cada plataforma y no usan claves de integración, esté activada o no la aplicación obligatoria:
| Canal | Cómo lo verifica VirtuAI |
|---|---|
La X-Twilio-Signature que Twilio calcula con tu token de autenticación de Twilio |
|
| Google Chat | El token de Google, verificado con el número de tu proyecto de Google Cloud (GOOGLE_CHAT_PROJECT_NUMBER) |
| Slack | El secreto de firma de la app de Slack |
| Telegram | El secreto que VirtuAI genera cuando registras el webhook |
| Chat web | Un miembro del espacio de trabajo que haya iniciado sesión |
| A2A | Las credenciales propias del cliente, que se crean en la tarjeta de clientes de A2A en Settings |
Cuando editas un agente, su tarjeta Integration URLs marca el Voice WebSocket con Requires X-API-Key mientras la aplicación obligatoria está activada. Es la única URL que necesita una clave; los demás canales se verifican como se indica arriba.
Actívala
Sección titulada «Actívala»- Abre Integrations. En Create New Key, ingresa un nombre que indique dónde se usa la clave, por ejemplo,
Voice Prod, y selecciona Create. - Copia la clave desde Copy Your API Key. Se muestra una sola vez: VirtuAI almacena un hash, no la clave.
- Configura la conexión de voz para que envíe la clave.
- Activa Key Enforcement.
Los espacios de trabajo nuevos comienzan con la aplicación obligatoria activada. El interruptor establece el parámetro INTEGRATION_KEYS_ENFORCED del espacio de trabajo.
Cuando se rechaza una conexión
Sección titulada «Cuando se rechaza una conexión»Una conexión de voz sin una clave válida se rechaza antes de abrirse. La causa es una de estas:
- No se envió ninguna clave.
- El valor no es una clave de integración de VirtuAI.
- La clave no pertenece al espacio de trabajo de este agente o se revocó.
Si las solicitudes de Google Chat se rechazan con 401 · X-API-Key header is required, el espacio de trabajo tiene la aplicación obligatoria activada y no tiene un número de proyecto de Google Cloud. Configura GOOGLE_CHAT_PROJECT_NUMBER como se describe en Google Chat.
Administrar las claves
Sección titulada «Administrar las claves»La lista API Keys muestra cada clave con su nombre, su estado (Active o Revoked), su Prefix y cuándo se usó por última vez (Last used). El prefijo, como via_1a2b3c4d, es el inicio de la clave, de modo que puedes saber qué clave usa una conexión sin ver el secreto. Last used se actualiza, como máximo, cada cinco minutos.
- Un espacio de trabajo puede tener hasta 5 claves activas. Los nombres deben ser únicos entre las claves activas.
- Una clave solo funciona en el espacio de trabajo que la creó.
- Revoke se aplica de inmediato y no se puede deshacer.
Rotar una clave
Sección titulada «Rotar una clave»No hay un botón para rotar, así que rota una clave superponiendo dos:
- Crea una clave nueva.
- Actualiza la conexión de voz para que envíe la clave nueva y comprueba que siga conectándose.
- Revoca la clave anterior.
Revoca una clave en cuanto sospeches que se filtró y cada vez que se vaya alguien que la tenía.