Catálogo de aplicaciones de chat
Publica tu aplicación de chat en el catálogo para que otros la instalen sin configurarla desde cero, o instala una ya publicada.
Actualizado el . 5 min de lectura
Incluido en todos los planes. Ver precios
El catálogo de aplicaciones sirve para distribuir una aplicación de chat: la publicas una vez y quien la instale recibe una copia en su organización, con su propia clave y los scopes de chat ya puestos, sin configurarla desde cero. Funciona como el catálogo de AI Studio: una ficha publicada y, por cada instalación, una aplicación nueva.
En el producto está en Catálogo de aplicaciones, necesitas entrar con tu cuenta. Por debajo usa estos endpoints, que exigen la sesión de una persona (no una clave de API), el aplicativo Integraciones en el plan y estos permisos:
| Acción | Permiso |
|---|---|
| Publicar y retirar | Gestionar aplicaciones externas (INTEGRATIONS_APPS_MANAGE) |
| Explorar e instalar | Instalar aplicaciones del catálogo (INTEGRATIONS_APPS_INSTALL) |
De publicar a usar una aplicación del catálogo
Catálogo de aplicaciones
Publica la ficha
Quien tiene «Gestionar aplicaciones externas» publica una aplicación de chat de su organización.Si no: 400 si la aplicación no tiene scopes de chat.
Catálogo de aplicaciones
Instala la aplicación
Otra organización, con «Instalar aplicaciones del catálogo», recibe una copia con su propia clave y los scopes de chat.Guarda la clave y el secreto
Se muestran una sola vez, en la respuesta de la instalación.Panel del canal › Apps
La copia nace sin ningún canal: un responsable le abre cada uno.
Qué se puede publicar
Solo aplicaciones de chat: la aplicación tiene que tener al menos un scope chat:*; si no, la publicación responde 400. Cómo se asignan está en Scopes y acceso por canal.
Una ficha puede ser privada (solo la ve tu organización) o pública (la ven todas las organizaciones de UTILIA OS). Publicar en público solo lo puede hacer UTILIA; si lo pide otra organización, la ficha se publica igualmente, pero como privada.
Publicar
/api/app-catalog/listingsPublica una aplicación de chat de tu organización en el catálogo
- externalAppIdstringobligatorio
- La aplicación de tu organización que publicas.
- displayNamestringobligatorio
- Nombre en el catálogo, de 1 a 120 caracteres.
- categorystringPor defecto:
COMMUNICATION - Categoría.
- shortDescriptionstring
- Descripción corta, hasta 280 caracteres.
- descriptionstring
- Descripción larga, hasta 5.000 caracteres.
- iconUrlstring
- Dirección del icono, hasta 500 caracteres.
- tagsstring[]
- Etiquetas de búsqueda; se guardan en minúsculas y sin repetir.
- visibilitystringPor defecto:
PRIVATE - PRIVATE o PUBLIC (PUBLIC solo para UTILIA).
- acceptPolicybooleanobligatorio
- Tiene que ser true: aceptas la política del catálogo y confirmas que la aplicación no expone datos sensibles.
Cada aplicación tiene como mucho una ficha: volver a publicarla actualiza la existente. La ficha solo guarda los scopes de chat de la aplicación, no los demás.
| Código | Cuándo |
|---|---|
| 400 | acceptPolicy no es true, o la aplicación no tiene scopes de chat. |
| 403 | Falta el permiso de gestionar aplicaciones. |
| 404 | La aplicación no existe en tu organización. |
Retirar del catálogo
/api/app-catalog/listings/:idRetira del catálogo una ficha de tu organización
Responde { "success": true, "listingId": "..." }. Tu aplicación no se borra: sigue con su clave y sus scopes, y sigue funcionando en los canales donde tenga acceso. Solo desaparece la ficha, así que nadie más podrá instalarla.
Se pierde el registro de las instalaciones
Al retirar la ficha se borran también los registros de quién la instaló. Las copias que otras organizaciones ya tienen siguen funcionando con sus propias credenciales, pero pierden el vínculo con la ficha; si vuelves a publicarla, podrían instalarla otra vez.
Responde 403 sin el permiso de gestionar aplicaciones, y 404 si la ficha no existe o es de otra organización (aunque sea pública y la veas).
Explorar
/api/app-catalog/listingsLista las fichas que puedes ver
Devuelve las fichas de tu organización y las públicas aprobadas. Admite category, search (busca en nombre, descripción y etiquetas), limit (de 1 a 100, 20 por defecto) y offset.
/api/app-catalog/listings/:idDetalle de una ficha del catálogo
Una ficha privada de otra organización responde 404, sin revelar que existe.
Instalar
/api/app-catalog/listings/:id/installInstala una ficha del catálogo en tu organización
Instalar crea una aplicación nueva en tu organización, con su propia clave de API y los scopes de chat de la ficha, ya habilitada en la plataforma de chat.
- customNamestring
- Nombre de la aplicación instalada, hasta 100 caracteres. Si no lo pones, el de la ficha.
- acknowledgeDisclaimerbooleanobligatorio
- Tiene que ser true: aceptas el aviso de instalar una aplicación de terceros.
Respuesta (201):
- installIdstring
- Identificador de la instalación.
- listingIdstring
- Ficha instalada.
- installedAppIdstring
- La aplicación nueva de tu organización.
- apiKeyPlainTextstring
- Su clave de API. Solo se muestra esta vez.
- webhookSecretPlainTextstring
- El secreto para verificar sus avisos. Solo se muestra esta vez.
- scopesstring[]
- Scopes de chat con los que se creó.
La clave y el secreto se muestran una sola vez
Guárdalos en ese momento en un gestor de secretos. No se vuelven a mostrar; si los pierdes, tendrás que regenerarlos desde la ficha de la aplicación.
| Código | Cuándo |
|---|---|
| 400 | acknowledgeDisclaimer no es true, o tu organización ya la había instalado (solo se puede instalar una vez). |
| 403 | Falta el permiso de instalar aplicaciones. |
| 404 | La ficha no existe, o es privada de otra organización. |
Siguiente paso
La aplicación instalada no tiene acceso a ningún canal todavía. Para que pueda trabajar, una persona responsable tiene que darle acceso a cada canal, como se explica en Scopes y acceso por canal.