# Rainbow Extensions — Custo-Manifest

**Referencia S170 — abril 2026**
*Fuente: presentación S170 Roadmap + especificación funcional Rainbow custo-manifest*

---

## 1. Visión general

Las **Rainbow Extensions** (también llamadas *Custo-Manifest*) permiten integrar Rainbow Web/Desktop con el ecosistema de negocio de un cliente **sin código** — únicamente depositando un archivo JSON de configuración. Una extensión puede:

- reaccionar a un evento Rainbow (llamada entrante, saliente…);
- añadir un botón en una parte de la UI (lista de contactos, registro de llamadas, etc.);
- mostrar un contenido (Markdown, JSON, Adaptive Card) en una ubicación de Rainbow;
- o abrir una aplicación de terceros en un frame o en un navegador.

### Beneficios

- **No-code**: solo configuración JSON
- Aumenta la **productividad del usuario** (acciones de un clic, datos contextuales)
- **Habilitador de negocio** para los partners (integración con CRM, ticketing, domótica…)

### Tipos de interacción admitidos

| Tipo | Efecto |
|---|---|
| `commandType: "file"` | Lee un archivo — local en Desktop, o incluido en el ZIP del manifest en Web |
| `commandType: "rest"` | Llamada HTTP GET o POST a una API |
| Apertura web | Abre una URL en el navegador |
| Ejecución nativa (solo Desktop) | Lanza un `.exe` o un script local |

### Formatos de visualización admitidos

- **Markdown** (por defecto) — también puede extraerse del campo de una respuesta JSON mediante `displayJsonField`
- **Adaptive Card** (template + datos)

### Requisitos de licencia

Solo las extensiones de tipo **Event** se admiten con licencia **Essentials**.
Las demás extensiones requieren al menos una licencia **Business**.

### Web vs Desktop

Desde **S161**, el custo-manifest se migra progresivamente de Desktop a Web. A partir de **S170**, todas las extensiones están disponibles en Rainbow Web Y Desktop, **excepto la ejecución local de aplicaciones/scripts** (lanzar un `.exe` o un script), que sigue siendo exclusiva de Desktop. Para `commandType: "file"` en Web, el archivo debe estar incluido en el ZIP del manifest.

**Mobile** *(BETA S183)*: un primer paso hace disponible `on-main-window-actions` en Rainbow Mobile — ver §6.2.

---

## 2. Estructura del archivo manifest

El custo-manifest es un objeto JSON que respeta este esqueleto:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "<EXTENSION-POINT-KEY>": [
      {
        "name": "...",
        "command": {
          "url": "...",
          "params": "...",
          "commandType": "rest",
          "method": "GET"
        },
        "icon": "...",
        "responseType": "markdown"
      }
    ]
  }
}
```

### Reglas globales

- `version` debe valer `"2"`.
- `jsonType` debe valer `"Rainbow-custo-manifest"`. Este campo sirve para identificar, dentro de un ZIP, qué archivo JSON es el manifest.
- Cada clave de `extension-points` es un array (hasta **3 acciones** como máximo por punto de extensión).
- Cada acción contiene al menos un `name` (excepto los events, donde es opcional) y un objeto `command` válido.
- `defaultDevicesSupported` *(BETA S183)* — array opcional en la raíz del manifest: los clientes Rainbow destinatarios por defecto de todos los items (ver §6.2).

---

## 3. Lista de puntos de extensión

### 3.1 Events — eventos automáticos (sin visualización)

| Clave | Se dispara cuando… |
|---|---|
| `on-outgoing-pbx-call-actions` | Se inicia una llamada saliente |
| `on-incoming-pbx-call-actions` | Llega una llamada entrante |
| `on-answering-incoming-pbx-call-actions` | Se contesta una llamada entrante |
| `on-releasing-incoming-pbx-call-actions` | Se finaliza una llamada entrante |
| `on-makecall-insert-correlator` | En cada makecall — inserta un correlador (solo OXE) |

### 3.2 Buttons — botones clicables (con visualización opcional del resultado)

| Clave | Ubicación del botón |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up de llamada entrante |
| `on-call-log-list-actions` | Cada fila del registro de llamadas |
| `on-contact-list-actions` | Cada fila de la lista de contactos |
| `on-contact-detail-actions` | Panel de detalle de un contacto |
| `on-communication-card-actions` | Barra del gestor de llamadas |
| `on-bubble-actions` | Menú de propiedades de la burbuja |
| `on-bubble-conference-actions` | Menú de conferencia telefónica |
| `on-user-menu-actions` | Menú de usuario (Desktop / Web — no Teams) |

### 3.3 Displays — visualización automática de información

| Clave | Ubicación |
|---|---|
| `on-incoming-pbx-call-display-actions` | Inserción en el pop-up de llamada entrante |
| `on-contact-card-display-actions` | Inserción en el panel de detalle del contacto |
| `on-main-widget-display-actions` | Widget en el panel principal de Rainbow |
| `on-main-display-actions` | Mensaje en la webapp de Teams |
| `on-conversation-tab-actions` *(Novedad S179)* | Pestaña personalizada en el detalle de una conversación (P2P o conferencia) |

### 3.4 Frame display — aplicación WEB de terceros

| Clave | Descripción |
|---|---|
| `on-main-window-actions` | Muestra una aplicación WEB de terceros en un frame de Rainbow. Con `popout: true`, abre la aplicación en una ventana del navegador. |

---

## 4. Campos principales de una acción

| Campo | Posición | Descripción |
|---|---|---|
| `name` | raíz | Texto mostrado (título del botón/widget, etiqueta del menú). Obligatorio según el EP. |
| `icon` / `iconId` | raíz | Icono del botón (URL, `${custo.path}\…` o sprite integrado). Obligatorio para los botones icono. |
| `tooltip` | raíz | Texto del tooltip. Opcional. |
| `command` | raíz | Objeto de comando (ver §5). **Siempre obligatorio**. |
| `responseType` | raíz | `"markdown"` (por defecto), `"json"` o `"adaptiveCard"`. |
| Campos Adaptive Card | raíz | `adaptiveCardTemplate`, `adaptiveCardTemplateJsonField`, `adaptiveCardContentJsonField`, `adaptiveCardSubmitUrl` |
| `displayJsonField` | raíz | Nombre del campo que contiene el markdown a mostrar (cuando la respuesta es JSON) |
| `redirectUrl` *(BETA S183)* | raíz | **Events de llamada y botones** — plantilla de URL abierta en una nueva ventana del navegador una vez finalizada la llamada REST; requiere `responseType: "json"` (ver §10.1 y §10.2). |
| `markdownTemplate` *(BETA S183)* | raíz | **EPs de visualización y de botón** — plantilla Markdown mostrada tras la sustitución de las variables Rainbow y de `${response...}` (cuerpo JSON de la llamada REST); requiere `commandType: "rest"` y `responseType: "json"` (ver §8.4). |

### Tabla de referencia por EP

> Síntesis de las reglas: `name` mandatory/n/a, icon mandatory/n/a, commandType permitido, responseType permitido, etc.

| Extension Point | name | icon | commandType | responseType |
|---|---|---|---|---|
| `on-outgoing-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorio** con `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorio** con `redirectUrl` — BETA S183) |
| `on-answering-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorio** con `redirectUrl` — BETA S183) |
| `on-releasing-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatorio** con `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-button-actions` | "Button text" | n/a | `rest` | opcional |
| `on-contact-list-actions` | n/a | obligatorio | `rest`, `file` | opcional |
| `on-contact-detail-actions` | n/a | obligatorio | `rest`, `file` | opcional |
| `on-call-log-list-actions` | n/a | obligatorio | `rest`, `file` | opcional |
| `on-communication-card-actions` | "menu text" | obligatorio | `rest`, `file` | opcional |
| `on-bubble-actions` | "menu text" | obligatorio | `rest`, `file` | opcional |
| `on-bubble-conference-actions` | "menu text" | obligatorio | `rest`, `file` | opcional |
| `on-incoming-pbx-call-display-actions` | n/a | n/a | `rest`, `file` | **obligatorio** |
| `on-contact-card-display-actions` | n/a | n/a | `rest`, `file` | **obligatorio** |
| `on-main-widget-display-actions` | "widget title" | n/a | `rest`, `file` | **obligatorio** |
| `on-main-display-actions` | n/a | n/a | `rest`, `file` | **obligatorio** |
| `on-conversation-tab-actions` | "nombre de pestaña" | mandatory | `rest`, `file`, `app` | optional |
| `on-main-window-actions` | "Frame name" | obligatorio | Browse URL (por defecto, `commandType` vacío) | n/a |
| `on-user-menu-actions` | "menu item title" | n/a | `rest`, `file` | opcional |

> `redirectUrl` *(BETA S183)* se acepta en los 4 events de llamada (§10.1) y en los 8 EPs de botón (§10.2). En los botones, requiere `responseType: "json"` (obligatorio): combinarlo con `"markdown"` o `"adaptiveCard"`, u omitir `responseType`, es inválido (una redirección sustituye a la visualización).

---

## 5. El objeto `command`

El objeto `command` es **siempre obligatorio** y contiene al menos una `url`. Según el `commandType` elegido, hay sub-campos adicionales válidos.

```json
"command": {
  "url": "{{server}}/your-endpoint",
  "params": "user=${localUser.email}",
  "commandType": "rest",
  "method": "GET",
  "header": ["Authorization: Bearer TOKEN"],
  "bodyParameters": { "key": "value" }
}
```

| Campo | Cuándo usarlo |
|---|---|
| `url` | **obligatorio**. Ruta de aplicación, URL Web, archivo o API REST. |
| `params` | Opcional. Concatenado tras `?` para GET, o como parámetros de URL. Variables permitidas. |
| `commandType` | Opcional. Por defecto `"rest"`. Valores: `"rest"`, `"file"` (según EP). |
| `method` | Opcional (solo si `commandType: "rest"`). Valores: `"GET"`, `"POST"`. |
| `header` | Opcional (si REST). Array de cadenas `"Header-Name: value"` insertadas como cabeceras HTTP. |
| `bodyParameters` | **Obligatorio si `method: "POST"`**. Objeto JSON enviado como cuerpo. Variables permitidas. |

---

## 6. Campos secundarios (según EP)

| Campo | EPs afectados | Efecto |
|---|---|---|
| `AnswerOnClick` | `on-incoming-pbx-call-button-actions` | `true` → ejecuta la acción Y contesta la llamada en un clic |
| `NoShortNumber` (boolean) | events de llamada | No dispara el evento si el número llamante es un número corto |
| `RaiseChangeCall` | events entrantes | `true`, `false`, `"Only"` — comportamiento ante transferencia remota (cf. §6.1) |
| `redirectUrl` *(BETA S183)* | `on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions` y los 8 EPs de botón (§3.2) | Plantilla de URL abierta en una nueva ventana del navegador tras la llamada REST. Variables permitidas (variables Rainbow y `${response...}`, ver §7.7). Requiere `responseType: "json"`. |
| `popout` (boolean) | `on-main-window-actions` | `true` → abre la aplicación WEB en una ventana del navegador (en vez de mostrarla en el frame de Rainbow). |
| `alsoForTeams` (boolean) | `on-call-log-list-actions`, `on-main-display-actions` | Muestra la extensión también en el add-in de Teams — **obsoleto**, usar `devicesSupported` (§6.2) |
| `markdownTemplate` *(BETA S183)* | todos los EPs que muestran Markdown (EPs de visualización y de botón, §8.4) | Plantilla Markdown rellenada con las variables Rainbow y `${response...}`. Requiere `commandType: "rest"` y `responseType: "json"`. |
| `devicesSupported` *(BETA S183)* | todos (`"mobile"` y `"teams"` solo en algunos EPs — ver §6.2) | Array de los clientes Rainbow a los que se aplica el item: `"web"`, `"desktop"`, `"mobile"`, `"teams"`. Sustituye a `defaultDevicesSupported` para este item. |
| `scope` (array) | `on-conversation-tab-actions` | Contextos de conversación donde aparece la pestaña: `"one_to_one"` (P2P), `"bubble"` (conferencia). Ausente → todos los contextos. |
| `urlConfig` | `on-main-widget-display-actions` | URL HTTP/HTTPS de configuración del widget |
| `firstNameJsonField`, `lastNameJsonField`, `companyJsonField` | SOLO `on-incoming-pbx-call-display-actions` | Identificación del caller (respuesta JSON) |
| `linkJsonField` *(Novedad S179)* | SOLO `on-incoming-pbx-call-display-actions` | Campo JSON cuyo valor se muestra como **hipervínculo** para abrir la aplicación de negocio/CRM del llamante (etiqueta del enlace = `name` de la acción si existe, si no «Link») |

### 6.1 Valores de `RaiseChangeCall`

| Valor | Comportamiento |
|---|---|
| `false` (por defecto) | Solo se notifican las llamadas directas |
| `true` | Llamadas directas **Y** transferidas |
| `"Only"` | Solo las llamadas transferidas |

### 6.2 Clientes destinatarios — `devicesSupported` *(BETA S183)*

> ⚠ **BETA (S183)** — esta funcionalidad está en beta y puede evolucionar antes de su disponibilidad general.

Por defecto, cada item se aplica a **Rainbow Web y Desktop**. Dos atributos opcionales declaran a qué clientes Rainbow se aplica un item:

| Atributo | Posición | Función |
|---|---|---|
| `defaultDevicesSupported` | raíz del manifest (junto a `version`, `jsonType`, `extension-points`) | Clientes destinatarios por defecto de **todos** los items del manifest |
| `devicesSupported` | raíz de un item (mismo nivel que `scope`) | **Sustituye** a `defaultDevicesSupported` solo para este item (sustitución total, sin fusión) |

Valores admitidos para ambos: `"web"`, `"desktop"`, `"mobile"`, `"teams"`.

**Orden de resolución** para un item dado: `devicesSupported` del item (si está presente) → si no, `defaultDevicesSupported` del manifest (si está presente) → si no, el valor por defecto integrado `["web", "desktop"]`. Un manifest que no usa ninguno de los dos atributos se comporta exactamente como antes: no se necesita ninguna migración.

**Dónde está disponible cada cliente**

| Cliente | Válido en |
|---|---|
| `"web"`, `"desktop"` | todos los puntos de extensión |
| `"mobile"` | `on-main-window-actions` **únicamente** (primer paso) |
| `"teams"` | `on-call-log-list-actions`, `on-main-display-actions` |

**Reglas**
- Un cliente solicitado **explícitamente en un item** (`devicesSupported`) para un punto de extensión fuera de la lista anterior es señalado como **warning** por el Rainbow Validator.
- Un cliente que solo es **heredado** de `defaultDevicesSupported` y no se aplica al punto de extensión del item es **ignorado silenciosamente** — sin warning.
- `alsoForTeams` está **obsoleto** en favor de `devicesSupported`, pero sigue funcionando: `alsoForTeams: true` añade `"teams"` a los clientes efectivos del item. El Rainbow Validator muestra un aviso de obsolescencia.

**Mobile (primer paso)**
- Solo **`on-main-window-actions`** está disponible en Mobile. En Mobile **abre siempre la aplicación externa en el navegador/webview del dispositivo**: no existe embebido en frame en Mobile, por lo que el campo `popout` del item **no se lee** allí (sigue determinando frame o ventana en Web/Desktop). También se muestra **sin icono**: `icon` / `iconId` no se usa en Mobile, por lo que un item que apunta solo a Mobile (`devicesSupported` sin `"web"` ni `"desktop"`) no lo necesita.
- En Mobile, el manifest se carga **únicamente mediante despliegue cloud (administrador)**; la importación local no está admitida.

**Ejemplo**

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "defaultDevicesSupported": ["web", "desktop", "mobile"],
  "extension-points": {
    "on-main-window-actions": [
      {
        "name": "External reporting",
        "iconId": "settings",
        "popout": true,
        "command": { "url": "https://reporting.example.com/" }
      },
      {
        "name": "Internal only",
        "iconId": "settings",
        "popout": true,
        "devicesSupported": ["web", "desktop"],
        "command": { "url": "https://internal.example.com/" }
      }
    ],
    "on-main-display-actions": [
      {
        "devicesSupported": ["web", "desktop", "teams"],
        "command": { "url": "https://announcements.example.com/today" },
        "responseType": "markdown"
      }
    ]
  }
}
```

- *External reporting* hereda el valor por defecto del manifest y, por tanto, se expone en Mobile.
- *Internal only* lo sustituye y queda excluido de Mobile.
- El item de `on-main-display-actions` es el equivalente en el nuevo estilo de `alsoForTeams: true`.

---

## 7. Variables Rainbow

Las **`$Variables`** se reemplazan en tiempo de ejecución por su valor real. Pueden aparecer en:

- `command.url`
- `command.params`
- `command.bodyParameters`
- `urlConfig`, `adaptiveCardSubmitUrl`
- `redirectUrl` *(BETA S183)* — solo events de llamada y botones (§10.1, §10.2)
- `markdownTemplate` *(BETA S183)* — los EPs que muestran Markdown (§8.4)
- `${response...}` *(BETA S183)* está disponible **solo** en `redirectUrl` y `markdownTemplate` (§7.7)
- el **contenido devuelto a la extensión para visualización**: también puede contener variables Rainbow que se sustituirán antes de mostrar

### 7.1 Sintaxis

```
${objeto.atributo}
${objeto.atributo.regex(patrón)}
${objeto.atributo.regex(patrón, reemplazo)}
```

### 7.2 Objetos y atributos disponibles

**Usuario Rainbow (ME)**
```
${localUser.firstName}        ${localUser.lastName}
${localUser.email}            ${localUser.canonicalNumber}
${localUser.phoneNumber}      ${localUser.internalNumber}
${localUser.phonePbx}         ${localUser.nickname}
${localUser.loginEmail}       ${localUser.id}          (Cpaas)
```

**Caller (llamante)**
```
${caller.firstName}   ${caller.lastName}   ${caller.phoneNumber}
```

**Called (llamado)**
```
${called.phoneNumber}
```

**Contexto de la llamada**
```
${call.callId}
${call.globalCallId}      (solo OXE)
${call.correlatorData}
${call.hexCorrelatorData}
```

**Contact (si está identificado)**
```
${contact.firstName}     ${contact.lastName}
${contact.phoneNumber}   ${contact.email}
${contact.company}       ${contact.workNumber}
${contact.mobileNumber}  ${contact.personalNumber}
${contact.personalMobile}
${contact.tags}          (concatenados, separados por ',')
```

**Bubble (grupo de conversación)**
```
${bubble.ownerEmail}   ${bubble.name}      ${bubble.shareLink}
${bubble.id}           (Cpaas)
${bubble.members}      → JSON {"organizersEmails":[…], "membersEmails":[…]}
                         **Solo utilizable con una llamada REST**
```

**Time (timestamp)**
```
${time}             fecha y hora completas
${time.year}        ${time.month}
${time.hour}        ${time.minute}    ${time.second}    ${time.millisec}
${time.hex}         4 bytes hex para Unix Epoch (solo con hexCorrelatorData)
```

### 7.3 Compatibilidad por EP

Cada EP permite un subconjunto de objetos. Síntesis:

| EP | Objetos de variable permitidos |
|---|---|
| Events de llamada saliente | `localUser`, `called`, `call`, `contact` |
| Events de llamada entrante (incoming/answering/releasing) | `localUser`, `caller`, `called`, `call`, `contact` |
| Inserción automática de correlador OXE | `localUser`, `called` |
| Botones icono (contact-list, contact-detail, call-log-list, contact-card-display) | `localUser`, `contact` |
| Botones de llamada (communication-card, incoming-button, incoming-display) | `localUser`, `caller`, `called`, `call`, `contact` |
| Bubbles | `localUser`, `bubble` |
| Pestaña de conversación | `localUser`, `contact`, `bubble` |
| Display widget / main-display / main-window / user-menu | `localUser` |

### 7.4 Modificador `regex`

Aplica una regex al valor de la variable **antes de la sustitución**. ⚠ Rainbow **no** recorta los espacios alrededor de la coma que separa `pattern` y `replacement` — un espacio después de la coma termina literalmente en el resultado (confirmado en real 2026-10-02, ej. `regex(@.*$, @example.com)` produce `"nombre @example.com"` con un espacio parásito). No usar **ningún espacio** alrededor de la coma:

```jsonc
// Reemplaza +33 o +1 por 0 (normaliza un número)
"params": "pbx=${localUser.phonePbx.regex(^\\+33|^\\+1,0)}"

// Reemplaza el dominio del email
"params": "byEmail=${localUser.email.regex(alcatel.com,al-enterprise.com)}"

// Conserva los últimos 9 dígitos (regex sin reemplazo = extracción)
"params": "${called.phoneNumber.regex(.{0,9}$)}"
```

### 7.5 Variable `${time}` — marca de tiempo

Variable especial de marca de tiempo, disponible en **todos los EPs**. Se sustituye en el instante en que se ejecuta la acción.

| Variable | Valor | Formato / comentario |
|---|---|---|
| `${time}` | Fecha-hora completa | `YYYY/MM/DD HH:MM:SS`, ej. `2026-05-18 15:30:45` (no ISO 8601, sin milisegundos — confirmado en real 2026-10-02) |
| `${time.year}` | Año | 4 dígitos, ej. `2026` |
| `${time.month}` | Mes | 2 dígitos, `01`–`12` |
| `${time.day}` | Día del mes | 2 dígitos, `01`–`31` |
| `${time.hour}` | Hora | 2 dígitos, `00`–`23` |
| `${time.minute}` | Minuto | 2 dígitos, `00`–`59` |
| `${time.second}` | Segundo | 2 dígitos, `00`–`59` |
| `${time.millisec}` | Milisegundos | 3 dígitos, `000`–`999` |
| `${time.hex}` | Unix Epoch en hexadecimal (4 bytes) | **Reservado para `hexCorrelatorData`** — no usar en una cadena o JSON cualquiera |

#### Ejemplos

```jsonc
// Construir un identificador de log
"params": "logId=${time.year}-${time.month}-${time.day}_${time.hour}${time.minute}${time.second}"
// → logId=2026-05-18_153045

// Body POST con marca de tiempo completa
"bodyParameters": { "ts": "${time}", "user": "${localUser.loginEmail}" }

// Correlador OXE con timestamp hex (solo on-makecall-insert-correlator)
"hexCorrelatorData": "O-${localUser.nickname}-${time.hex}"
```

### 7.6 Recursos locales — `${custo.path}`

Para distribuir un manifest con archivos locales (iconos, contenidos estáticos):

1. Referenciar cada recurso por `${custo.path}\\nombre-de-archivo.ext`
2. Empaquetar todo en un **ZIP**:
   - `custo-manifest.json` en la raíz
   - los archivos de recursos al lado

Ejemplo:
```json
{
  "icon": "${custo.path}\\basketball.png",
  "command": {
    "commandType": "file",
    "url": "${custo.path}\\FileDisplay.txt"
  },
  "responseType": "markdown"
}
```

El ZIP debe contener: `custo-manifest.json`, `basketball.png`, `FileDisplay.txt`.

#### Identificación del manifest dentro del ZIP

Rainbow identifica el archivo manifest según el siguiente orden de prioridad:

1. **`custo-manifest.json`** — archivo con exactamente este nombre, en la raíz del ZIP
2. **De lo contrario**, el **primer archivo `.json`** encontrado en el ZIP que contenga `"jsonType": "Rainbow-custo-manifest"`

Si ningún archivo cumple ninguno de estos dos criterios, la importación del ZIP falla.

> 💡 Para garantizar una detección sin ambigüedad, nombre su manifest `custo-manifest.json` y colóquelo en la raíz del ZIP.

---


---

### 7.7 La variable `${response}` — respuesta REST *(BETA S183)*

`${response}` representa el **cuerpo JSON devuelto por la llamada REST de la misma acción**. Está disponible en `redirectUrl` de los events de llamada (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) y de los 8 EPs de botón — ver §10.1 y §10.2 — y en **`markdownTemplate`** de los EPs que muestran Markdown — ver §8.4. No está disponible en ningún otro campo.

```
${response.contactId}               campo de la respuesta
${response.data.contact.id}         ruta anidada
${response[0].contactId}            índice de array
```

**Resolución tolerante.** Algunas APIs REST devuelven un único objeto cuando hay un solo resultado y un array cuando hay varios. Por ello, ambas sintaxis funcionan sea cual sea la forma de la respuesta:

| Sintaxis | La respuesta es un objeto | La respuesta es un array |
|---|---|---|
| `${response.contactId}` | el campo del objeto | el campo del **primer elemento** |
| `${response[0].contactId}` | el propio objeto se toma como primer elemento | el campo del primer elemento |

- Cualquier otro índice sobre un objeto (`${response[1]...}`) es un campo ausente.
- Un array vacío (`[]`) es un campo ausente.

Cuando el campo apuntado está ausente, no ocurre nada (ver §10.1, *Gestión de errores*).

---

## 8. Visualización en formato texto / Markdown

Cuando una extensión puede mostrar una respuesta y `responseType: "markdown"` (o está ausente — es el valor por defecto), el contenido de la respuesta se renderiza **como texto enriquecido en Markdown** en un popup de Rainbow. Los **emojis** también son admitidos (Unicode nativo, pegado directamente — los shortcodes tipo `:smile:` **no** se interpretan, se muestran tal cual).

### 8.1 Sintaxis Markdown común

Rainbow admite un subconjunto del Markdown estándar. Los elementos más útiles en un popup de extensión:

| Sintaxis | Efecto |
|---|---|
| `**negrita**` | **negrita** |
| `*cursiva*` | *cursiva* |
| `# Título 1`, `## Título 2`, `### Título 3` | títulos jerárquicos |
| `- elemento` o `* elemento` | lista con viñetas |
| `1. elemento` | lista numerada |
| `[etiqueta](https://url.com)` | enlace clicable |
| ```` ```\nbloque de código\n``` ```` | bloque de código |
| `---` | línea horizontal |
| `\| col 1 \| col 2 \|` | tabla (con línea de separación `\|---\|---\|`) |
| 🎉 ✅ 📞 | emojis Unicode (copiar y pegar directo) |

#### Ejemplo — Markdown enriquecido en salida REST

Una API devuelve:

```markdown
## Contacto identificado 📇

**Marie Curie** — *Universidad de la Sorbona*

| Campo | Valor |
|---|---|
| Teléfono | +33 1 42 34 56 78 |
| Email | [marie.curie@example.com](mailto:marie.curie@example.com) |
| Estado | ✅ Cliente activo |

> 💡 Al hacer clic en el email se abre tu cliente de correo.
```

El popup de Rainbow mostrará el título, la tabla formateada, los enlaces clicables y los emojis.

#### Ejemplo — Demo de la sintaxis admitida (archivo local)

Manifest:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-contact-card-display-actions": [
      {
        "name": "SupportedMarkdown",
        "command": {
          "url": "${custo.path}\\SupportedMarkdown.txt",
          "commandType": "file"
        },
        "responseType": "markdown"
      }
    ]
  }
}
```

Contenido del archivo `SupportedMarkdown.txt` (entregado en el ZIP junto al manifest):

```markdown
<!-- Comment: Supported markdown -->
---
**bold text**
*italic text*
# Título 1,
## Título 2,
### Título 3
* elemento 1️⃣
* elemento 2️⃣
* elemento 3️⃣
1. elemento 1️⃣
2. elemento 2️⃣
3. elemento 3️⃣
---
<!-- Tables -->
| Table   |  Link |
|---------- |:------: |
| Rainbow | *[Rainbow](https://support.openrainbow.com/hc/en-us/articles/4706281095058)*|
| Teams | *[Rainbow Teams](https://support.openrainbow.com/hc/en-us/articles/11949840558098)*|
___
```

Renderizado en Rainbow:

![Renderizado Markdown en Rainbow](images/markdown.png)

### 8.2 Markdown extraído de una respuesta JSON

Si `responseType: "json"` **y** `displayJsonField` está definido, Rainbow interpreta la respuesta como JSON, extrae el valor del campo apuntado por `displayJsonField`, y lo muestra como texto/Markdown.

Es útil cuando el servidor ya devuelve un JSON estructurado (por ejemplo, un payload de API de negocio) que contiene el markdown a mostrar en uno de sus campos.

#### Ejemplo — Markdown dentro de un campo JSON

Manifest:

```json
"on-contact-list-actions": [{
  "name": "Quick info",
  "icon": "${custo.path}\\info.png",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/info",
    "params": "email=${contact.email}"
  },
  "responseType": "json",
  "displayJsonField": "display"
}]
```

Respuesta de la API:

```json
{
  "id": 12345,
  "status": "active",
  "display": "## ${contact.firstName} ${contact.lastName}\n\nCliente desde **2019**\n\n- ✉️ contact@example.com\n- 📞 +33 1 42 34 56 78\n- 🎫 [Abrir el ticket](https://crm.example.com/12345)"
}
```

Rainbow extrae `display`, sustituye las variables `${contact.*}`, y muestra el resultado en el popup.

### 8.3 Visualización vía salida estándar (solo Desktop)

Cuando un EP admite el retorno de visualización en Markdown, se puede capturar la **salida estándar** de un script o de un programa:

```json
"command": {
  "commandType": "file",
  "url": "${custo.path}\\display.bat"
},
"responseType": "markdown"
```

El contenido escrito en `stdout` por el script se muestra en un popup de Rainbow. Ideal para integraciones simples o prototipado sin infraestructura REST.

> ⚠ **Solo Rainbow Desktop.** En Web, el script no puede ejecutarse localmente, por lo que este modo no está disponible.

### 8.4 Plantilla Markdown — `markdownTemplate` *(BETA S183)*

> ⚠ **BETA (S183)** — esta funcionalidad está en beta y puede evolucionar antes de su disponibilidad general.

Hasta ahora, el resultado de una llamada REST podía mostrarse como **un campo de la respuesta JSON** (`displayJsonField`, §8.2) o maquetarse con una **Adaptive Card** (§9). `markdownTemplate` añade una tercera opción: una **plantilla Markdown declarada en el manifiesto**, rellenada con las variables Rainbow y con los campos de la respuesta JSON de la llamada REST.

**Reglas**
- `command` es de tipo **`rest`** y la respuesta de tipo **JSON** (`responseType: "json"`) — ambos son **obligatorios** con `markdownTemplate`.
- `markdownTemplate` (string, Markdown) está en la raíz de la acción. Su texto se muestra tras una **sustitución de variables**: las **variables Rainbow** habituales del EP (§7) y la variable **`${response}`** (§7.7), es decir, el cuerpo JSON devuelto por la llamada REST de la misma acción (`${response.contactId}`, `${response.data.contact.id}`, `${response[0].contactId}`; resolución flexible de objetos/arrays, §7.7).
- Los valores sustituidos se insertan **tal cual**: sin codificación URL y sin escape de los caracteres Markdown.
- **Orden de ejecución** — cuando varios de estos elementos están definidos en la misma acción, Rainbow los trata en este orden, y se ejecuta el primero que se aplica: `redirectUrl`, luego `markdownTemplate`, luego `displayJsonField`, luego Adaptive Card. En particular, si existe un `redirectUrl` y se devuelve una respuesta REST válida, se aplica la redirección y `markdownTemplate` **no** se muestra; si **no hay `redirectUrl`**, o si está **vacío porque la respuesta REST está vacía**, se muestra el contenido de `markdownTemplate`.
- **Gestión de errores** — si la llamada REST falla (timeout, error HTTP), si la respuesta no es JSON válido o si falta un campo referenciado: **no se muestra nada**.
- Un cliente que no conoce `markdownTemplate` ignora el campo (sin error).

**Disponible en** todos los extension points que muestran Markdown:
- Visualización: `on-incoming-pbx-call-display-actions`, `on-contact-card-display-actions`, `on-main-widget-display-actions`, `on-main-display-actions`, `on-conversation-tab-actions`;
- Botones que muestran un resultado: `on-incoming-pbx-call-button-actions`, `on-contact-list-actions`, `on-contact-detail-actions`, `on-call-log-list-actions`, `on-communication-card-actions`, `on-bubble-actions`, `on-bubble-conference-actions`, `on-user-menu-actions`.

Los events de llamada no muestran nada y no están afectados.

**Ejemplo — ficha construida a partir de la respuesta**

```json
"on-incoming-pbx-call-display-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "markdownTemplate": "## ${response.firstName} ${response.lastName}\n🏢 ${response.company}\n📞 ${caller.phoneNumber}"
}]
```

Con una respuesta `{"firstName":"Jane","lastName":"Doe","company":"ACME"}`, el pop-up muestra el título *Jane Doe* seguido de la empresa y del número de teléfono.

---

## 9. Adaptive Cards

**Adaptive Card** es un estándar abierto definido por **Microsoft** para representar contenido enriquecido (texto, listas, formularios, botones, imágenes) en un formato JSON portable, renderizado de forma coherente por cada aplicación que lo integra.

📖 [Referencia Microsoft Adaptive Card](https://adaptivecards.io/explorer/) — documentación oficial y biblioteca de ejemplos.

El modelo de Adaptive Card separa dos cosas:
- un **template** (presentación) descrito en JSON — estructura visual con variables `${...}`;
- **datos dinámicos** también en JSON — que rellenan las variables del template.

Rainbow retoma esta separación y realiza el render en el cliente (Desktop o Web).
- El **template** puede estar predefinido en el manifest (`adaptiveCardTemplate`) o incluido en la respuesta JSON de una llamada REST (extracción mediante `adaptiveCardTemplateJsonField`).
- Los **datos** pueden estar igualmente en el manifest, en un archivo separado (útil para pruebas), pero suelen provenir de la respuesta a una llamada REST de negocio.

Cuatro combinaciones son admitidas en Rainbow Desktop **y** Web:

| Modo | Template | Content |
|---|---|---|
| **Todo en el manifest** | inline | inline |
| **Template en el manifest** | inline | en un archivo |
| **Template en manifest + datos REST** | inline | devuelto por una llamada REST |
| **Todo vía REST** | devuelto por REST | devuelto por REST |

### Campos implicados (en la raíz de la acción)

| Campo | Rol |
|---|---|
| `adaptiveCardTemplate` | Template JSON inline en el manifest |
| `adaptiveCardTemplateJsonField` | Nombre del campo de la respuesta REST que contiene el template |
| `adaptiveCardContentJsonField` | Nombre del campo de la respuesta REST que contiene los datos. **Si está vacío o ausente, las variables se buscan directamente en la raíz del objeto JSON de la respuesta.** |
| `adaptiveCardSubmitUrl` | URL REST llamada con POST cuando se invoca un `Action.Submit` en la card |

### Acciones admitidas en una Adaptive Card

- **`Action.OpenUrl`** — abre una URL en el navegador.
- **`Action.Submit`** — Rainbow transforma esta acción en un **POST** hacia la URL definida por `adaptiveCardSubmitUrl`. El cuerpo de la petición contiene el objeto `data` de la acción (más los valores de los `Input.*` que pueda haber).
  - Si la respuesta REST devuelve **datos refrescados** (misma estructura que la respuesta inicial, o un nuevo template), Rainbow **refresca la card** automáticamente con los nuevos valores.

### Tags Adaptive Card admitidos (indicativo)

Tabla de referencia del soporte de los principales elementos Adaptive Card en Rainbow. El estado puede evolucionar entre versiones — para verificar con precisión con tu versión actual de Rainbow, utiliza la herramienta de test **Adaptive Card** integrada en RainbowCustoServer.

| Elemento AC | Soporte | Notas |
|---|:---:|---|
| `TextBlock` | ✅ | elemento de texto básico, rico en opciones de estilo |
| `Image` | ✅ | URL http(s), data URI |
| `ColumnSet` / `Column` | ✅ | maquetación por columnas |
| `Container` | ✅ | agrupación, estilos de fondo |
| `FactSet` | ✅ | tabla clave / valor |
| `ImageSet` | ✅ | galería de imágenes |
| `ActionSet` | ✅ | grupo de botones inline |
| `RichTextBlock` / `TextRun` | ✅ | texto con varios estilos en una misma línea |
| `Table` | ✅ | tabla estructurada (AC 1.5+) |
| `Input.Text` | ✅ | entrada de texto |
| `Input.Number` | ✅ | entrada numérica |
| `Input.Date` | ✅ | selector de fecha |
| `Input.Time` | ✅ | selector de hora |
| `Input.Toggle` | ✅ | casilla de verificación |
| `Input.ChoiceSet` | ✅ | desplegable / radio / multi-selección |
| `Action.OpenUrl` | ✅ | abre la URL en el navegador |
| `Action.Submit` | ✅ | POST a `adaptiveCardSubmitUrl` |
| `Action.ToggleVisibility` | ✅ | ocultar / mostrar elementos dinámicamente |
| `Action.ShowCard` | ✅ | sub-card inline |
| `Media` | ⚠️ | renderizado de vídeo / audio limitado |
| `Carousel` | ⚠️ | navegación entre cards — límites de render (AC 1.4+) |
| `Badge` | ❌ | AC 1.6+ — no admitido |
| `CodeBlock` | ❌ | AC 1.6+ — no admitido |
| `Icon` | ❌ | AC 1.6+ — no admitido |
| `CompoundButton` | ❌ | AC 1.6+ — no admitido |
| `ProgressRing` | ❌ | AC 1.6+ — no admitido |
| `ProgressBar` | ❌ | AC 1.6+ — no admitido |
| `Action.Popover` | ❌ | AC 1.6+ — no admitido |
| `Input.Rating` | ❌ | AC 1.6+ — no admitido |
| `Chart.*` (Donut, Line, Bar…) | ❌ | extensiones Chart no admitidas |

Leyenda: ✅ admitido · ⚠️ admitido con límites · ❌ no admitido

### Ejemplo: widget con template y datos desde REST

```json
"on-main-widget-display-actions": [{
  "name": "Domotic",
  "command": {
    "method": "GET",
    "commandType": "rest",
    "url": "http://localhost:3300/domotic/api/card"
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField": "data",
  "adaptiveCardSubmitUrl": "http://localhost:3300/domotic/card-submit"
}]
```

Respuesta REST esperada:
```json
{
  "card": { "type": "AdaptiveCard", "body": [ … ] },
  "data": { "lumiere": { "status": "on" }, … }
}
```

Renderizado en Rainbow:

![Renderizado Adaptive Card en Rainbow](images/adaptive.png)

---

## 10. Referencia por tipo de extensión

Esta sección agrupa los puntos de extensión por familia funcional. Cuatro familias: **eventos de telefonía**, **botones**, **visualización**, **aplicación**.

---

### 10.1 Eventos de telefonía

![Eventos telefónicos Rainbow](images/telephony-events.svg)

**Principio**: sin UI propia. Estas extensiones disparan automáticamente una acción (llamada REST, ejecución local, apertura de URL) cuando se produce un evento telefónico. Casos de uso típicos: registro de llamadas en un ERP, disparo de un workflow CRM, actualización de presencia en un sistema de negocio.

**Puntos de extensión**:

| Clave | Disparador |
|---|---|
| `on-outgoing-pbx-call-actions` | Se inicia una llamada saliente |
| `on-incoming-pbx-call-actions` | Llega una llamada entrante |
| `on-answering-incoming-pbx-call-actions` | Se contesta una llamada entrante |
| `on-releasing-incoming-pbx-call-actions` | Se finaliza una llamada entrante |
| `on-makecall-insert-correlator` | En cada makecall — inserta un correlador (solo OXE) |

**Requisito de licencia**: Essentials (los events son la única familia admitida en esta licencia).

#### Campos (acción estándar)

| Campo | Posición | Tipo | Obligatorio | Valores / restricciones |
|---|---|---|---|---|
| `command` | raíz | object | **SÍ** | Objeto command |
| `command.url` | command | string | **SÍ** | URL HTTP(S) o `{{server}}/…` |
| `command.params` | command | string | no | Parámetros URL (concatenados tras `?`). Variables permitidas. |
| `command.commandType` | command | string | no | `"rest"` (por defecto y único valor soportado para events) |
| `command.method` | command | string | no | `"GET"` (por defecto) o `"POST"` |
| `command.header` | command | array | no | Array de strings `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **SÍ si `method: "POST"`** | JSON enviado como cuerpo. Variables permitidas. |
| `NoShortNumber` | raíz | boolean | no | Si `true`, el event no se dispara cuando el llamante es un número corto |
| `RaiseChangeCall` | raíz | `true` \| `false` \| `"Only"` | no | (solo incoming events) — gestiona la propagación en caso de transferencia remota (§6.1) |
| `redirectUrl` *(BETA S183)* | raíz | string | no | Plantilla de URL abierta en una nueva ventana del navegador tras la llamada REST (ver más abajo). Requiere `responseType: "json"`. |
| `responseType` | raíz | `"json"` | **SÍ si `redirectUrl`** | Obligatorio con `redirectUrl`. En caso contrario, sin `responseType` en los events. |

**A tener en cuenta**:
- **Sin `name`, `icon`** — un event es silencioso desde la perspectiva de la UI de Rainbow
- **Sin `responseType`**, salvo `"json"`, que es **obligatorio** junto con `redirectUrl` *(BETA S183)* — ver más abajo
- `commandType: "file"` no admitido

**Variables Rainbow permitidas por EP**

| EP | `localUser` | `caller` | `called` | `call` | `contact` *¹ | `time` |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `on-outgoing-pbx-call-actions` | ✓ | — | ✓ | ✓ | ✓ | ✓ |
| `on-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-answering-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-releasing-incoming-pbx-call-actions` | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| `on-makecall-insert-correlator` | ✓ | — | solo `phoneNumber` | — | — | ✓ |

*¹ — `${contact.*}` solo se resuelve **si se ha identificado un contacto** (número reconocido en Rainbow). En caso contrario, las variables `${contact.*}` quedan vacías al sustituir.*

*Solo en `redirectUrl` (BETA S183), `${response...}` (cuerpo JSON de la llamada REST de la misma acción) también está disponible — ver §7.7.*

#### Redirección tras una llamada REST — `redirectUrl` *(BETA S183)*

**Principio**: encadenar una llamada REST con la apertura de una URL construida a partir de su respuesta JSON — típicamente un **CTI screen-pop**: 1) se consulta una API REST con el número del llamante para obtener un identificador (p. ej. `contactId`), 2) se abre una página de "screen-pop" decorada con ese identificador. Toda la cadena se declara en el manifest, sin backend intermedio.

Disponible en los cuatro events de llamada (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) **y en los puntos de extensión de botón** (§10.2).

**Reglas**:
- **`redirectUrl`** (string, plantilla): se aplica una redirección cuando está presente. `responseType: "json"` es **obligatorio** con él (la respuesta REST se lee como JSON para alimentar `${response}`); no es un nuevo valor de `responseType`.
- El único trabajo de Rainbow es una **sustitución de variables** en `redirectUrl`, ya sea una variable Rainbow (`${caller.phoneNumber}`, …) o una variable `${response...}` (§7.7). Dos usos:
  - **la respuesta aporta una parte del destino**: `"redirectUrl": "http://server/screenPop?id=${response.contactId}"`;
  - **la respuesta aporta todo el destino**: `"redirectUrl": "${response.url}"` — el campo `url` de la respuesta es la página que se abre.
- El valor sustituido se **codifica automáticamente como URL** (mismo mecanismo que las demás variables del manifest).
- La URL se abre **siempre** en una **nueva ventana del navegador** (popup).
- **Gestión de errores** — si la llamada REST falla (timeout, error HTTP), si el campo apuntado no está en la respuesta, o si la respuesta no es un JSON válido: **no ocurre nada** (sin popup, sin error mostrado al usuario); solo se escribe una traza de log en el cliente para el diagnóstico.
- Un cliente que no conoce `redirectUrl` ignora el campo (sin error).

> ⚠ **BETA (S183)** — esta funcionalidad está en beta y puede evolucionar antes de su disponibilidad general.

**Ejemplo 1 — la respuesta aporta una parte del destino**

```json
"on-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "http://server/screenPop?id=${response.contactId}"
}]
```

**Ejemplo 2 — la respuesta aporta todo el destino (respuesta `{"url":"https://crm.example.com/contact/42"}`)**

```json
"on-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "${response.url}"
}]
```

**Ejemplo 3 — variable Rainbow y variable de respuesta combinadas; la API responde un objeto *o* un array (resolución tolerante, §7.7)**

```json
"on-answering-incoming-pbx-call-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "phone=${caller.phoneNumber}"
  },
  "responseType": "json",
  "redirectUrl": "http://server/screenPop?id=${response[0].contactId}&user=${localUser.loginEmail}"
}]
```

#### Resolución de caller-ID
La **resolución de la identidad del llamante** (nombre/apellido/empresa) y el **enlace clicable** hacia su ficha CRM **no** se hacen mediante los events de telefonía (que son silenciosos en la UI de Rainbow), sino mediante la visualización **`on-incoming-pbx-call-display-actions`** — ver **§10.3.1**.

#### Esquema especial — `on-makecall-insert-correlator` (OXE)

Este EP no sigue el esquema `command` estándar. Inserta un correlador (ASCII o hex) en todos los makecall:

```json
"on-makecall-insert-correlator": [{
  "correlatorData":    "string-ascii-32-chars-max"
  // O
  "hexCorrelatorData": "O-${localUser.nickname}-${called.phoneNumber.regex(.{8}$)}-${time.hex}"
}]
```

Limitado a 32 caracteres. Solo un tipo (`correlatorData` **o** `hexCorrelatorData`) a la vez.

#### Ejemplo 1 — registro de llamada entrante (POST con body)

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-incoming-pbx-call-actions": [{
      "command": {
        "commandType": "rest",
        "method": "POST",
        "url": "https://crm.example.com/calls/log",
        "header": [
          "Content-Type: application/json",
          "Authorization: Bearer eyJhbGc...",
          "X-Rainbow-User: ${localUser.loginEmail}"
        ],
        "bodyParameters": {
          "type":      "incoming",
          "from":      "${caller.phoneNumber}",
          "to":        "${localUser.phoneNumber}",
          "user":      "${localUser.loginEmail}",
          "timestamp": "${time}"
        }
      }
    }]
  }
}
```

> ℹ La **resolución de caller-ID** (nombre/apellido/empresa + enlace CRM) **no** es un event: se declara mediante `on-incoming-pbx-call-display-actions` — ver **§10.3.1**.

#### Ejemplo 2 — Popup de aplicación web, filtrado de números cortos

```json
"on-outgoing-pbx-call-actions": [{
  "NoShortNumber": true,
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://reporting.example.com/outgoing",
    "params": "to=${called.phoneNumber}"
  }
}]
```

El event no se disparará para llamadas internas (extensiones cortas).

#### Ejemplo 3 — ejecución de un script local al descolgar

> **⚠ Solo Rainbow Desktop** — la ejecución de un script o aplicación local (`.exe`, `.bat`, etc.) no está admitida por Rainbow Web. En Web, este event se ignora.

```json
{
  "version": "2",
  "extension-points": {
    "on-answering-incoming-pbx-call-actions": [{
      "command": {
        "commandType": "file",
        "url": "C:\\Tools\\log-call.bat",
        "params": "from=${caller.phoneNumber} called=${localUser.phonePbx}"
      }
    }]
  }
}
```

El script `log-call.bat` se ejecuta localmente cuando el usuario descuelga la llamada. Las variables Rainbow se sustituyen en `params` antes de pasarse a la línea de comandos.

#### Ejemplo 4 — correlador OXE en makecall

> **⚠ Solo OXE** — este EP solo se puede explotar en una centralita Alcatel-Lucent OXE.

Para añadir un correlador a cada llamada saliente iniciada mediante makecall:

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-makecall-insert-correlator": [{
      "hexCorrelatorData": "O-${localUser.nickname}-${called.phoneNumber.regex(.{8}$)}-${time.hex}"
    }]
  }
}
```

**Reglas**:
- O bien `correlatorData` (ASCII) **O** `hexCorrelatorData` (hexadecimal) — **solo se permite un tipo**
- Limitado a **32 caracteres**
- Variables permitidas: `${localUser.*}`, `${called.phoneNumber}`, `${time.*}`
- `${time.hex}` es un formato especial de 4 bytes — únicamente con `hexCorrelatorData`

---

### 10.2 Botones

![Botones en la UI de Rainbow](images/buttons.png)

**Principio**: un botón-icono se inserta en una ubicación concreta de la UI de Rainbow. Al hacer clic, se ejecuta una acción y, opcionalmente, su resultado se muestra en un popup (Markdown o Adaptive Card). 3 botones como máximo por EP.

**Puntos de extensión**:

| Clave | Ubicación del botón |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up de llamada entrante |
| `on-call-log-list-actions` | Cada fila del registro de llamadas |
| `on-contact-list-actions` | Cada fila de la lista de contactos |
| `on-contact-detail-actions` | Panel de detalle del contacto |
| `on-communication-card-actions` | Barra del gestor de llamadas (menú) |
| `on-bubble-actions` | Menú de propiedades de una bubble |
| `on-bubble-conference-actions` | Menú de una conferencia telefónica |
| `on-user-menu-actions` | Menú de usuario (Desktop / Web — no Teams) |

**Requisito de licencia**: Business mínimo.

#### Campos (todos los botones)

| Campo | Posición | Tipo | Obligatorio | Valores / restricciones |
|---|---|---|---|---|
| `name` | raíz | string | ver especificidades | Texto / tooltip del botón o etiqueta de menú |
| `icon` o `iconId` | raíz | string | ver especificidades | URL `https://…`, `${custo.path}\archivo.png` o nombre de sprite integrado |
| `tooltip` | raíz | string | no | Tooltip alternativo (ignorado en algunos EPs) |
| `command` | raíz | object | **SÍ** | Objeto command |
| `command.url` | command | string | **SÍ** | URL HTTP(S), `{{server}}/…` o ruta de archivo |
| `command.params` | command | string | no | Parámetros URL. Variables permitidas. |
| `command.commandType` | command | string | no | `"rest"` (por defecto) o `"file"`. En Web, `"file"` requiere el archivo en el ZIP. |
| `command.method` | command | string | no | `"GET"` (por defecto) o `"POST"` |
| `command.header` | command | array | no | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **SÍ si POST** | JSON enviado como cuerpo |
| `responseType` | raíz | string | ver especificidades | `"markdown"`, `"json"` o `"adaptiveCard"`. Si está presente → popup. Si no → la acción se ejecuta sin retorno visible. |
| `displayJsonField` | raíz | string | no | Si `responseType: "json"`, nombre del campo JSON que contiene el markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | raíz | — | según modo | Si `responseType: "adaptiveCard"` — ver §8 |
| `AnswerOnClick` | raíz | boolean | no | (solo `on-incoming-pbx-call-button-actions`) — si `true`, también descuelga la llamada |
| `alsoForTeams` | raíz | boolean | no | (solo `on-call-log-list-actions`) — también se muestra en el add-in de Teams |
| `redirectUrl` *(BETA S183)* | raíz | string | no | Plantilla de URL abierta en una nueva ventana del navegador tras la llamada REST (ver más abajo). Requiere `responseType: "json"`. |
| `markdownTemplate` *(BETA S183)* | raíz | string | no | Plantilla Markdown mostrada tras la sustitución de las variables Rainbow y de `${response...}`. Requiere `commandType: "rest"` y `responseType: "json"` — ver §8.4. |

#### Especificidades por EP

| EP | `name` | `icon` | `responseType` | Variables permitidas |
|---|---|---|---|---|
| `on-incoming-pbx-call-button-actions` | "Button text" | no usado | opcional | localUser, caller, called, call, contact |
| `on-call-log-list-actions` | tooltip | **SÍ** | opcional | localUser, contact |
| `on-contact-list-actions` | tooltip | **SÍ** | opcional | localUser, contact |
| `on-contact-detail-actions` | tooltip | **SÍ** | opcional | localUser, contact |
| `on-communication-card-actions` | "menu text" | **SÍ** (menú) | opcional | localUser, caller, called, call, contact |
| `on-bubble-actions` | "menu text" | **SÍ** (menú) | opcional | localUser, bubble |
| `on-bubble-conference-actions` | "menu text" | **SÍ** (menú) | opcional | localUser, bubble |
| `on-user-menu-actions` | "menu item title" | **SÍ** (menú) | opcional | localUser |

#### Redirección tras una llamada REST — `redirectUrl` *(BETA S183)*

Todos los EPs de botón aceptan `redirectUrl`: al hacer clic, se ejecuta la llamada REST y la URL — construida a partir de la respuesta JSON — se abre en una **nueva ventana del navegador**. Las reglas son las mismas que para los events de llamada (ver **§10.1**): `redirectUrl` requiere `responseType: "json"`, las variables (las variables Rainbow del EP y `${response...}`, §7.7) se sustituyen y se codifican como URL, y no ocurre nada si la llamada REST falla, si falta el campo o si la respuesta no es JSON.

Especificidades para los botones:
- Una redirección **sustituye a la visualización**: `responseType` debe ser `"json"` (obligatorio). Combinar `redirectUrl` con `"markdown"` o `"adaptiveCard"`, u omitir `responseType`, es **inválido** (señalado como error por el Rainbow Validator).
- `command.commandType` debe ser `"rest"` (por defecto) — la respuesta solo existe para una llamada REST, no para `"file"`.

> ⚠ **BETA (S183)** — esta funcionalidad está en beta y puede evolucionar antes de su disponibilidad general.

**Ejemplo — botón de la lista de contactos que abre la ficha CRM resuelta mediante una consulta REST**

```json
"on-contact-list-actions": [{
  "iconId": "settings",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/contacts/lookup",
    "params": "email=${contact.email}"
  },
  "responseType": "json",
  "redirectUrl": "${response.url}"
}]
```

#### Ejemplo 1 — botón en la lista de contactos que abre un CRM externo

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-contact-list-actions": [{
      "name": "Open in CRM",
      "tooltip": "View this contact in our CRM",
      "icon": "${custo.path}\\crm.png",
      "command": {
        "url": "https://crm.example.com/contact",
        "params": "email=${contact.email}&phone=${contact.phoneNumber}"
      }
    }]
  }
}
```

Sin `responseType` → la URL se abre en una nueva pestaña del navegador, sin popup en Rainbow.

#### Ejemplo 2 — botón en llamada entrante que crea un ticket y descuelga

```json
"on-incoming-pbx-call-button-actions": [{
  "name": "Create ticket & answer",
  "AnswerOnClick": true,
  "command": {
    "commandType": "rest",
    "method": "POST",
    "url": "https://tickets.example.com/api/tickets",
    "header": [
      "Authorization: Bearer eyJhbGc...",
      "Content-Type: application/json"
    ],
    "bodyParameters": {
      "caller":    "${caller.phoneNumber}",
      "callId":    "${call.callId}",
      "createdBy": "${localUser.loginEmail}"
    }
  }
}]
```

El clic crea el ticket **y** descuelga la llamada en una sola operación (`AnswerOnClick: true`).

#### Ejemplo 3 — menú Adaptive Card en el menú de la bubble

```json
"on-bubble-actions": [{
  "name": "Bubble members report",
  "icon": "${custo.path}\\report.png",
  "command": {
    "commandType": "rest",
    "method": "POST",
    "url": "https://api.example.com/bubble/report",
    "header": ["Authorization: Bearer eyJhbGc...", "Accept: application/json"],
    "bodyParameters": {
      "bubbleId": "${bubble.id}",
      "members":  "${bubble.members}"
    }
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField":  "data"
}]
```

`${bubble.members}` requiere `commandType: "rest"` (cf. §7).

---

### 10.3 Visualización (Display)

![Visualización automática de información en Rainbow](images/displays.png)

**Principio**: inserta automáticamente contenido (Markdown o Adaptive Card) en una ubicación concreta de la UI — sin interacción del usuario. El contenido se recupera en el momento en que la ubicación se hace visible.

**Puntos de extensión**:

| Clave | Ubicación de la visualización |
|---|---|
| `on-incoming-pbx-call-display-actions` | En el pop-up de llamada entrante |
| `on-contact-card-display-actions` | En el panel de detalle del contacto |
| `on-main-widget-display-actions` | Widget en el panel principal de Rainbow |
| `on-main-display-actions` | Mensaje en la webapp de Teams |
| `on-conversation-tab-actions` | Pestaña personalizada en una conversación (P2P o conferencia) — ver abajo |

**Requisito de licencia**: Business mínimo.

#### Campos (todos los displays)

| Campo | Posición | Tipo | Obligatorio | Valores / restricciones |
|---|---|---|---|---|
| `name` | raíz | string | ver especificidades | Título (solo widget) |
| `command` | raíz | object | **SÍ** | Objeto command |
| `command.url` | command | string | **SÍ** | URL HTTP(S), `{{server}}/…` o archivo |
| `command.params` | command | string | no | Parámetros URL. Variables permitidas. |
| `command.commandType` | command | string | no | `"rest"` (por defecto) o `"file"`. En Web, `"file"` → archivo en el ZIP. |
| `command.method` | command | string | no | `"GET"` (por defecto) o `"POST"` |
| `command.header` | command | array | no | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **SÍ si POST** | JSON body |
| `responseType` | raíz | string | **SÍ** | `"markdown"`, `"json"` o `"adaptiveCard"` ¹ — siempre requerido para los displays |
| `displayJsonField` | raíz | string | no | Si `responseType: "json"`, campo que contiene el markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | raíz | — | según modo | Si `responseType: "adaptiveCard"` — ver §8 |
| `urlConfig` | raíz | string | no | (solo `on-main-widget-display-actions`) — URL de configuración del widget |
| `alsoForTeams` | raíz | boolean | no | (solo `on-main-display-actions`) — mostrar en el web add-in de Teams |
| `markdownTemplate` *(BETA S183)* | raíz | string | no | Plantilla Markdown mostrada tras la sustitución de las variables Rainbow y de `${response...}`. Requiere `commandType: "rest"` y `responseType: "json"` — ver §8.4. |

*¹ `adaptiveCard` NO es compatible con `on-incoming-pbx-call-display-actions` (ventana emergente de llamada entrante) — véase §10.3.1.*

#### Especificidades por EP

| EP | `name` | Variables permitidas |
|---|---|---|
| `on-incoming-pbx-call-display-actions` | no usado | localUser, caller, called, call, contact |
| `on-contact-card-display-actions` | no usado | localUser, contact |
| `on-main-widget-display-actions` | "widget title" | localUser |
| `on-main-display-actions` | no usado | localUser |
| `on-conversation-tab-actions` | "nombre de pestaña" | localUser, contact, bubble |

#### 10.3.1 `on-incoming-pbx-call-display-actions` (detalle)

**Rol**: mostrar automáticamente información en el **pop-up de llamada entrante**, sin interacción del usuario. El contenido se recupera en el momento en que aparece el pop-up, a partir de una fuente declarada en `command`.

**Fuentes de contenido posibles**:

| Fuente | `command` | Efecto |
|---|---|---|
| **Archivo** | `commandType: "file"`, `url` = ruta de archivo | lee un archivo y muestra su contenido |
| **Script** | `commandType: "file"`, `url` = ejecutable/script | ejecuta el script y muestra su salida |
| **Página Web** | `commandType: "rest"`, `url` = http(s) | abre la URL y muestra su contenido |
| **API REST** | `commandType: "rest"`, `method` GET/POST | invoca una API REST y explota la respuesta |

**`responseType`**: `"markdown"` (por defecto) o `"json"`.

> ⚠️ **Adaptive Card NO es utilizable** para este punto de extensión.

**Explotación de una respuesta JSON** (`responseType: "json"`) — varios campos de la respuesta pueden extraerse:

| Campo manifest | Rol |
|---|---|
| `displayJsonField` | nombre del campo JSON **cuyo valor se muestra** (texto / Markdown) en el pop-up |
| `firstNameJsonField` | **sobrescribe/define el nombre** del llamante mostrado |
| `lastNameJsonField` | **sobrescribe/define el apellido** del llamante |
| `companyJsonField` | **sobrescribe/define la empresa** del llamante |
| `linkJsonField` | nombre del campo JSON cuyo valor se añade como **enlace clicable** en el pop-up (etiqueta = `name` de la acción si existe, si no «Link») — típicamente para abrir la ficha del llamante en la aplicación de negocio/CRM |

El pop-up puede así, en una sola llamada, **enriquecer la identidad del llamante** (nombre/apellido/empresa resueltos desde el CRM), **mostrar un contenido** y ofrecer un **enlace** hacia su ficha.

**Ejemplo — resolución de caller-ID + contenido + enlace desde una API REST**:

```json
"on-incoming-pbx-call-display-actions": [{
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/lookup",
    "params": "phone=${caller.phoneNumber}",
    "header": ["Authorization: Bearer eyJhbGc..."]
  },
  "responseType": "json",
  "displayJsonField":   "display",
  "firstNameJsonField": "firstName",
  "lastNameJsonField":  "lastName",
  "companyJsonField":   "company",
  "linkJsonField":      "crmUrl"
}]
```

Respuesta REST esperada (ejemplo):

```json
{ "display": "**VIP** — file #42", "firstName": "Marie", "lastName": "Curie", "company": "Sorbonne", "crmUrl": "https://crm.example.com/contacts/42" }
```

Rainbow muestra el valor de `display`, reemplaza el nombre/apellido y la empresa del llamante por los resueltos, y añade el valor de `crmUrl` como enlace clicable (etiqueta = `name` de la acción, si no «Link»).

> **⚠ Persistencia limitada** — la identidad resuelta **no persiste más allá de la sesión actual de Rainbow**; tras el cierre de la sesión, el historial de llamadas solo muestra el número bruto. Para una identificación persistente, añadir el contacto al directorio Rainbow.

**Ejemplo concreto — Markdown almacenado en un campo de texto del CRM**

Truco: almacenar **Markdown** directamente en un campo de texto del CRM (aquí `notes`). Rainbow lo muestra tal cual en la ventana emergente — negrita, emojis y **enlace clicable** incluidos. Aquí los campos están bajo un objeto `contact` (rutas `contact.*`).

Extracto del manifest:

```json
"responseType": "json",
"displayJsonField":   "contact.notes",
"firstNameJsonField": "contact.prenom",
"lastNameJsonField":  "contact.nom",
"companyJsonField":   "contact.compagnie"
```

Respuesta REST (el campo `notes` contiene Markdown):

```json
{
  "contact": {
    "id": 18,
    "prenom": "SIP",
    "nom": "BOUSSEL",
    "telephone_pro": "+333xxxxxxx",
    "telephone_mobile": "",
    "compagnie": "SIPCOmpany",
    "notes": "🏭**Support for custo team**\n🌍[Personal site](https:linkperso.com)\n"
  }
}
```

Representación en la ventana emergente de llamada entrante:

![Visualización Markdown en la ventana emergente de llamada entrante](images/incomingCallDisplaySample1.png)

#### Ejemplo 1 — ficha caller-ID en Markdown en el pop-up de llamada entrante

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-incoming-pbx-call-display-actions": [{
      "command": {
        "commandType": "rest",
        "method": "GET",
        "url": "https://api.example.com/lookup",
        "params": "phone=${caller.phoneNumber}",
        "header": ["Authorization: Bearer eyJhbGc..."]
      },
      "responseType": "markdown"
    }]
  }
}
```

#### Ejemplo 2 — widget Adaptive Card refrescado en cada apertura

```json
"on-main-widget-display-actions": [{
  "name": "My tickets",
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://api.example.com/tickets/me",
    "header": ["Authorization: Bearer ${localUser.id}"]
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField":  "data",
  "adaptiveCardSubmitUrl":         "https://api.example.com/tickets/submit"
}]
```

`adaptiveCardSubmitUrl` permite a los botones `Action.Submit` de la card hacer POST de su `data` a esa URL.

#### Ejemplo 3 — visualización declarada también para Teams

```json
"on-main-display-actions": [{
  "alsoForTeams": true,
  "command": {
    "commandType": "rest",
    "method": "GET",
    "url": "https://announcements.example.com/today"
  },
  "responseType": "markdown"
}]
```

#### Pestaña de conversación — `on-conversation-tab-actions`

> ℹ **Novedad S179.**

**Principio**: añade una **pestaña personalizada** en la columna de detalle de una conversación, para una conversación P2P y/o una conferencia (burbuja). El elemento de pestaña se define con `name`, `icon` y `tooltip`. Al seleccionarla, la acción se ejecuta —una llamada REST (`rest`), un script local/Exec (`file`) o una página web (`app`)— y el contenido devuelto se muestra en la pestaña (`markdown` o `adaptiveCard`). Durante una conferencia, la pestaña se ofrece en la lista de **herramientas de reunión**.

**Licencia**: todos los planes de servicio excepto Essential.

A diferencia de los demás displays, `responseType` es **opcional** aquí: una pestaña que solo abre una página web no devuelve ningún contenido para mostrar.

**`scope`** (array, opcional) — los contextos de conversación donde aparece la pestaña:

| Valor | Contexto |
|---|---|
| `"one_to_one"` | Conversaciones P2P |
| `"bubble"` | Conferencias (burbujas) |

Si `scope` está ausente, la pestaña se propone en todos los contextos.

**Variables permitidas**: `${localUser.*}`, todas las `${contact.*}` y todas las `${bubble.*}` (ver §7.2). `${bubble.members}` solo se puede usar con una llamada REST.

```json
"on-conversation-tab-actions": [{
  "name": "Conference Assistant",
  "scope": ["one_to_one", "bubble"],
  "tooltip": "Translation assistant",
  "icon": "${custo.path}\\assistant.png",
  "command": {
    "method": "GET",
    "commandType": "rest",
    "url": "http://www.confAssistant.com/api/lang-card?email=${localUser.email}"
  },
  "responseType": "adaptiveCard",
  "adaptiveCardTemplateJsonField": "card",
  "adaptiveCardContentJsonField": "data"
}]
```

---

### 10.4 Aplicación (Frame display)

![Aplicación WEB de terceros en un frame de Rainbow](images/applications.png)

**Principio**: embebe una **aplicación WEB de terceros** en un frame de la UI de Rainbow. Sin objeto `command` REST — es simplemente una URL cargada como un iframe. Con `popout: true`, la aplicación se abre en una ventana del navegador (en lugar de embeberse).

**Punto de extensión**:

| Clave | Ubicación |
|---|---|
| `on-main-window-actions` | Frame en la ventana principal de Rainbow |

**Requisito de licencia**: Business mínimo.

#### Campos

| Campo | Posición | Tipo | Obligatorio | Valores / restricciones |
|---|---|---|---|---|
| `name` | raíz | string | **SÍ** | "Frame name" — nombre mostrado de la aplicación en la barra de Rainbow |
| `icon` o `iconId` | raíz | string | **SÍ** (no necesario para un item que apunta solo a Mobile) | URL `https://…`, `${custo.path}\archivo.png` o sprite |
| `tooltip` | raíz | string | no | Tooltip |
| `command` | raíz | object | **SÍ** | Objeto command — al menos `url` |
| `command.url` | command | string | **SÍ** | URL HTTP(S) de la aplicación WEB a embeber |
| `command.params` | command | string | no | Parámetros URL. Variables permitidas. |
| `command.commandType` | command | string | no | Vacío por defecto → comportamiento "Browse URL" (la URL simplemente se carga) |
| `popout` | raíz | boolean | no | `true` → abre la aplicación en una ventana del navegador en lugar del frame de Rainbow |
| `devicesSupported` *(BETA S183)* | raíz | array | no | Clientes Rainbow destinatarios del item (`"web"`, `"desktop"`, `"mobile"`) — ver §6.2 |

**A tener en cuenta**:
- **Sin `method`, `bodyParameters`, `header`, `responseType`** — es una carga de URL, no una llamada API
- **Sin variables distintas de `localUser.*`** — el EP está a nivel de aplicación Rainbow, no asociado a un contacto/llamada

**Variables Rainbow permitidas**: `${localUser.*}`

#### Mobile *(BETA S183)*

`on-main-window-actions` es el primer punto de extensión disponible en Rainbow Mobile (`devicesSupported` que incluye `"mobile"`, §6.2). En Mobile, la aplicación **se abre siempre en el navegador/webview del dispositivo**, cualquiera que sea el valor de `popout`, que no se lee allí, y **sin icono** (el icono no se usa en Mobile). El manifest debe desplegarse mediante el mecanismo de administrador (cloud).

#### Seguridad

La URL cargada debe declararse como **trusted domain** en la consola de Rainbow (Company → Customization → Custo-manifest domains). De lo contrario, el navegador se negará a embeberla (CSP). Ver §12.

> **⚠ La aplicación WEB de terceros debe aceptar ser mostrada en un frame.**
> Muchos sitios rechazan por defecto el embebido en un iframe mediante:
> - la cabecera HTTP `X-Frame-Options: DENY` o `SAMEORIGIN`
> - o la directiva CSP `Content-Security-Policy: frame-ancestors 'self'`
>
> Si la aplicación destino utiliza una de estas protecciones, el frame permanecerá **vacío** (página en blanco) o mostrará un mensaje de error del navegador, sin mensaje del lado de Rainbow. Verifica estas cabeceras en el servidor de la aplicación antes de embeberla. Si la aplicación no es modificable, la alternativa es `popout: true` para abrir la app en una ventana del navegador en lugar de un frame.

#### Ejemplo 1 — embeber una aplicación WEB de negocio

```json
{
  "version": "2",
  "jsonType": "Rainbow-custo-manifest",
  "extension-points": {
    "on-main-window-actions": [{
      "name": "Mi CRM",
      "icon": "${custo.path}\\crm.png",
      "command": {
        "url": "https://crm.example.com/dashboard",
        "params": "user=${localUser.email}"
      }
    }]
  }
}
```

La aplicación aparece en Rainbow con el nombre "Mi CRM". Al hacer clic, el dashboard CRM se carga en el frame, con el email del usuario como parámetro.

#### Ejemplo 2 — apertura en el navegador (en lugar del frame)

```json
"on-main-window-actions": [{
  "name": "Reporting externo",
  "icon": "${custo.path}\\report.png",
  "popout": true,
  "command": {
    "url": "https://reporting.example.com/",
    "params": "user=${localUser.loginEmail}"
  }
}]
```

`popout: true` → la aplicación se abre en una ventana del navegador. Útil cuando la aplicación rechaza ser embebida (CSP frame-ancestors restrictiva) o cuando se quiere un espacio de trabajo grande.

#### Ejemplo 3 — aplicación sin autenticación de usuario (estática)

```json
"on-main-window-actions": [{
  "name": "Wiki",
  "icon": "${custo.path}\\wiki.png",
  "command": {
    "url": "https://wiki.example.com/"
  }
}]
```

## 11. Creación & despliegue

El despliegue de un manifest se puede realizar de dos maneras:

- **Localmente**, mediante importación del archivo (o del ZIP) por el usuario final en el cliente Rainbow.
- **Automáticamente desde la nube**, cuando el administrador ha asignado el manifest al usuario a través de la consola Rainbow. El cliente lo descarga entonces al arrancar, sin acción del usuario.

El despliegue local se recomienda para la **fase de pruebas** o si hay **pocos usuarios** afectados. El administrador puede prohibir este modo mediante un **flag de perfil**: en ese caso, la opción Importar/Exportar desaparece del lado del usuario.

**El despliegue del administrador tiene prioridad**: un manifest asignado por el admin reemplaza cualquier manifest local y el usuario no puede sobreescribirlo.

**Alcance**: el despliegue del administrador se aplica a **todas las instancias** del cliente Rainbow del usuario (Desktop, Web, en todas las máquinas/sesiones). El despliegue local, en cambio, solo afecta a **la máquina o el navegador usados para la importación** — no sigue al usuario en sus otros puestos.

### 11.1 Creación

Hay varias formas de obtener un archivo manifest inicial:

**Desde el cliente Rainbow Desktop (export de un template)**

Es posible obtener un archivo template localmente solicitando una exportación **mientras no se haya importado todavía ningún manifest**. El cliente genera entonces un archivo de ejemplo que contiene todos los puntos de extensión soportados.

1. En el cliente Rainbow Desktop: **Settings → Telephony → Customization → Export**
2. Eliminar los puntos de extensión no utilizados (mantener solo los que se quieren configurar)
3. Rellenar el contenido de cada uno de los EPs conservados (`name`, `icon`, `command`, etc.)
4. Importar para probar en local

**Desde una herramienta de generación o un ejemplo**

Las herramientas de generación de manifest (por ejemplo el **Rainbow Generator** de ALE) o los **ejemplos** suministrados en esta documentación también pueden servir de punto de partida — basta con copiar la estructura JSON, adaptarla al contexto de negocio e importarla.

### 11.2 ZIP con recursos

Si el manifest referencia archivos locales (iconos, textos, scripts), crear un ZIP que contenga el manifest **y** los archivos de recursos, y luego importarlo en el cliente.

**Recordatorios** (cf. §7.6):
- Referenciar cada recurso del ZIP por `${custo.path}\\nombre-de-archivo.ext` en el manifest.
- Incluir el campo `"jsonType": "Rainbow-custo-manifest"` en la raíz del manifest — es lo que permite a Rainbow identificar el archivo manifest dentro del ZIP. De lo contrario, Rainbow busca un archivo llamado exactamente `custo-manifest.json`.

**Compatibilidad Web / Desktop**: el ZIP es compatible con los dos clientes Rainbow. En Desktop, los recursos se escriben en disco; en Web, se cargan en memoria desde el ZIP descargado. El mismo ZIP puede por tanto desplegarse indistintamente para ambas plataformas.

### 11.3 Mass provisioning (por administrador)

**Company → Information → Customization → Custo-manifest**

1. Importar el manifest en la administración central de Rainbow
2. Asignar un manifest a los usuarios:
   - mediante la web de administración (Member → Information → custo-manifest)
   - mediante CSV
   - mediante conector LDAP: mapear el campo `selectedManifestName` con el atributo LDAP correspondiente
3. El cliente Rainbow descarga automáticamente el manifest al arrancar:
   - La opción `/Custom` del setup se **ignora**
   - La entrada Importar/Exportar en Settings queda **oculta** para el usuario

### 11.4 Setup CLI

> **⚠ Procedimiento obsoleto** — privilegiar el **despliegue del administrador** (§11.3), que tiene prioridad sobre este modo antiguo y ofrece una gestión centralizada. Este modo CLI se conserva por retrocompatibilidad con integraciones Desktop antiguas.

Al iniciar el setup de Rainbow:
```
RainbowSetup.exe /Custom=C:\path\to\manifest.json
```
A tener en cuenta: `/Custom` también oculta la opción Importar/Exportar del usuario.

---

## 12. Seguridad (S170)

### 12.1 Mecanismos web estándar

Las extensiones se ejecutan en la aplicación Web de Rainbow (incluso cuando está embebida en Desktop). Se aplican las protecciones web estándar:

- **CSP** (Content-Security-Policy) — Rainbow solo puede cargar una página o invocar una API si el dominio está en la lista blanca
- **CORS** (Cross-Origin) — el servidor REST debe aceptar explícitamente a Rainbow como origen
- **LNA** (Local Network Access) — el acceso a máquinas/servidores locales puede ser denegado por el navegador
- **CSP del lado remoto** — el servidor puede negarse a ser embebido en un frame de Rainbow

### 12.2 Trusted domains (nuevo en S170)

#### Qué controla

Toda URL referenciada en un manifest (llamada REST o iframe) debe tener su **origen** declarado como trusted en la consola Rainbow. Esto aplica a:

- `command.url` en todos los extension points (llamadas REST, navegación de archivos)
- `command.url` en `on-main-window-actions` (web app embebida en el frame)
- `adaptiveCardSubmitUrl`
- `urlConfig` (URL de configuración del widget)

La declaración es **global para toda la empresa**: cubre todos los manifests desplegados en la empresa y todos los usuarios.

> **Excepción `popout: true`** — cuando `on-main-window-actions` usa `popout: true`, la URL se abre en una **ventana de navegador dedicada**, no dentro del frame de Rainbow. El control de trusted domains está **desactivado** en ese caso: se aplica la seguridad nativa del navegador y Rainbow no impone su propio CSP para esa URL.

> **Flujos SSO / OAuth** — si la aplicación web embebida desencadena un flujo de autenticación (SSO, OAuth, SAML…), el proveedor de identidad suele encontrarse en un **dominio diferente** al de la aplicación (p. ej. `login.microsoftonline.com`, `accounts.google.com`, un IdP interno…). Rainbow intentará cargar esas URLs de redirección dentro del mismo frame, por lo que **cada dominio involucrado en el flujo de autenticación también debe declararse como trusted** — no solo el origen de la aplicación. No declarar el dominio del IdP resulta en un frame en blanco en el paso de login, aunque la URL de la aplicación esté correctamente en la lista blanca.

#### Dónde configurar

**Company → Information → Customization → Custo-manifest domains**

Añadir una entrada por origen. Cada entrada debe seguir el formato:

```
<protocolo>://<dominio>[:<puerto>]
```

| Parte | Reglas |
|---|---|
| `protocolo` | `https` o `http` — **obligatorio** |
| `dominio` | Nombre de host exacto o wildcard (`*.example.com`) |
| `puerto` | Opcional. Omitir para puertos estándar (443 para https, 80 para http). |
| `/` final | **No permitido** — la entrada es rechazada o no coincide si termina en `/` |

#### Restricciones de protocolo (HTTP / HTTPS)

Declarar un origen como trusted **no es suficiente**: el navegador aplica además sus propias reglas sobre el protocolo. La aplicación Web Rainbow se sirve mediante **HTTPS**, por lo tanto:

- **`http://` solo se acepta para `localhost` / `127.0.0.1` (loopback).** Cualquier otro origen HTTP (IP de LAN, nombre de máquina, dominio público) es **bloqueado por el navegador** (regla *mixed content*), aunque la entrada esté correctamente declarada en la consola. Una entrada como `http://192.168.1.100:3300` se acepta como formato pero la llamada REST fallará silenciosamente en ejecución.
- **`https://` exige un certificado de servidor válido.** El certificado debe estar emitido por una **autoridad reconocida** (CA pública, o CA de empresa instalada en el equipo) y coincidir con el nombre de host. Un certificado **autofirmado, expirado o con nombre incorrecto** es rechazado por el navegador: la llamada REST falla y un frame embebido queda **en blanco**, sin mensaje de error dentro de Rainbow.

> **En resumen**: HTTPS con certificado válido en todas partes, salvo `localhost`/`127.0.0.1` donde se tolera HTTP (útil solo para desarrollo local).

#### Ejemplos válidos

| Entrada | Coincide con |
|---|---|
| `https://crm.example.com` | `https://crm.example.com/cualquier/ruta` |
| `https://crm.example.com:8443` | `https://crm.example.com:8443/cualquier/ruta` |
| `https://*.example.com` | `https://crm.example.com`, `https://api.example.com`, … |
| `http://localhost:3300` | Servidor local de desarrollo — único caso en que se acepta HTTP en ejecución |

#### Ejemplos inválidos

| Entrada | Problema |
|---|---|
| `crm.example.com` | Protocolo ausente |
| `https://crm.example.com/` | Barra final — rechazado |
| `https://crm.example.com/api` | Ruta no permitida — declarar solo el origen |
| `http://192.168.1.100:3300` | Formato aceptado, pero **bloqueado en ejecución** — HTTP no permitido fuera de `localhost` (mixed content) |
| `https://` con certificado autofirmado | Rechazado por el navegador — certificado no reconocido |

#### Comportamiento si el dominio no está declarado

| Situación | Efecto |
|---|---|
| Manifest cargado por el cliente | **Advertencia mostrada al usuario** — el manifest contiene dominios no trusted |
| Llamada REST (`commandType: "rest"`) | Llamada bloqueada por el navegador (CSP / CORS) — sin popup, sin mensaje de error en Rainbow |
| Frame (`on-main-window-actions`) | El frame se muestra pero la página está **en blanco** (o muestra un error de seguridad del navegador) |

> **⚠ La advertencia aparece al cargar el manifest, antes de que se active cualquier extensión.** Si el usuario ignora la advertencia, las extensiones que apuntan a dominios no declarados fallarán silenciosamente en tiempo de ejecución.

### 12.3 CORS

Aunque un dominio esté declarado como trusted en Rainbow, el **navegador** aplica CORS de forma independiente. El servidor REST debe devolver:

```
Access-Control-Allow-Origin: https://web.openrainbow.com
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization
```

El valor exacto de `Access-Control-Allow-Origin` depende de la plataforma Rainbow. Usar las herramientas de desarrollo del navegador (pestaña Red) para identificar el header `Origin` enviado por Rainbow en la solicitud bloqueada. Alternativamente, usar el comodín:

```
Access-Control-Allow-Origin: *
```

> **Limitación del comodín** — incompatible con las credenciales del navegador (`withCredentials: true`, cookies de sesión). Para extensiones Rainbow que pasan un token a través del campo `header` del manifiesto (p. ej. `Authorization: Bearer …`), el comodín funciona porque Rainbow envía el token como un header HTTP estándar. Para autenticación basada en cookies, declarar el origen Rainbow explícitamente y añadir `Access-Control-Allow-Credentials: true`.

> **Breaking change** — un manifiesto que funcionaba antes de S170 puede dejar de funcionar si el servidor REST no devuelve los headers CORS. No se muestra ningún error en Rainbow — la llamada falla silenciosamente.

### 12.4 Local Network Access (LNA)

Si el servidor REST se ejecuta en una **red local o privada** (p. ej. `https://192.168.1.100:8443`), Chrome y Edge aplican la política de **Private Network Access**.

> **HTTP bloqueado antes** — un servidor local en HTTP (p. ej. `http://192.168.1.100:3300`) ya está bloqueado por la regla *mixed content* (ver §12.2) **antes** de que intervenga el LNA. En la práctica, el LNA solo concierne a los servidores locales servidos mediante **HTTPS** (o la excepción `localhost`).

> **Rainbow Desktop no se ve afectado** — solo Rainbow Web está sujeto a las reglas LNA del navegador.

> **Navegadores afectados** — LNA solo lo aplica **Chrome y Edge (basados en Chromium)**. Firefox y Safari no implementan esta política.

El navegador envía un preflight OPTIONS con `Access-Control-Request-Private-Network: true`. El servidor debe responder con:

```
Access-Control-Allow-Private-Network: true
```

además de los headers CORS estándar.

> **Permiso del usuario (Chrome/Edge)** — incluso con los headers del servidor correctos, Chrome puede mostrar una solicitud de permiso: *«¿Permitir que [sitio] acceda a los recursos de su red local?»*. El usuario debe conceder este permiso explícitamente. También se puede gestionar en `chrome://settings/content/privateNetworkDevices`.

### 12.5 Seguridad de las aplicaciones embebidas

Cuando `on-main-window-actions` carga una URL en el frame de Rainbow, la aplicación de destino puede negarse a ser embebida mediante headers del servidor:

| Header | Valor típico | Efecto |
|---|---|---|
| `X-Frame-Options` | `DENY` o `SAMEORIGIN` | El navegador se niega a renderizar la página en el iframe — frame en blanco |
| `Content-Security-Policy` | `frame-ancestors 'self'` o `'none'` | Mismo efecto, mecanismo moderno |

Esto es independiente de la declaración de trusted domains — un dominio declarado puede igualmente negarse al embebido en iframe.

**Solución:** configurar la aplicación para que permita el origen Rainbow en `frame-ancestors`, o cambiar a `popout: true` en `on-main-window-actions`.

> **Flujos SSO / OAuth** — el proveedor de identidad normalmente establece `X-Frame-Options: DENY` por razones de seguridad. En ese caso, SSO no puede completarse en el iframe independientemente de las declaraciones de dominio. Usar `popout: true`.

### 12.6 Caso especial de ejecución local

`commandType: "file"` (ejecución de un `.exe` o script local) **no está controlado por estos mecanismos**. Para prohibir este tipo de extensión a nivel empresarial: impedir que el usuario cargue un manifiesto y desplegar solo a través de la nube Rainbow.

---

## 13. Buenas prácticas

### 13.1 Construcción

1. **Partir de un template** exportado por Rainbow Desktop, eliminar los EPs inútiles
2. Hacer una **importación local** para validar la sintaxis antes del despliegue central
3. Verificar que todas las referencias sean **portables** (sin rutas codificadas a la máquina del desarrollador)
4. Para los recursos locales: usar sistemáticamente `${custo.path}\…` + ZIP
5. Probar en **Web** y **Desktop** (salvo si el EP es exclusivo Desktop)

### 13.2 Seguridad

- Declarar **todos** los dominios REST destino en la consola Rainbow antes del despliegue
- Verificar las **cabeceras CORS** del servidor REST (`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`)
- Usar siempre **HTTPS con un certificado válido** (no autofirmado) — HTTP solo se acepta para `localhost`/`127.0.0.1` (ver §12.2)
- Para servidores REST en una **red local/privada** (servidos mediante HTTPS): añadir `Access-Control-Allow-Private-Network: true` — Chrome/Edge aplican LNA (ver §12.4)
- **Nunca** poner un secreto en claro en el manifest (es descargado por cada cliente)
- Para apps embebidas que rechazan el iframe: usar `popout: true` o configurar `frame-ancestors` en la app de destino (ver §12.5)

### 13.3 Variables

- Usar solo las variables documentadas para el EP — las variables no admitidas se vacían silenciosamente
- Para las regex: doblar las `\` en el JSON (`\\+33` para `\+33`)
- Mantener los correladores por debajo de **32 caracteres**

### 13.4 Adaptive Cards

- Privilegiar el patrón "Template en manifest + Datos vía REST": permite modificar los datos en el servidor sin volver a desplegar el manifest
- Usar `${variable}` en el template y proporcionar los valores en el contenido
- `Action.Submit` envía todo el objeto `data` de la acción

---

## 14. Validación y depuración

Un **validador custo-manifest** está disponible en el lado ALE para verificar:
- estructura del manifest (`version`, `jsonType`, `extension-points`)
- conformidad campo a campo según cada EP
- presencia de los iconos obligatorios
- variables Rainbow permitidas para el EP
- sintaxis `${object.attribute}` (vs `$(object.attribute)` o `$[object.attribute]`)
- rutas absolutas vs recursos `${custo.path}`
- compatibilidad `commandType` / `method` / `bodyParameters` / `header` / `responseType`

También ofrece correcciones automáticas (añadir icono faltante, mover campos mal ubicados de vuelta a la raíz o bajo `command`, eliminar campos no admitidos, convertir rutas absolutas en recursos).

---

## 15. Historial de versiones

| Versión | Aportaciones principales |
|---|---|
| **S156** | Event `on-outgoing-pbx-call-actions` · Mass provisioning por admin · Correlador en makecall · Multi-extensiones (hasta 3) |
| **S161** | Custo-manifest parcialmente soportado en WEB · Variable `contact` (card info) |
| **S170** | Custom widget extension (área de widget libre) · Custo-manifest **completo** en Web y Desktop · Endurecimiento REST (trusted domains + CORS) |
| **S179** | Extensión `on-conversation-tab-actions` (pestaña personalizada en el detalle de una conversación, P2P o conferencia — `scope`) · `linkJsonField` (hipervínculo a la aplicación de negocio/CRM del llamante) |
| **S183** | `redirectUrl` *(preview beta)* — en los events de llamada y los botones, abre un navegador en una URL calculada a partir de la respuesta JSON de una llamada REST (`${response}`) · `devicesSupported` / `defaultDevicesSupported` *(preview beta)* — clientes destinatarios de un item (web, desktop, mobile, teams); primer paso Mobile en `on-main-window-actions` · `markdownTemplate` *(preview beta)* — plantilla Markdown rellenada con las variables Rainbow y la respuesta JSON de una llamada REST, en los EPs que muestran Markdown |

---

---

*Documento generado a partir de la presentación S170 (abril 2026) y de la especificación funcional Rainbow custo-manifest. Para cualquier corrección o adición, contactar con el equipo Product Management Rainbow.*
