# Rainbow Extensions — Custo-Manifest

**Référence S170 — avril 2026**
*Source : présentation S170 Roadmap + spécification fonctionnelle Rainbow*

---

## 1. Vue d'ensemble

Les **Rainbow Extensions** (aussi appelées *Custo-Manifest*) permettent d'intégrer Rainbow Web/Desktop avec l'écosystème métier d'un client **sans code** — uniquement en déposant un fichier JSON de configuration. Une extension :

- réagit à un événement Rainbow (appel entrant, sortant…) ;
- ajoute un bouton dans une partie de l'UI (liste de contacts, journal d'appels, etc.) ;
- affiche un contenu (Markdown, JSON, Adaptive Card) dans un emplacement Rainbow ;
- ou ouvre une application tierce dans une frame ou dans un browser.

### Bénéfices

- **No-code** : configuration JSON seulement
- Augmente la **productivité utilisateur** (actions un clic, données contextuelles)
- **Business enabler** pour les partenaires (intégration CRM, ticketing, domotique…)

### Types d'interaction supportés

| Type | Effet |
|---|---|
| `commandType: "file"` | Lit un fichier — local sur Desktop, ou inclus dans le ZIP du manifest sur Web |
| `commandType: "rest"` | Appel HTTP GET ou POST vers une API |
| Ouverture web | Ouvre une URL dans le navigateur |
| Exécution native (Desktop uniquement) | Lance un `.exe` ou un script local |

### Formats d'affichage supportés

- **Markdown** (par défaut) — peut aussi être extrait d'un champ d'une réponse JSON via `displayJsonField`
- **Adaptive Card** (template + données)

### Pré-requis licences

Seules les extensions de type **Event** sont supportées avec une licence **Essentials**.
Les autres extensions nécessitent au minimum une licence **Business**.

### Web vs Desktop

Depuis **S161**, le custo-manifest est progressivement migré du Desktop vers le Web. À partir de **S170**, toutes les extensions sont disponibles sur Rainbow Web ET Desktop, **à l'exception de l'exécution locale d'application/script** (lancement d'un `.exe` ou script) qui reste Desktop-only. Pour `commandType: "file"` côté Web, le fichier doit être inclus dans le ZIP du manifest.

**Mobile** *(BETA S183)* : une première étape rend `on-main-window-actions` disponible sur Rainbow Mobile — voir §6.2.

---

## 2. Structure du fichier manifest

Le custo-manifest est un objet JSON respectant ce squelette :

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

### Règles globales

- `version` doit valoir `"2"`.
- `jsonType` doit valoir `"Rainbow-custo-manifest"`. Ce champ sert à identifier, à l'intérieur d'un ZIP, quel fichier JSON est le manifest.
- Chaque clé d'`extension-points` est un tableau (jusqu'à **3 actions** maximum par point d'extension).
- Chaque action contient au moins un `name` (sauf events où il est optionnel) et un objet `command` valide.
- `defaultDevicesSupported` *(BETA S183)* — tableau optionnel à la racine du manifest : les clients Rainbow ciblés par défaut par tous les items (voir §6.2).

---

## 3. Liste des points d'extension

### 3.1 Events — événements automatiques (sans affichage)

| Clé | Déclenché quand… |
|---|---|
| `on-outgoing-pbx-call-actions` | Un appel sortant est lancé |
| `on-incoming-pbx-call-actions` | Un appel entrant arrive |
| `on-answering-incoming-pbx-call-actions` | Un appel entrant est décroché |
| `on-releasing-incoming-pbx-call-actions` | Un appel entrant est terminé |
| `on-makecall-insert-correlator` | À chaque makecall — insère un corrélateur (OXE only) |

### 3.2 Buttons — boutons cliquables (avec affichage optionnel du résultat)

| Clé | Emplacement du bouton |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up d'appel entrant |
| `on-call-log-list-actions` | Chaque ligne du journal d'appels |
| `on-contact-list-actions` | Chaque ligne de la liste des contacts |
| `on-contact-detail-actions` | Zone détaillée d'un contact |
| `on-communication-card-actions` | Barre du gestionnaire d'appels |
| `on-bubble-actions` | Menu propriété de la bulle |
| `on-bubble-conference-actions` | Menu de conférence téléphonique |
| `on-user-menu-actions` | Menu utilisateur (Desktop / Web — pas Teams) |

### 3.3 Displays — affichage automatique d'informations

| Clé | Emplacement |
|---|---|
| `on-incoming-pbx-call-display-actions` | Insertion dans la pop-up d'appel entrant |
| `on-contact-card-display-actions` | Insertion dans la zone détaillée du contact |
| `on-main-widget-display-actions` | Widget dans le panneau principal Rainbow |
| `on-main-display-actions` | Message dans Webapp Teams |
| `on-conversation-tab-actions` *(Nouveauté S179)* | Onglet personnalisé dans le détail d'une conversation (P2P ou conférence) |

### 3.4 Frame display — application WEB tierce

| Clé | Description |
|---|---|
| `on-main-window-actions` | Affiche une application WEB tierce dans une frame Rainbow. Avec `popout: true`, ouvre l'application dans une fenêtre du navigateur. |

---

## 4. Champs principaux d'une action

| Champ | Position | Description |
|---|---|---|
| `name` | racine | Texte affiché (titre du bouton/widget, libellé du menu). Obligatoire selon l'EP. |
| `icon` / `iconId` | racine | Icône du bouton (URL, `${custo.path}\…` ou sprite intégré). Obligatoire pour les boutons icone. |
| `tooltip` | racine | Texte d'info-bulle. Optionnel. |
| `command` | racine | Objet de commande (voir §5). **Toujours obligatoire**. |
| `responseType` | racine | `"markdown"` (défaut), `"json"` ou `"adaptiveCard"`. |
| Champs Adaptive Card | racine | `adaptiveCardTemplate`, `adaptiveCardTemplateJsonField`, `adaptiveCardContentJsonField`, `adaptiveCardSubmitUrl` |
| `displayJsonField` | racine | Nom du champ contenant le markdown à afficher (quand la réponse est JSON) |
| `redirectUrl` *(BETA S183)* | racine | **Events d'appel et boutons** — template d'URL ouverte dans une nouvelle fenêtre du navigateur une fois l'appel REST terminé ; nécessite `responseType: "json"` (cf. §10.1 et §10.2). |
| `markdownTemplate` *(BETA S183)* | racine | **EP d'affichage et boutons** — template Markdown affiché après substitution des variables Rainbow et de `${response...}` (corps JSON de l'appel REST) ; nécessite `commandType: "rest"` et `responseType: "json"` (cf. §8.4). |

### Tableau de référence par EP

> Synthèse des règles : `name` mandatory/n/a, icon mandatory/n/a, commandType autorisé, responseType autorisé, etc.

| Extension Point | name | icon | commandType | responseType |
|---|---|---|---|---|
| `on-outgoing-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatoire** avec `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatoire** avec `redirectUrl` — BETA S183) |
| `on-answering-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatoire** avec `redirectUrl` — BETA S183) |
| `on-releasing-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **obligatoire** avec `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-button-actions` | "Button text" | n/a | `rest` | optionnel |
| `on-contact-list-actions` | n/a | mandatory | `rest`, `file` | optional |
| `on-contact-detail-actions` | n/a | mandatory | `rest`, `file` | optional |
| `on-call-log-list-actions` | n/a | mandatory | `rest`, `file` | optional |
| `on-communication-card-actions` | "menu text" | mandatory | `rest`, `file` | optional |
| `on-bubble-actions` | "menu text" | mandatory | `rest`, `file` | optional |
| `on-bubble-conference-actions` | "menu text" | mandatory | `rest`, `file` | optional |
| `on-incoming-pbx-call-display-actions` | n/a | n/a | `rest`, `file` | **mandatory** |
| `on-contact-card-display-actions` | n/a | n/a | `rest`, `file` | **mandatory** |
| `on-main-widget-display-actions` | "widget title" | n/a | `rest`, `file` | **mandatory** |
| `on-main-display-actions` | n/a | n/a | `rest`, `file` | **mandatory** |
| `on-conversation-tab-actions` | "nom d'onglet" | mandatory | `rest`, `file`, `app` | optional |
| `on-main-window-actions` | "Frame name" | mandatory | Browse URL (par défaut, `commandType` vide) | n/a |
| `on-user-menu-actions` | "menu item title" | n/a | `rest`, `file` | optional |

> `redirectUrl` *(BETA S183)* est accepté sur les 4 events d'appel (§10.1) et sur les 8 EP boutons (§10.2). Il nécessite `responseType: "json"` (obligatoire) — le combiner avec `"markdown"` ou `"adaptiveCard"`, ou omettre `responseType`, est invalide (une redirection remplace l'affichage).

---

## 5. L'objet `command`

L'objet `command` est **toujours obligatoire** et porte au minimum un `url`. Selon le `commandType` choisi, des sous-champs supplémentaires sont valides.

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

| Champ | Quand l'utiliser |
|---|---|
| `url` | **obligatoire**. Path d'application, URL Web, fichier ou Rest API. |
| `params` | Optionnel. Concaténé après `?` pour GET, ou comme paramètres URL. Variables autorisées. |
| `commandType` | Optionnel. Par défaut `"rest"`. Valeurs : `"rest"`, `"file"` (selon EP). |
| `method` | Optionnel (si `commandType: "rest"` uniquement). Valeurs : `"GET"`, `"POST"`. |
| `header` | Optionnel (si REST). Tableau de strings `"Header-Name: value"` insérés comme entêtes HTTP. |
| `bodyParameters` | **Obligatoire si `method: "POST"`**. Objet JSON envoyé en body. Variables autorisées. |

---

## 6. Champs secondaires (selon EP)

| Champ | EP concernés | Effet |
|---|---|---|
| `AnswerOnClick` | `on-incoming-pbx-call-button-actions` | `true` → exécute l'action ET décroche l'appel en un clic |
| `NoShortNumber` (boolean) | events d'appel | Ne déclenche pas l'event si le numéro appelant est un numéro court |
| `RaiseChangeCall` | events entrants | `true`, `false`, `"Only"` — comportement sur transfert distant (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`, et les 8 EP boutons (§3.2) | Template d'URL ouverte dans une nouvelle fenêtre du navigateur après l'appel REST. Variables autorisées (variables Rainbow et `${response...}`, cf. §7.7). Nécessite `responseType: "json"`. |
| `popout` (boolean) | `on-main-window-actions` | `true` → ouvre l'application WEB dans une fenêtre du navigateur (au lieu de l'afficher dans la frame Rainbow). |
| `alsoForTeams` (boolean) | `on-call-log-list-actions`, `on-main-display-actions` | Affiche l'extension aussi dans l'add-in Teams — **déprécié**, utiliser `devicesSupported` (§6.2) |
| `markdownTemplate` *(BETA S183)* | tous les EP qui affichent du Markdown (EP d'affichage et boutons, §8.4) | Template Markdown renseigné avec les variables Rainbow et `${response...}`. Nécessite `commandType: "rest"` et `responseType: "json"`. |
| `devicesSupported` *(BETA S183)* | tous (`"mobile"` et `"teams"` uniquement sur certains EP — voir §6.2) | Tableau des clients Rainbow auxquels l'item s'applique : `"web"`, `"desktop"`, `"mobile"`, `"teams"`. Remplace `defaultDevicesSupported` pour cet item. |
| `scope` (array) | `on-conversation-tab-actions` | Contextes de conversation où l'onglet apparaît : `"one_to_one"` (P2P), `"bubble"` (conférence). Absent → tous les contextes. |
| `urlConfig` | `on-main-widget-display-actions` | URL HTTP/HTTPS de configuration du widget |
| `firstNameJsonField`, `lastNameJsonField`, `companyJsonField` | `on-incoming-pbx-call-display-actions` UNIQUEMENT | Identification du caller (réponse JSON) |
| `linkJsonField` *(Nouveauté S179)* | `on-incoming-pbx-call-display-actions` UNIQUEMENT | Champ JSON dont la valeur est affichée comme **lien hypertexte** pour ouvrir l'application métier/CRM de l'appelant (libellé du lien = `name` de l'action si présent, sinon « Link ») |

### 6.1 Valeurs de `RaiseChangeCall`

| Valeur | Comportement |
|---|---|
| `false` (défaut) | Seuls les appels directs sont notifiés |
| `true` | Appels directs **ET** transférés |
| `"Only"` | Uniquement les appels transférés |

### 6.2 Clients ciblés — `devicesSupported` *(BETA S183)*

> ⚠ **BETA (S183)** — cette fonctionnalité est en beta et peut évoluer avant la disponibilité générale.

Par défaut, chaque item s'applique à **Rainbow Web et Desktop**. Deux attributs optionnels permettent de déclarer les clients Rainbow auxquels un item s'applique :

| Attribut | Position | Rôle |
|---|---|---|
| `defaultDevicesSupported` | racine du manifest (à côté de `version`, `jsonType`, `extension-points`) | Clients ciblés par défaut par **tous** les items du manifest |
| `devicesSupported` | racine d'un item (même niveau que `scope`) | **Remplace** `defaultDevicesSupported` pour cet item uniquement (remplacement complet, pas de fusion) |

Valeurs autorisées pour les deux : `"web"`, `"desktop"`, `"mobile"`, `"teams"`.

**Ordre de résolution** pour un item donné : `devicesSupported` de l'item (s'il est présent) → sinon `defaultDevicesSupported` du manifest (s'il est présent) → sinon la valeur par défaut intégrée `["web", "desktop"]`. Un manifest qui n'utilise aucun des deux attributs se comporte exactement comme avant : aucune migration n'est nécessaire.

**Disponibilité de chaque client**

| Client | Valide sur |
|---|---|
| `"web"`, `"desktop"` | tous les points d'extension |
| `"mobile"` | `on-main-window-actions` **uniquement** (première étape) |
| `"teams"` | `on-call-log-list-actions`, `on-main-display-actions` |

**Règles**
- Un client demandé **explicitement sur un item** (`devicesSupported`) pour un point d'extension hors de la liste ci-dessus est signalé comme **avertissement** (warning) par le Rainbow Validator.
- Un client seulement **hérité** de `defaultDevicesSupported` et qui ne s'applique pas au point d'extension de l'item est **ignoré silencieusement** — pas d'avertissement.
- `alsoForTeams` est **déprécié** au profit de `devicesSupported`, mais continue de fonctionner : `alsoForTeams: true` ajoute `"teams"` aux clients effectifs de l'item. Le Rainbow Validator signale un avis de dépréciation.

**Mobile (première étape)**
- Seul **`on-main-window-actions`** est disponible sur Mobile. Sur Mobile, il **ouvre toujours l'application externe dans le navigateur/la webview de l'appareil** : il n'y a pas d'embarquement en frame sur Mobile, le champ `popout` de l'item n'y est donc **pas lu** (il continue de déterminer frame ou fenêtre sur Web/Desktop). Il est aussi affiché **sans icône** : `icon` / `iconId` n'est pas utilisé sur Mobile, un item ciblant uniquement Mobile (`devicesSupported` sans `"web"` ni `"desktop"`) n'en a donc pas besoin.
- Sur Mobile, le manifest est chargé **uniquement par déploiement cloud (administrateur)** ; l'import local n'est pas supporté.

**Exemple**

```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* hérite de la valeur par défaut du manifest et est donc exposé sur Mobile.
- *Internal only* la remplace et est donc exclu de Mobile.
- L'item `on-main-display-actions` est l'équivalent, nouveau style, de `alsoForTeams: true`.

---

## 7. Variables Rainbow

Les **`$Variables`** sont remplacées à l'exécution par leur valeur réelle. Elles peuvent apparaître dans :

- `command.url`
- `command.params`
- `command.bodyParameters`
- `urlConfig`, `adaptiveCardSubmitUrl`
- `redirectUrl` *(BETA S183)* — events d'appel et boutons uniquement (§10.1, §10.2)
- `markdownTemplate` *(BETA S183)* — les EP qui affichent du Markdown (§8.4)
- `${response...}` *(BETA S183)* est disponible **uniquement** dans `redirectUrl` et `markdownTemplate` (§7.7)
- le **contenu retourné à l'extension pour affichage** : peut aussi contenir des variables Rainbow qui seront substituées avant affichage

### 7.1 Syntaxe

```
${objet.attribut}
${objet.attribut.regex(pattern)}
${objet.attribut.regex(pattern, replacement)}
```

### 7.2 Objets et attributs disponibles

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

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

**Called (appelé)**
```
${called.phoneNumber}
```

**Call context**
```
${call.callId}
${call.globalCallId}      (OXE uniquement)
${call.correlatorData}
${call.hexCorrelatorData}
```

**Contact (si identifié)**
```
${contact.id}            (identifiant CRM — ex. deeplink d'ouverture de fiche)
${contact.firstName}     ${contact.lastName}
${contact.phoneNumber}   ${contact.email}
${contact.company}       ${contact.workNumber}
${contact.mobileNumber}  ${contact.personalNumber}
${contact.personalMobile}
${contact.tags}          (concaténés, séparés par ',')
```

**Bubble (groupe de conversation)**
```
${bubble.ownerEmail}   ${bubble.name}      ${bubble.shareLink}
${bubble.id}           (Cpaas)
${bubble.members}      → JSON {"organizersEmails":[…], "membersEmails":[…]}
                         **Utilisable uniquement avec un appel REST**
```

**Time (timestamp)**
```
${time}             full date time
${time.year}        ${time.month}
${time.hour}        ${time.minute}    ${time.second}    ${time.millisec}
${time.hex}         4 bytes hex pour Unix Epoch (uniquement avec hexCorrelatorData)
```

### 7.3 Compatibilité par EP

Chaque EP autorise un sous-ensemble d'objets. Synthèse :

| EP | Objets variables autorisés |
|---|---|
| Events d'appel sortant | `localUser`, `called`, `call`, `contact` |
| Events d'appel entrant (incoming/answering/releasing) | `localUser`, `caller`, `called`, `call`, `contact` |
| Insertion automatique d'un correlator OXE | `localUser`, `called` |
| Boutons icone (contact-list, contact-detail, call-log-list, contact-card-display) | `localUser`, `contact` |
| Boutons d'appel (communication-card, incoming-button, incoming-display) | `localUser`, `caller`, `called`, `call`, `contact` |
| Bubbles | `localUser`, `bubble` |
| Onglet de conversation | `localUser`, `contact`, `bubble` |
| Display widget / main-display / main-window / user-menu | `localUser` |

### 7.4 Modifier `regex`

Applique une regex sur la valeur de la variable **avant substitution**. ⚠ Rainbow ne trim **pas** les espaces autour de la virgule séparant `pattern` et `replacement` — une espace après la virgule se retrouve littéralement dans le résultat (confirmé en réel 2026-10-02, ex. `regex(@.*$, @example.com)` produit `"nom @example.com"` avec une espace parasite). N'utiliser **aucune espace** autour de la virgule :

```jsonc
// Remplace +33 ou +1 par 0 (normalise un numéro)
"params": "pbx=${localUser.phonePbx.regex(^\\+33|^\\+1,0)}"

// Remplace le domaine email
"params": "byEmail=${localUser.email.regex(alcatel.com,al-enterprise.com)}"

// Garde les 9 derniers chiffres (regex sans replacement = extraction)
"params": "${called.phoneNumber.regex(.{0,9}$)}"
```

### 7.5 Variable `${time}` — horodatage

Variable spéciale d'horodatage, disponible sur **tous les EPs**. Substituée à l'instant où l'action est exécutée.

| Variable | Valeur | Format / commentaire |
|---|---|---|
| `${time}` | Date-heure complète | `YYYY/MM/DD HH:MM:SS`, ex. `2026-05-18 15:30:45` (pas d'ISO 8601, pas de millisecondes — confirmé en réel 2026-10-02) |
| `${time.year}` | Année | 4 chiffres, ex. `2026` |
| `${time.month}` | Mois | 2 chiffres, `01`–`12` |
| `${time.day}` | Jour du mois | 2 chiffres, `01`–`31` |
| `${time.hour}` | Heure | 2 chiffres, `00`–`23` |
| `${time.minute}` | Minute | 2 chiffres, `00`–`59` |
| `${time.second}` | Seconde | 2 chiffres, `00`–`59` |
| `${time.millisec}` | Millisecondes | 3 chiffres, `000`–`999` |
| `${time.hex}` | Unix Epoch hexadécimal (4 octets) | **Réservé à `hexCorrelatorData`** — ne pas utiliser dans une chaîne ou un JSON quelconque |

#### Exemples

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

// Body POST avec horodatage complet
"bodyParameters": { "ts": "${time}", "user": "${localUser.loginEmail}" }

// Corrélateur OXE avec timestamp hex (uniquement on-makecall-insert-correlator)
"hexCorrelatorData": "O-${localUser.nickname}-${time.hex}"
```

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

Pour distribuer un manifest avec des fichiers locaux (icônes, contenus statiques) :

1. Référencer chaque ressource par `${custo.path}\\nom-du-fichier.ext`
2. Empaqueter le tout dans un **ZIP** :
   - `custo-manifest.json` à la racine
   - les fichiers ressources à côté

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

Le ZIP doit contenir : `custo-manifest.json`, `basketball.png`, `FileDisplay.txt`.

#### Identification du manifest dans le ZIP

Rainbow identifie le fichier manifest selon l'ordre de priorité suivant :

1. **`custo-manifest.json`** — fichier portant exactement ce nom, à la racine du ZIP
2. **Sinon**, le **premier fichier `.json`** trouvé dans le ZIP qui contient `"jsonType": "Rainbow-custo-manifest"`

Si aucun fichier ne correspond à ces deux critères, l'import du ZIP échoue.

> 💡 Pour garantir une détection sans ambiguïté, nommez votre manifest `custo-manifest.json` et placez-le à la racine du ZIP.

---


---

### 7.7 Variable `${response}` — réponse REST *(BETA S183)*

`${response}` représente le **corps JSON retourné par l'appel REST de la même action**. Elle est utilisable dans `redirectUrl` des events d'appel (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) et des 8 EP boutons — voir §10.1 et §10.2 — et dans **`markdownTemplate`** des EP qui affichent du Markdown — voir §8.4. Elle n'est disponible dans aucun autre champ.

```
${response.contactId}               champ de la réponse
${response.data.contact.id}         chemin imbriqué
${response[0].contactId}            index de tableau
```

**Résolution tolérante.** Certaines API REST retournent un objet seul quand il y a un résultat et un tableau quand il y en a plusieurs. Les deux syntaxes fonctionnent donc quelle que soit la forme de la réponse :

| Syntaxe | La réponse est un objet | La réponse est un tableau |
|---|---|---|
| `${response.contactId}` | le champ de l'objet | le champ du **premier élément** |
| `${response[0].contactId}` | l'objet lui-même est pris comme premier élément | le champ du premier élément |

- Tout autre index sur un objet (`${response[1]...}`) est un champ manquant.
- Un tableau vide (`[]`) est un champ manquant.

Quand le champ ciblé est manquant, rien ne se passe (voir §10.1, *Gestion des échecs*).

---

## 8. Affichage au format texte / Markdown

Lorsqu'une extension peut afficher une réponse et que `responseType: "markdown"` (ou est absent — c'est la valeur par défaut), le contenu de la réponse est rendu **comme du texte enrichi en Markdown** dans un popup Rainbow. Les **emojis** sont également supportés (Unicode natif, à copier-coller directement — les shortcodes type `:smile:` ne sont **pas** interprétés, ils s'affichent tels quels).

### 8.1 Syntaxe Markdown courante

Rainbow supporte un sous-ensemble Markdown standard. Les éléments les plus utiles dans un popup d'extension :

| Syntaxe | Effet |
|---|---|
| `**gras**` | **gras** |
| `*italique*` | *italique* |
| `# Titre 1`, `## Titre 2`, `### Titre 3` | titres hiérarchiques |
| `- élément` ou `* élément` | liste à puces |
| `1. élément` | liste numérotée |
| `[libellé](https://url.com)` | lien cliquable |
| ```` ```\nbloc de code\n``` ```` | bloc de code |
| `---` | ligne horizontale |
| `\| col 1 \| col 2 \|` | tableau (avec ligne de séparation `\|---\|---\|`) |
| 🎉 ✅ 📞 | emojis Unicode (copier-coller direct) |

#### Exemple — Markdown enrichi en sortie REST

Une API renvoie :

```markdown
## Contact identifié 📇

**Marie Curie** — *Sorbonne Université*

| Champ | Valeur |
|---|---|
| Téléphone | +33 1 42 34 56 78 |
| Email | [marie.curie@example.com](mailto:marie.curie@example.com) |
| Statut | ✅ Client actif |

> 💡 Cliquer sur l'email ouvre votre client de messagerie.
```

Le popup Rainbow affichera le titre, le tableau formaté, les liens cliquables et les emojis.

#### Exemple — Démo de la syntaxe supportée (fichier 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"
      }
    ]
  }
}
```

Contenu du fichier `SupportedMarkdown.txt` (livré dans le ZIP à côté du manifest) :

```markdown
<!-- Comment: Supported markdown -->
---
**bold text**
*italic text*
# Titre 1,
## Titre 2,
### Titre 3
* élément 1️⃣
* élément 2️⃣
* élément 3️⃣
1. élément 1️⃣
2. élément 2️⃣
3. élément 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)*|
___
```

Rendu dans Rainbow :

![Rendu Markdown dans Rainbow](images/markdown.png)

### 8.2 Markdown extrait d'une réponse JSON

Si `responseType: "json"` **et** que `displayJsonField` est défini, Rainbow interprète la réponse comme du JSON, en extrait la valeur du champ pointé par `displayJsonField`, et l'affiche comme du texte/Markdown.

C'est utile quand le serveur renvoie déjà un JSON structuré (par exemple un payload d'API métier) qui contient le markdown à afficher dans un de ses champs.

#### Exemple — Markdown dans un champ 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"
}]
```

Réponse de l'API :

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

Rainbow extrait `display`, substitue les variables `${contact.*}`, et affiche le résultat dans le popup.

### 8.3 Affichage via sortie standard (Desktop only)

Quand un EP supporte le retour d'affichage en Markdown, on peut capturer la **sortie standard** d'un script ou d'un programme :

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

Le contenu écrit sur `stdout` par le script est affiché dans un popup Rainbow. Idéal pour intégration simple ou prototypage sans infrastructure REST.

> ⚠ **Rainbow Desktop uniquement.** Côté Web, le script ne peut pas être exécuté localement ; ce mode n'est donc pas disponible.

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

> ⚠ **BETA (S183)** — cette fonctionnalité est en beta et peut évoluer avant la disponibilité générale.

Jusqu'à présent, le résultat d'un appel REST pouvait être affiché comme **un champ de la réponse JSON** (`displayJsonField`, §8.2) ou mis en forme avec une **Adaptive Card** (§9). `markdownTemplate` ajoute une troisième option : un **template Markdown déclaré dans le manifest**, renseigné avec les variables Rainbow et avec les champs de la réponse JSON de l'appel REST.

**Règles**
- `command` est de type **`rest`** et la réponse de type **JSON** (`responseType: "json"`) — les deux sont **obligatoires** avec `markdownTemplate`.
- `markdownTemplate` (string, Markdown) est à la racine de l'action. Son texte est affiché après une **substitution de variables** : les **variables Rainbow** habituelles de l'EP (§7) et la variable **`${response}`** (§7.7), c'est-à-dire le corps JSON retourné par l'appel REST de la même action (`${response.contactId}`, `${response.data.contact.id}`, `${response[0].contactId}` ; résolution souple objet/tableau, §7.7).
- Les valeurs substituées sont insérées **telles quelles** : pas d'encodage URL et pas d'échappement des caractères Markdown.
- **Ordre d'exécution** — lorsque plusieurs de ces éléments sont définis sur la même action, Rainbow les traite dans cet ordre, et le premier qui s'applique est exécuté : `redirectUrl`, puis `markdownTemplate`, puis `displayJsonField`, puis Adaptive Card. En particulier, si un `redirectUrl` existe et qu'une réponse REST valide est retournée, la redirection est appliquée et `markdownTemplate` n'est **pas** affiché ; s'il n'y a **pas de `redirectUrl`**, ou s'il est **vide parce que la réponse REST est vide**, le contenu de `markdownTemplate` est affiché.
- **Gestion des échecs** — si l'appel REST échoue (timeout, erreur HTTP), si la réponse n'est pas du JSON valide, ou si un champ référencé est absent : **rien n'est affiché**.
- Un client qui ne connaît pas `markdownTemplate` ignore le champ (pas d'erreur).

**Disponible sur** tous les points d'extension qui affichent du Markdown :
- Affichage : `on-incoming-pbx-call-display-actions`, `on-contact-card-display-actions`, `on-main-widget-display-actions`, `on-main-display-actions`, `on-conversation-tab-actions` ;
- Boutons affichant un résultat : `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`.

Les events d'appel n'affichent rien et ne sont pas concernés.

**Exemple — fiche construite à partir de la réponse**

```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}"
}]
```

Avec une réponse `{"firstName":"Jane","lastName":"Doe","company":"ACME"}`, la pop-up affiche le titre *Jane Doe* suivi de la société et du numéro de téléphone.

---

## 9. Adaptive Cards

**Adaptive Card** est un standard ouvert défini par **Microsoft** pour représenter un contenu enrichi (texte, listes, formulaires, boutons, images) dans un format JSON portable, rendu de manière cohérente par chaque application qui l'intègre.

📖 [Microsoft Adaptive Card reference](https://adaptivecards.io/explorer/) — documentation officielle et bibliothèque d'exemples.

Le modèle Adaptive Card sépare deux choses :
- un **template** (mise en forme) décrit en JSON — structure visuelle avec variables `${...}` ;
- des **données dynamiques** également en JSON — qui peuplent les variables du template.

Rainbow reprend cette séparation et calcule le rendu dans le client (Desktop ou Web).
- Le **template** peut être prédéfini dans le manifest (`adaptiveCardTemplate`) ou bien inclus dans la réponse JSON d'un appel REST (extraction via `adaptiveCardTemplateJsonField`).
- Les **données** peuvent également être dans le manifest, dans un fichier séparé (utile pour tester), mais proviennent le plus souvent d'une réponse à un appel REST métier.

Quatre combinaisons sont supportées sur Rainbow Desktop **et** Web :

| Mode | Template | Content |
|---|---|---|
| **Tout dans le manifest** | inline | inline |
| **Template dans manifest** | inline | dans un fichier |
| **Template dans manifest + REST data** | inline | renvoyé par un appel REST |
| **Tout en REST** | renvoyé par REST | renvoyé par REST |

### Champs concernés (à la racine de l'action)

| Champ | Rôle |
|---|---|
| `adaptiveCardTemplate` | Template JSON inline dans le manifest |
| `adaptiveCardTemplateJsonField` | Nom du champ de la réponse REST contenant le template |
| `adaptiveCardContentJsonField` | Nom du champ de la réponse REST contenant les données. **Si vide ou absent, les variables sont recherchées directement à la racine de l'objet JSON de la réponse.** |
| `adaptiveCardSubmitUrl` | URL REST appelée en POST lors d'un `Action.Submit` dans la carte |

### Actions supportées dans une Adaptive Card

- **`Action.OpenUrl`** — ouvre une URL dans le navigateur.
- **`Action.Submit`** — Rainbow transforme cette action en **POST** vers l'URL définie par `adaptiveCardSubmitUrl`. Le corps de la requête contient l'objet `data` de l'action (plus les valeurs des `Input.*` éventuels).
  - Si la réponse REST renvoie des **données rafraîchies** (même structure que la réponse initiale, ou un nouveau template), Rainbow **rafraîchit la carte** automatiquement avec les nouvelles valeurs.

### Tags Adaptive Card supportés (indicatif)

Tableau de référence du support des principaux éléments Adaptive Card dans Rainbow. Le statut peut évoluer entre versions — pour vérifier finement avec votre version Rainbow courante, utilisez l'outil de test **Adaptive Card** intégré à RainbowCustoServer.

| Élément AC | Support | Notes |
|---|:---:|---|
| `TextBlock` | ✅ | élément texte de base, riche en options de style |
| `Image` | ✅ | URL http(s), data URI |
| `ColumnSet` / `Column` | ✅ | mise en page en colonnes |
| `Container` | ✅ | regroupement, styles d'arrière-plan |
| `FactSet` | ✅ | tableau clé / valeur |
| `ImageSet` | ✅ | galerie d'images |
| `ActionSet` | ✅ | groupe de boutons inline |
| `RichTextBlock` / `TextRun` | ✅ | texte multi-styles dans une même ligne |
| `Table` | ✅ | tableau structuré (AC 1.5+) |
| `Input.Text` | ✅ | saisie texte |
| `Input.Number` | ✅ | saisie numérique |
| `Input.Date` | ✅ | sélecteur de date |
| `Input.Time` | ✅ | sélecteur d'heure |
| `Input.Toggle` | ✅ | case à cocher |
| `Input.ChoiceSet` | ✅ | liste déroulante / radio / multi-select |
| `Action.OpenUrl` | ✅ | ouvre l'URL dans le navigateur |
| `Action.Submit` | ✅ | POST vers `adaptiveCardSubmitUrl` |
| `Action.ToggleVisibility` | ✅ | masquer / afficher dynamiquement des éléments |
| `Action.ShowCard` | ✅ | sous-carte inline |
| `Media` | ⚠️ | rendu vidéo / audio limité |
| `Carousel` | ⚠️ | navigation entre cartes — limites de rendu (AC 1.4+) |
| `Badge` | ❌ | AC 1.6+ — non supporté |
| `CodeBlock` | ❌ | AC 1.6+ — non supporté |
| `Icon` | ❌ | AC 1.6+ — non supporté |
| `CompoundButton` | ❌ | AC 1.6+ — non supporté |
| `ProgressRing` | ❌ | AC 1.6+ — non supporté |
| `ProgressBar` | ❌ | AC 1.6+ — non supporté |
| `Action.Popover` | ❌ | AC 1.6+ — non supporté |
| `Input.Rating` | ❌ | AC 1.6+ — non supporté |
| `Chart.*` (Donut, Line, Bar…) | ❌ | extensions Chart non supportées |

Légende : ✅ supporté · ⚠️ supporté avec limites · ❌ non supporté

### Exemple : widget avec template et data depuis 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"
}]
```

La réponse REST attendue :
```json
{
  "card": { "type": "AdaptiveCard", "body": [ … ] },
  "data": { "lumiere": { "status": "on" }, … }
}
```

Rendu dans Rainbow :

![Rendu Adaptive Card dans Rainbow](images/adaptive.png)

---

## 10. Référence par type d'extension

Cette section regroupe les points d'extension par famille fonctionnelle. Quatre familles : **événements de téléphonie**, **boutons**, **affichage**, **application**.

---

### 10.1 Événements de téléphonie

![Événements téléphoniques Rainbow](images/telephony-events.svg)

**Principe** : aucune UI propre. Ces extensions déclenchent automatiquement une action (appel REST, exécution locale, ouverture URL) lorsque survient un événement téléphonique. Cas d'usage typiques : journalisation d'appels dans un ERP, déclenchement d'un workflow CRM, mise à jour de présence dans un système métier.

**Points d'extension** :

| Clé | Déclencheur |
|---|---|
| `on-outgoing-pbx-call-actions` | Un appel sortant est initié |
| `on-incoming-pbx-call-actions` | Un appel entrant arrive |
| `on-answering-incoming-pbx-call-actions` | Un appel entrant est décroché |
| `on-releasing-incoming-pbx-call-actions` | Un appel entrant est terminé |
| `on-makecall-insert-correlator` | À chaque makecall — insère un corrélateur (OXE only) |

**Pré-requis licence** : Essentials (les events sont la seule famille supportée sur cette licence).

#### Champs (action standard)

| Champ | Position | Type | Obligatoire | Valeurs / contraintes |
|---|---|---|---|---|
| `command` | racine | object | **OUI** | Objet command |
| `command.url` | command | string | **OUI** | URL HTTP(S) ou `{{server}}/…` |
| `command.params` | command | string | non | Paramètres URL (concaténés après `?`). Variables autorisées. |
| `command.commandType` | command | string | non | `"rest"` (défaut et seule valeur supportée pour les events) |
| `command.method` | command | string | non | `"GET"` (défaut) ou `"POST"` |
| `command.header` | command | array | non | Tableau de strings `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **OUI si `method: "POST"`** | JSON envoyé en body. Variables autorisées. |
| `NoShortNumber` | racine | boolean | non | Si `true`, l'event n'est pas levé quand l'appelant est un numéro court |
| `RaiseChangeCall` | racine | `true` \| `false` \| `"Only"` | non | (incoming events uniquement) — gère la propagation sur transfert distant (§6.1) |
| `redirectUrl` *(BETA S183)* | racine | string | non | Template d'URL ouverte dans une nouvelle fenêtre du navigateur après l'appel REST (voir ci-dessous). Nécessite `responseType: "json"`. |
| `responseType` | racine | `"json"` | **OUI si `redirectUrl`** | Obligatoire avec `redirectUrl`. Sinon pas de `responseType` sur les events. |

**À noter** :
- **Pas de `name`, `icon`** — un event est silencieux côté UI Rainbow
- **Pas de `responseType`**, sauf `"json"`, **obligatoire** avec `redirectUrl` *(BETA S183)* — voir ci-dessous
- `commandType: "file"` non supporté

**Variables Rainbow autorisées par 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` | ✓ | — | `phoneNumber` seul | — | — | ✓ |

*¹ — `${contact.*}` n'est résolu que **si un contact a été identifié** (numéro reconnu dans Rainbow). Sinon, les variables `${contact.*}` sont vides à la substitution.*

*Dans `redirectUrl` uniquement (BETA S183), `${response...}` (corps JSON de l'appel REST de la même action) est également disponible — voir §7.7.*

#### Redirection après un appel REST — `redirectUrl` *(BETA S183)*

**Principe** : enchaîner un appel REST avec l'ouverture d'une URL construite à partir de sa réponse JSON — typiquement un **screen-pop CTI** : 1) une API REST est interrogée avec le numéro de l'appelant pour obtenir un identifiant (ex. `contactId`), 2) une page de « screen-pop » décorée de cet identifiant est ouverte. Toute la chaîne est déclarée dans le manifest, sans backend intermédiaire.

Disponible sur les quatre events d'appel (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) **et sur les points d'extension boutons** (§10.2).

**Règles** :
- **`redirectUrl`** (string, template) : une redirection est appliquée lorsqu'il est présent. `responseType: "json"` est **obligatoire** avec lui (la réponse REST est lue comme JSON pour alimenter `${response}`) ; ce n'est pas une nouvelle valeur de `responseType`.
- Le seul travail de Rainbow est une **substitution de variables** dans `redirectUrl`, que la variable soit une variable Rainbow (`${caller.phoneNumber}`, …) ou une variable `${response...}` (§7.7). Deux usages :
  - **la réponse fournit une partie de la destination** : `"redirectUrl": "http://server/screenPop?id=${response.contactId}"` ;
  - **la réponse fournit toute la destination** : `"redirectUrl": "${response.url}"` — le champ `url` de la réponse est la page à ouvrir.
- La valeur substituée est **automatiquement encodée URL** (même mécanisme que les autres variables du manifest).
- L'URL s'ouvre **toujours** dans une **nouvelle fenêtre du navigateur** (popup).
- **Gestion des échecs** — si l'appel REST échoue (timeout, erreur HTTP), si le champ ciblé est absent de la réponse, ou si la réponse n'est pas du JSON valide : **rien ne se passe** (pas de popup, pas d'erreur affichée à l'utilisateur) ; seule une trace de log côté client est écrite pour le diagnostic.
- Un client qui ne connaît pas `redirectUrl` ignore le champ (pas d'erreur).

> ⚠ **BETA (S183)** — cette fonctionnalité est en beta et peut évoluer avant la disponibilité générale.

**Exemple 1 — la réponse fournit une partie de la destination**

```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}"
}]
```

**Exemple 2 — la réponse fournit toute la destination (réponse `{"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}"
}]
```

**Exemple 3 — variable Rainbow et variable de réponse combinées ; l'API répond un objet *ou* un tableau (résolution tolérante, §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}"
}]
```

#### Résolution caller-ID

La **résolution de l'identité de l'appelant** (nom/prénom/société) et le **lien cliquable** vers sa fiche CRM ne se font **pas** via les events de téléphonie (qui sont silencieux côté UI), mais via l'affichage **`on-incoming-pbx-call-display-actions`** — voir **§10.3.1**.

#### Schéma particulier — `on-makecall-insert-correlator` (OXE)

Cet EP ne suit pas le schéma `command` standard. Il insère un corrélateur (ASCII ou hex) sur tous les makecall :

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

Limité à 32 caractères. Un seul type (`correlatorData` **ou** `hexCorrelatorData`) à la fois.

#### Exemple 1 — journalisation d'appel entrant (POST avec 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 **résolution caller-ID** (nom/prénom/société + lien CRM) n'est **pas** un event : elle se déclare via `on-incoming-pbx-call-display-actions` — voir **§10.3.1**.

#### Exemple 2 — Popup application web, filtrage des numéros courts

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

L'event ne sera pas levé pour les appels internes (extensions courtes).

#### Exemple 3 — exécution d'un script local au décrochage

> **⚠ Rainbow Desktop uniquement** — l'exécution d'un script ou d'une application locale (`.exe`, `.bat`, etc.) n'est pas supportée par Rainbow Web. Côté Web, cet event sera ignoré.

```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}"
      }
    }]
  }
}
```

Le script `log-call.bat` est exécuté localement au moment où l'utilisateur décroche l'appel. Les variables Rainbow sont substituées dans `params` avant le passage en ligne de commande.

#### Exemple 4 — corrélateur OXE sur makecall

> **⚠ OXE uniquement** — cet EP n'est exploitable que sur un PBX Alcatel-Lucent OXE.

Pour ajouter un corrélateur à chaque appel sortant initié par makecall :

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

**Règles** :
- Soit `correlatorData` (ASCII) **OU** `hexCorrelatorData` (hexadécimal) — **un seul type autorisé**
- Limité à **32 caractères**
- Variables autorisées : `${localUser.*}`, `${called.phoneNumber}`, `${time.*}`
- `${time.hex}` est un format spécial 4 bytes — uniquement avec `hexCorrelatorData`

---

### 10.2 Boutons

![Boutons dans l'UI Rainbow](images/buttons.png)

**Principe** : un bouton-icône est inséré à un emplacement précis de l'UI Rainbow. Au clic, une action est exécutée et, optionnellement, son résultat est affiché dans un popup (Markdown ou Adaptive Card). 3 boutons maximum par EP.

**Points d'extension** :

| Clé | Emplacement du bouton |
|---|---|
| `on-incoming-pbx-call-button-actions` | Pop-up d'appel entrant |
| `on-call-log-list-actions` | Chaque ligne du journal d'appels |
| `on-contact-list-actions` | Chaque ligne de la liste des contacts |
| `on-contact-detail-actions` | Panneau de détail d'un contact |
| `on-communication-card-actions` | Barre du gestionnaire d'appels (menu) |
| `on-bubble-actions` | Menu propriété d'une bulle |
| `on-bubble-conference-actions` | Menu d'une conférence téléphonique |
| `on-user-menu-actions` | Menu utilisateur (Desktop / Web — pas Teams) |

**Pré-requis licence** : Business minimum.

#### Champs (tous boutons)

| Champ | Position | Type | Obligatoire | Valeurs / contraintes |
|---|---|---|---|---|
| `name` | racine | string | voir spécificités | Texte / tooltip du bouton ou label de menu |
| `icon` ou `iconId` | racine | string | voir spécificités | URL `https://…`, `${custo.path}\fichier.png` ou nom de sprite intégré |
| `tooltip` | racine | string | non | Tooltip alternatif (ignoré sur certains EPs) |
| `command` | racine | object | **OUI** | Objet command |
| `command.url` | command | string | **OUI** | URL HTTP(S), `{{server}}/…` ou chemin de fichier |
| `command.params` | command | string | non | Paramètres URL. Variables autorisées. |
| `command.commandType` | command | string | non | `"rest"` (défaut) ou `"file"`. En Web, `"file"` nécessite le fichier dans le ZIP. |
| `command.method` | command | string | non | `"GET"` (défaut) ou `"POST"` |
| `command.header` | command | array | non | Tableau `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **OUI si POST** | JSON envoyé en body |
| `responseType` | racine | string | voir spécificités | `"markdown"`, `"json"` ou `"adaptiveCard"`. Si présent → popup. Sinon → action exécutée sans retour affiché. |
| `displayJsonField` | racine | string | non | Si `responseType: "json"`, nom du champ JSON contenant le markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | racine | — | selon mode | Si `responseType: "adaptiveCard"` — voir §8 |
| `AnswerOnClick` | racine | boolean | non | (uniquement `on-incoming-pbx-call-button-actions`) — si `true`, décroche aussi l'appel |
| `alsoForTeams` | racine | boolean | non | (uniquement `on-call-log-list-actions`) — affiche aussi dans l'add-in Teams |
| `redirectUrl` *(BETA S183)* | racine | string | non | Template d'URL ouverte dans une nouvelle fenêtre du navigateur après l'appel REST (voir ci-dessous). Nécessite `responseType: "json"`. |
| `markdownTemplate` *(BETA S183)* | racine | string | non | Template Markdown affiché après substitution des variables Rainbow et de `${response...}`. Nécessite `commandType: "rest"` et `responseType: "json"` — voir §8.4. |

#### Spécificités par EP

| EP | `name` | `icon` | `responseType` | Variables autorisées |
|---|---|---|---|---|
| `on-incoming-pbx-call-button-actions` | "Button text" | non utilisé | optionnel | localUser, caller, called, call, contact |
| `on-call-log-list-actions` | tooltip | **OUI** | optionnel | localUser, contact |
| `on-contact-list-actions` | tooltip | **OUI** | optionnel | localUser, contact |
| `on-contact-detail-actions` | tooltip | **OUI** | optionnel | localUser, contact |
| `on-communication-card-actions` | "menu text" | **OUI** (menu) | optionnel | localUser, caller, called, call, contact |
| `on-bubble-actions` | "menu text" | **OUI** (menu) | optionnel | localUser, bubble |
| `on-bubble-conference-actions` | "menu text" | **OUI** (menu) | optionnel | localUser, bubble |
| `on-user-menu-actions` | "menu item title" | **OUI** (menu) | optionnel | localUser |

> **Note (confirmé en direct, 2026-10-01)** : quel que soit son rôle normal
> indiqué ci-dessus (tooltip, libellé de menu…), `name` est **également** repris
> comme titre du popup lorsque `responseType` déclenche l'affichage d'un
> résultat — y compris sur les EP où ce tableau indique "tooltip" plutôt qu'un
> titre de bouton visible par défaut (`on-call-log-list-actions`,
> `on-contact-list-actions`, `on-contact-detail-actions`). Utile pour
> distinguer plusieurs boutons différents qui partagent le même mécanisme de
> popup générique.

#### Redirection après un appel REST — `redirectUrl` *(BETA S183)*

Tous les EP boutons acceptent `redirectUrl` : au clic, l'appel REST est exécuté et l'URL — construite à partir de la réponse JSON — est ouverte dans une **nouvelle fenêtre du navigateur**. Les règles sont les mêmes que pour les events d'appel (voir **§10.1**) : `redirectUrl` nécessite `responseType: "json"` (obligatoire), les variables (variables Rainbow de l'EP et `${response...}`, §7.7) sont substituées et encodées URL, et rien ne se passe si l'appel REST échoue, si le champ est absent ou si la réponse n'est pas du JSON.

Spécificités pour les boutons :
- Une redirection **remplace l'affichage** : `responseType` doit être `"json"` (obligatoire). Combiner `redirectUrl` avec `"markdown"` ou `"adaptiveCard"`, ou omettre `responseType`, est **invalide** (signalé comme une erreur par le Rainbow Validator).
- `command.commandType` doit être `"rest"` (défaut) — la réponse n'existe que pour un appel REST, pas pour `"file"`.

> ⚠ **BETA (S183)** — cette fonctionnalité est en beta et peut évoluer avant la disponibilité générale.

**Exemple — bouton de la liste de contacts qui ouvre la fiche CRM résolue par une recherche 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}"
}]
```

#### Exemple 1 — bouton dans la liste de contacts qui ouvre un CRM externe

```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}"
      }
    }]
  }
}
```

Pas de `responseType` → l'URL est ouverte dans un nouvel onglet du navigateur, sans popup dans Rainbow.

#### Exemple 2 — bouton sur appel entrant qui crée un ticket et décroche

```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}"
    }
  }
}]
```

Le clic crée le ticket **et** décroche l'appel en une opération (`AnswerOnClick: true`).

#### Exemple 3 — menu Adaptive Card dans le menu bulle

```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}` nécessite `commandType: "rest"` (cf §7).

---

### 10.3 Affichage (Display)

![Affichage automatique d'informations dans Rainbow](images/displays.png)

**Principe** : insère automatiquement du contenu (Markdown ou Adaptive Card) à un emplacement précis de l'UI — sans interaction utilisateur. Le contenu est récupéré au moment où l'emplacement devient visible.

**Points d'extension** :

| Clé | Emplacement de l'affichage |
|---|---|
| `on-incoming-pbx-call-display-actions` | Dans la pop-up d'appel entrant |
| `on-contact-card-display-actions` | Dans le panneau de détail du contact |
| `on-main-widget-display-actions` | Widget dans le panneau principal Rainbow |
| `on-main-display-actions` | Message dans la Webapp Teams |
| `on-conversation-tab-actions` | Onglet personnalisé dans une conversation (P2P ou conférence) — voir ci-dessous |

**Pré-requis licence** : Business minimum.

#### Champs (tous displays)

| Champ | Position | Type | Obligatoire | Valeurs / contraintes |
|---|---|---|---|---|
| `name` | racine | string | voir spécificités | Titre (widget uniquement) |
| `command` | racine | object | **OUI** | Objet command |
| `command.url` | command | string | **OUI** | URL HTTP(S), `{{server}}/…` ou fichier |
| `command.params` | command | string | non | Paramètres URL. Variables autorisées. |
| `command.commandType` | command | string | non | `"rest"` (défaut) ou `"file"`. En Web, `"file"` → fichier dans le ZIP. |
| `command.method` | command | string | non | `"GET"` (défaut) ou `"POST"` |
| `command.header` | command | array | non | Tableau `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **OUI si POST** | JSON body |
| `responseType` | racine | string | **OUI** | `"markdown"`, `"json"` ou `"adaptiveCard"` ¹ — toujours requis pour les displays |
| `displayJsonField` | racine | string | non | Si `responseType: "json"`, champ contenant le markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | racine | — | selon mode | Si `responseType: "adaptiveCard"` — voir §8 |
| `urlConfig` | racine | string | non | (uniquement `on-main-widget-display-actions`) — URL de config du widget |
| `alsoForTeams` | racine | boolean | non | (uniquement `on-main-display-actions`) — affiche dans Teams web add-in |
| `markdownTemplate` *(BETA S183)* | racine | string | non | Template Markdown affiché après substitution des variables Rainbow et de `${response...}`. Nécessite `commandType: "rest"` et `responseType: "json"` — voir §8.4. |

*¹ `adaptiveCard` n'est **pas** supporté par `on-incoming-pbx-call-display-actions` (pop-up d'appel entrant) — voir §10.3.1.*

#### Spécificités par EP

| EP | `name` | Variables autorisées |
|---|---|---|
| `on-incoming-pbx-call-display-actions` | non utilisé | localUser, caller, called, call, contact |
| `on-contact-card-display-actions` | non utilisé | localUser, contact |
| `on-main-widget-display-actions` | "widget title" | localUser |
| `on-main-display-actions` | non utilisé | localUser |
| `on-conversation-tab-actions` | "nom d'onglet" | localUser, contact, bubble |

#### 10.3.1 `on-incoming-pbx-call-display-actions` (détail)

**Rôle** : afficher automatiquement des informations dans la **pop-up d'appel entrant**, sans interaction de l'utilisateur. Le contenu est récupéré au moment où la pop-up s'affiche, à partir d'une source déclarée dans `command`.

**Sources de contenu possibles** :

| Source | `command` | Effet |
|---|---|---|
| **Fichier** | `commandType: "file"`, `url` = chemin fichier | lit un fichier et affiche son contenu |
| **Script** | `commandType: "file"`, `url` = exécutable/script | exécute le script et affiche sa sortie |
| **Page Web** | `commandType: "rest"`, `url` = http(s) | ouvre l'URL et affiche son contenu |
| **API REST** | `commandType: "rest"`, `method` GET/POST | invoque une API REST et exploite la réponse |

**`responseType`** : `"markdown"` (défaut) ou `"json"`.

> ⚠️ **Adaptive Card n'est PAS utilisable** pour ce point d'extension.

**Exploitation d'une réponse JSON** (`responseType: "json"`) — plusieurs champs de la réponse peuvent être extraits :

| Champ manifest | Rôle |
|---|---|
| `displayJsonField` | nom du champ JSON **dont la valeur est affichée** (texte / Markdown) dans la pop-up |
| `firstNameJsonField` | **surcharge/définit le prénom** de l'appelant affiché |
| `lastNameJsonField` | **surcharge/définit le nom** de l'appelant |
| `companyJsonField` | **surcharge/définit la société** de l'appelant |
| `linkJsonField` | nom du champ JSON dont la valeur est ajoutée comme **lien cliquable** dans la pop-up (libellé = `name` de l'action si présent, sinon « Link ») — typiquement pour ouvrir la fiche de l'appelant dans l'application métier/CRM |

La pop-up peut ainsi, en un seul appel, **enrichir l'identité de l'appelant** (nom/prénom/société résolus depuis le CRM), **afficher un contenu** et proposer un **lien** vers sa fiche.

**Exemple — résolution caller-ID + contenu + lien depuis une 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"
}]
```

Réponse REST attendue (exemple) :

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

Rainbow affiche la valeur de `display`, remplace le nom/prénom/société de l'appelant par ceux résolus, et ajoute la valeur de `crmUrl` comme lien cliquable (libellé = `name` de l'action, sinon « Link »).

> **⚠ Persistance limitée** — l'identité résolue (nom/prénom/société) **ne persiste pas au-delà de la session Rainbow courante** : après fermeture de session, le call-log n'affiche plus que le numéro brut. Pour une identification persistante, ajouter le contact au carnet Rainbow.

**Exemple concret — Markdown stocké dans un champ texte du CRM**

Astuce : stocker directement du **Markdown** dans un champ texte du CRM (ici `notes`). Rainbow l'affiche tel quel dans la pop-up — gras, emojis et **lien cliquable** compris. Les champs sont ici sous un objet `contact` (chemins `contact.*`).

Extrait de manifest :

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

Réponse REST (le champ `notes` contient du 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"
  }
}
```

Rendu dans la pop-up d'appel entrant :

![Affichage Markdown dans la pop-up d'appel entrant](images/incomingCallDisplaySample1.png)

#### Exemple 1 — fiche caller-ID en Markdown dans la pop-up d'appel entrant

```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"
    }]
  }
}
```

#### Exemple 2 — widget Adaptive Card refreshé à chaque ouverture

```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` permet aux boutons `Action.Submit` de la carte de POSTer leur `data` vers cette URL.

#### Exemple 3 — affichage déclaré dans Teams aussi

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

#### Onglet de conversation — `on-conversation-tab-actions`

> ℹ **Nouveauté S179.**

**Principe** : ajoute un **onglet personnalisé** dans la colonne de détail d'une conversation, pour une conversation P2P et/ou une conférence (bulle). L'item d'onglet est défini par `name`, `icon` et `tooltip`. À la sélection, l'action s'exécute — un appel REST (`rest`), un script local/Exec (`file`) ou une page web (`app`) — et le contenu retourné s'affiche dans l'onglet (`markdown` ou `adaptiveCard`). Pendant une conférence, l'onglet est proposé dans la liste des **outils de réunion**.

**Licence** : tous les plans de service sauf Essential.

Contrairement aux autres displays, `responseType` est **optionnel** ici : un onglet qui se contente d'ouvrir une page web ne renvoie aucun contenu à afficher.

**`scope`** (array, optionnel) — les contextes de conversation où l'onglet apparaît :

| Valeur | Contexte |
|---|---|
| `"one_to_one"` | Conversations P2P |
| `"bubble"` | Conférences (bulles) |

Si `scope` est absent, l'onglet est proposé dans tous les contextes.

**Variables autorisées** : `${localUser.*}`, toutes les `${contact.*}` et toutes les `${bubble.*}` (voir §7.2). `${bubble.members}` n'est utilisable qu'avec un appel 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 Application (Frame display)

![Application WEB tierce dans une frame Rainbow](images/applications.png)

**Principe** : embarque une **application WEB tierce** dans une frame de l'UI Rainbow. Pas d'objet `command` REST — c'est simplement une URL chargée comme un iframe. Avec `popout: true`, l'application s'ouvre dans une fenêtre du navigateur (au lieu d'être embarquée).

**Point d'extension** :

| Clé | Emplacement |
|---|---|
| `on-main-window-actions` | Frame dans la fenêtre principale Rainbow |

**Pré-requis licence** : Business minimum.

#### Champs

| Champ | Position | Type | Obligatoire | Valeurs / contraintes |
|---|---|---|---|---|
| `name` | racine | string | **OUI** | "Frame name" — nom affiché de l'application dans la barre Rainbow |
| `icon` ou `iconId` | racine | string | **OUI** (inutile pour un item ciblant uniquement Mobile) | URL `https://…`, `${custo.path}\fichier.png` ou sprite |
| `tooltip` | racine | string | non | Info-bulle |
| `command` | racine | object | **OUI** | Objet command — au minimum `url` |
| `command.url` | command | string | **OUI** | URL HTTP(S) de l'application WEB à embarquer |
| `command.params` | command | string | non | Paramètres URL. Variables autorisées. |
| `command.commandType` | command | string | non | Vide par défaut → comportement "Browse URL" (l'URL est simplement chargée) |
| `popout` | racine | boolean | non | `true` → ouvre l'application dans une fenêtre du navigateur au lieu de la frame Rainbow |
| `devicesSupported` *(BETA S183)* | racine | array | non | Clients Rainbow ciblés par l'item (`"web"`, `"desktop"`, `"mobile"`) — voir §6.2 |

**À noter** :
- **Pas de `method`, `bodyParameters`, `header`, `responseType`** — c'est un chargement d'URL, pas un appel API
- **Pas de variables autres que `localUser.*`** — l'EP est au niveau application Rainbow, pas d'un contact/appel

**Variables Rainbow autorisées** : `${localUser.*}`

#### Mobile *(BETA S183)*

`on-main-window-actions` est le premier point d'extension disponible sur Rainbow Mobile (`devicesSupported` incluant `"mobile"`, §6.2). Sur Mobile, l'application **s'ouvre toujours dans le navigateur/la webview de l'appareil**, quelle que soit la valeur de `popout`, qui n'y est pas lue, et **sans icône** (l'icône n'est pas utilisée sur Mobile). Le manifest doit être déployé via le mécanisme administrateur (cloud).

#### Sécurité

L'URL chargée doit être déclarée comme **trusted domain** dans la console Rainbow (Company → Customization → Custo-manifest domains). Sinon le navigateur refusera de l'embarquer (CSP). Voir §12.

> **⚠ L'application WEB tierce doit accepter d'être présentée dans une frame.**
> Beaucoup de sites refusent par défaut l'embarquement dans un iframe via :
> - l'en-tête HTTP `X-Frame-Options: DENY` ou `SAMEORIGIN`
> - ou une directive CSP `Content-Security-Policy: frame-ancestors 'self'`
>
> Si l'application cible utilise l'une de ces protections, la frame restera **vide** (page blanche) ou affichera un message d'erreur du navigateur, sans message côté Rainbow. Vérifiez ces en-têtes côté serveur de l'application avant de l'embarquer. Si l'application n'est pas modifiable, l'alternative est `popout: true` pour ouvrir l'app dans une fenêtre du navigateur au lieu d'une frame.

#### Exemple 1 — embarquer une application WEB métier

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

L'application apparaît dans Rainbow sous le nom "Mon CRM". Au clic, le dashboard CRM est chargé dans la frame, avec l'email de l'utilisateur en paramètre.

#### Exemple 2 — ouverture dans le navigateur (au lieu de la frame)

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

`popout: true` → l'application s'ouvre dans une fenêtre du navigateur. Utile quand l'application refuse d'être embarquée (CSP frame-ancestors restrictif) ou quand on veut un grand espace de travail.

#### Exemple 3 — application sans authentification utilisateur (statique)

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

## 11. Création & déploiement

Le déploiement d'un manifest peut se faire de deux manières :

- **Localement**, par import du fichier (ou du ZIP) par l'utilisateur final dans le client Rainbow.
- **Automatiquement depuis le cloud**, lorsque l'administrateur a affecté le manifest à l'utilisateur via la console Rainbow. Le client le télécharge alors au démarrage, sans action de l'utilisateur.

Le déploiement local est recommandé pour la **phase de test** ou si **peu d'utilisateurs** sont concernés. L'administrateur peut interdire ce mode au moyen d'un **flag de profil** : dans ce cas, l'option Import/Export disparaît côté utilisateur.

Le **déploiement administrateur est prioritaire** : un manifest affecté par l'admin remplace tout manifest local et l'utilisateur ne peut pas le surcharger.

**Portée** : le déploiement administrateur s'applique à **toutes les instances** de client Rainbow de l'utilisateur (Desktop, Web, sur toutes les machines/sessions). Le déploiement local, en revanche, ne concerne que **la machine ou le navigateur utilisé pour l'import** — il ne suit pas l'utilisateur sur ses autres postes.

### 11.1 Création

Plusieurs façons d'obtenir un fichier manifest de départ :

**Depuis le client Rainbow Desktop (export d'un template)**

Il est possible d'obtenir un fichier template localement en demandant un export **alors qu'aucun manifest n'a encore été importé**. Le client génère alors un fichier d'exemple contenant tous les points d'extension supportés.

1. Dans le client Rainbow Desktop : **Settings → Telephony → Customization → Export**
2. Supprimer les points d'extension non utilisés (garder seulement ceux que l'on veut configurer)
3. Renseigner le contenu de chacun des EPs conservés (`name`, `icon`, `command`, etc.)
4. Importer pour tester en local

**Depuis un outil de génération ou un exemple**

Les outils de génération de manifest (par exemple le **Rainbow Generator** d'ALE) ou les **exemples** fournis dans cette documentation peuvent aussi servir de point de départ — il suffit de copier la structure JSON, l'adapter à son contexte métier, et l'importer.

### 11.2 ZIP avec ressources

Si le manifest référence des fichiers locaux (icônes, textes, scripts), créer un ZIP contenant le manifest **et** les fichiers ressources, puis l'importer dans le client.

**Rappels** (cf. §7.6) :
- Référencer chaque ressource du ZIP par `${custo.path}\\nom-du-fichier.ext` dans le manifest.
- Inclure le champ `"jsonType": "Rainbow-custo-manifest"` à la racine du manifest — c'est lui qui permet à Rainbow d'identifier le fichier manifest dans le ZIP. À défaut, Rainbow cherche un fichier nommé exactement `custo-manifest.json`.

**Compatibilité Web / Desktop** : le ZIP est compatible avec les deux clients Rainbow. Côté Desktop, les ressources sont écrites sur disque ; côté Web, elles sont chargées en mémoire depuis le ZIP téléchargé. Le même ZIP peut donc être déployé indifféremment pour les deux plateformes.

### 11.3 Mass provisioning (par administrateur)

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

1. Importer le manifest dans l'administration Rainbow centrale
2. Allouer un manifest aux utilisateurs :
   - via le web admin (Member → Information → custo-manifest)
   - via CSV
   - via connecteur LDAP : mapper le champ `selectedManifestName` sur l'attribut LDAP correspondant
3. Le client Rainbow télécharge automatiquement le manifest au démarrage :
   - L'option `/Custom` du setup est **ignorée**
   - L'Import/Export dans Settings est **caché** à l'utilisateur

### 11.4 Setup CLI

> **⚠ Procédure obsolète** — privilégier le **déploiement administrateur** (§11.3), qui est prioritaire sur ce mode ancien et offre une gestion centralisée. Ce mode CLI est conservé pour rétro-compatibilité avec d'anciennes intégrations Desktop.

Au lancement du setup Rainbow :
```
RainbowSetup.exe /Custom=C:\path\to\manifest.json
```
À noter : `/Custom` masque aussi l'Import/Export utilisateur.

---

## 12. Sécurité (S170)

### 12.1 Mécanismes web standards

Les extensions sont exécutées par l'application Web Rainbow (même quand embarquée dans le Desktop). Les protections web s'appliquent :

- **CSP** (Content-Security-Policy) — Rainbow ne peut charger une page ou invoquer une API que si le domaine est dans la liste blanche
- **CORS** (Cross-Origin) — le serveur REST doit explicitement accepter Rainbow comme origine
- **LNA** (Local Network Access) — l'accès aux machines/serveurs locaux peut être refusé par le navigateur
- **CSP côté distant** — le serveur peut refuser d'être embarqué dans une frame Rainbow

### 12.2 Trusted domains (nouveau en S170)

#### Ce que ça contrôle

Toute URL référencée dans un manifest (appel REST ou iframe) doit avoir son **origine** déclarée comme trusted dans la console Rainbow. Cela s'applique à :

- `command.url` sur tous les extension points (appels REST, navigation fichier)
- `command.url` sur `on-main-window-actions` (web app embarquée dans la frame)
- `adaptiveCardSubmitUrl`
- `urlConfig` (URL de configuration du widget)

La déclaration est **globale à la company** : elle couvre tous les manifests déployés dans la company et tous les utilisateurs.

> **Exception `popout: true`** — lorsque `on-main-window-actions` utilise `popout: true`, l'URL s'ouvre dans une **fenêtre de navigateur dédiée**, pas dans la frame Rainbow. Le contrôle des trusted domains est **désactivé** dans ce cas : la sécurité native du navigateur s'applique et Rainbow n'impose pas son propre CSP pour cette URL.

> **Flux SSO / OAuth** — si l'application web embarquée déclenche un flux d'authentification (SSO, OAuth, SAML…), le fournisseur d'identité se trouve souvent sur un **domaine différent** de l'application elle-même (ex. `login.microsoftonline.com`, `accounts.google.com`, un IdP interne…). Rainbow va tenter de charger ces URL de redirection dans la même frame, donc **chaque domaine impliqué dans le flux d'authentification doit aussi être déclaré comme trusted** — pas uniquement l'origine de l'application. Ne pas déclarer le domaine IdP résulte en une frame blanche à l'étape de connexion, même si l'URL de l'application est correctement whitelistée.

#### Où configurer

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

Ajouter une entrée par origine. Chaque entrée doit respecter le format :

```
<protocole>://<domaine>[:<port>]
```

| Partie | Règles |
|---|---|
| `protocole` | `https` ou `http` — **obligatoire** |
| `domaine` | Nom d'hôte exact ou wildcard (`*.example.com`) |
| `port` | Optionnel. Omettre pour les ports standard (443 pour https, 80 pour http). |
| `/` final | **Interdit** — l'entrée est rejetée ou ne correspond pas si elle se termine par `/` |

#### Contraintes de protocole (HTTP / HTTPS)

Déclarer une origine comme trusted **ne suffit pas** : le navigateur applique en plus ses propres règles sur le protocole. L'application Web Rainbow est servie en **HTTPS**, donc :

- **`http://` n'est accepté que pour `localhost` / `127.0.0.1` (loopback).** Toute autre origine en HTTP (IP de LAN, nom de machine, domaine public) est **bloquée par le navigateur** (règle *mixed content*), même si l'entrée est correctement déclarée dans la console. Une entrée comme `http://192.168.1.100:3300` sera acceptée au format mais l'appel REST échouera silencieusement à l'exécution.
- **`https://` exige un certificat serveur valide.** Le certificat doit être émis par une **autorité reconnue** (CA publique, ou CA d'entreprise installée sur le poste) et correspondre au nom d'hôte. Un certificat **auto-signé, expiré ou au mauvais nom** est refusé par le navigateur : l'appel REST échoue et une frame embarquée reste **blanche**, sans message d'erreur dans Rainbow.

> **En résumé** : HTTPS avec certificat valide partout, sauf `localhost`/`127.0.0.1` où HTTP est toléré (utile en développement local uniquement).

#### Exemples valides

| Entrée | Correspond à |
|---|---|
| `https://crm.example.com` | `https://crm.example.com/n'importe/quel/chemin` |
| `https://crm.example.com:8443` | `https://crm.example.com:8443/n'importe/quel/chemin` |
| `https://*.example.com` | `https://crm.example.com`, `https://api.example.com`, … |
| `http://localhost:3300` | Serveur local en développement — seul cas où HTTP est accepté à l'exécution |

#### Exemples invalides

| Entrée | Problème |
|---|---|
| `crm.example.com` | Protocole manquant |
| `https://crm.example.com/` | Slash final — rejeté |
| `https://crm.example.com/api` | Chemin non autorisé — déclarer uniquement l'origine |
| `http://192.168.1.100:3300` | Format accepté, mais **bloqué à l'exécution** — HTTP interdit hors `localhost` (mixed content) |
| `https://` avec certificat auto-signé | Rejeté par le navigateur — certificat non reconnu |

#### Comportement si le domaine n'est pas déclaré

| Situation | Effet |
|---|---|
| Manifest chargé par le client | **Avertissement affiché à l'utilisateur** — le manifest contient des domaines non trusted |
| Appel REST (`commandType: "rest"`) | Appel bloqué par le navigateur (CSP / CORS) — pas de popup, pas de message d'erreur dans Rainbow |
| Frame (`on-main-window-actions`) | La frame s'affiche mais la page est **blanche** (ou affiche une erreur de sécurité du navigateur) |

> **⚠ L'avertissement apparaît au chargement du manifest, avant qu'une extension soit déclenchée.** Si l'utilisateur ignore l'avertissement, les extensions pointant vers des domaines non déclarés échoueront silencieusement à l'exécution.

### 12.3 CORS

Même si un domaine est déclaré trusted dans Rainbow, le **navigateur** applique indépendamment le CORS. Le serveur REST doit retourner :

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

La valeur exacte de `Access-Control-Allow-Origin` dépend de la plateforme Rainbow. Utiliser les outils développeur du navigateur (onglet Réseau) pour identifier le header `Origin` envoyé par Rainbow sur la requête bloquée. Alternativement, utiliser le wildcard :

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

> **Limitation du wildcard** — incompatible avec les credentials navigateur (`withCredentials: true`, cookies de session). Pour les extensions Rainbow passant un token via le champ `header` du manifest (ex. `Authorization: Bearer …`), le wildcard fonctionne car Rainbow envoie le token comme un header HTTP standard. Pour l'authentification par cookie, déclarer l'origine Rainbow explicitement et ajouter `Access-Control-Allow-Credentials: true`.

> **Breaking change** — un manifest qui fonctionnait avant S170 peut casser si le serveur REST ne retourne pas les headers CORS. Aucune erreur n'est affichée dans Rainbow — l'appel échoue silencieusement.

### 12.4 Local Network Access (LNA)

Si le serveur REST tourne sur un **réseau local ou privé** (ex. `https://192.168.1.100:8443`), Chrome et Edge appliquent la politique **Private Network Access**.

> **HTTP bloqué en amont** — un serveur local en HTTP (ex. `http://192.168.1.100:3300`) est déjà bloqué par la règle *mixed content* (voir §12.2) **avant** que le LNA n'entre en jeu. Le LNA ne concerne donc en pratique que les serveurs locaux servis en **HTTPS** (ou l'exception `localhost`).

> **Rainbow Desktop n'est pas concerné** — seul Rainbow Web est soumis aux règles LNA du navigateur.

> **Navigateurs concernés** — LNA est uniquement enforced par **Chrome et Edge (Chromium)**. Firefox et Safari n'implémentent pas cette politique.

Le navigateur envoie un preflight OPTIONS avec `Access-Control-Request-Private-Network: true`. Le serveur doit répondre avec :

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

en plus des headers CORS standard.

> **Permission utilisateur (Chrome/Edge)** — même avec les headers serveur corrects, Chrome peut afficher une demande de permission : *« Autoriser [site] à accéder aux ressources de votre réseau local ? »*. L'utilisateur doit explicitement accorder cette permission. Elle peut aussi être gérée dans `chrome://settings/content/privateNetworkDevices`.

### 12.5 Sécurité des applications embarquées

Quand `on-main-window-actions` charge une URL dans la frame Rainbow, l'application cible peut refuser d'être embarquée via des headers serveur :

| Header | Valeur courante | Effet |
|---|---|---|
| `X-Frame-Options` | `DENY` ou `SAMEORIGIN` | Le navigateur refuse d'afficher la page dans l'iframe — frame blanche |
| `Content-Security-Policy` | `frame-ancestors 'self'` ou `'none'` | Même effet, mécanisme moderne |

C'est indépendant de la déclaration des trusted domains — un domaine déclaré peut quand même refuser l'embedding.

**Fix :** configurer l'application pour autoriser l'origine Rainbow dans `frame-ancestors`, ou passer en `popout: true` sur `on-main-window-actions`.

> **Flux SSO / OAuth** — le fournisseur d'identité définit généralement `X-Frame-Options: DENY` pour des raisons de sécurité. Dans ce cas, le SSO ne peut pas se terminer dans l'iframe quelle que soit la déclaration des domaines. Utiliser `popout: true`.

### 12.6 Cas particulier de l'exécution locale

`commandType: "file"` (exécution d'un `.exe` ou script local) **n'est pas contrôlé par ces mécanismes**. Pour interdire ce type d'extension au niveau entreprise : empêcher l'utilisateur de charger un manifest, et déployer uniquement via le cloud Rainbow.

---

## 13. Bonnes pratiques

### 13.1 Construction

1. **Partir d'un template** exporté par Rainbow Desktop, supprimer les EPs inutiles
2. Faire un **import local** pour valider la syntaxe avant déploiement central
3. Vérifier que toutes les références sont **portables** (pas de chemin codé en dur de la machine du dev)
4. Pour les ressources locales : utiliser systématiquement `${custo.path}\…` + ZIP
5. Tester sur **Web** et **Desktop** (sauf si EP exclusivement Desktop)

### 13.2 Sécurité

- Déclarer **tous** les domaines REST cibles dans la console Rainbow avant déploiement
- Vérifier les **headers CORS** du serveur REST (`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`)
- Toujours utiliser **HTTPS avec un certificat valide** (non auto-signé) — le HTTP n'est accepté que pour `localhost`/`127.0.0.1` (voir §12.2)
- Pour les serveurs REST sur un **réseau local/privé** (servis en HTTPS) : ajouter `Access-Control-Allow-Private-Network: true` — Chrome/Edge appliquent le LNA (voir §12.4)
- Ne **jamais** mettre un secret en clair dans le manifest (il est téléchargé par chaque client)
- Pour les apps embarquées refusant l'iframe : utiliser `popout: true` ou configurer `frame-ancestors` sur l'app cible (voir §12.5)

### 13.3 Variables

- N'utiliser que les variables documentées pour l'EP — les variables non supportées sont silencieusement vides
- Pour les regex : doubler les `\` dans le JSON (`\\+33` pour `\+33`)
- Garder les corrélateurs sous **32 caractères**

### 13.4 Adaptive Cards

- Privilégier le pattern "Template dans manifest + Data via REST" : permet de modifier les données côté serveur sans redéployer le manifest
- Utiliser `${variable}` dans le template et fournir les valeurs dans le content
- `Action.Submit` envoie tout l'objet `data` de l'action

---

## 14. Validation et debug

Un **validateur custo-manifest** est disponible côté ALE pour vérifier :
- structure du manifest (`version`, `jsonType`, `extension-points`)
- conformité champ par champ selon chaque EP
- présence des icônes obligatoires
- variables Rainbow autorisées pour l'EP
- syntaxe `${object.attribute}` (vs `$(object.attribute)` ou `$[object.attribute]`)
- chemins absolus vs ressources `${custo.path}`
- compatibilité `commandType` / `method` / `bodyParameters` / `header` / `responseType`

Il propose aussi des corrections automatiques (ajout d'icône, déplacement de champs mal placés vers la racine ou vers `command`, suppression de champs non supportés, conversion de chemins absolus en ressources).

---

## 15. Historique des versions

| Version | Apports principaux |
|---|---|
| **S156** | Event `on-outgoing-pbx-call-actions` · Mass provisioning par admin · Corrélateur sur makecall · Multi-extensions (jusqu'à 3) |
| **S161** | Custo-manifest partiellement supporté en WEB · Variable `contact` (card info) |
| **S170** | Custom widget extension (free widget area) · Custo-manifest **complet** en Web et Desktop · Sécurisation REST (trusted domains + CORS) |
| **S179** | Extension `on-conversation-tab-actions` (onglet personnalisé dans le détail d'une conversation, P2P ou conférence — `scope`) · `linkJsonField` (lien hypertexte vers l'application métier/CRM de l'appelant) |
| **S183** | `redirectUrl` *(preview beta)* — sur les events d'appel et les boutons, ouvre un navigateur sur une URL calculée à partir de la réponse JSON d'un appel REST (`${response}`) · `devicesSupported` / `defaultDevicesSupported` *(preview beta)* — clients cibles d'un item (web, desktop, mobile, teams) ; première étape Mobile sur `on-main-window-actions` · `markdownTemplate` *(preview beta)* — template Markdown renseigné avec les variables Rainbow et la réponse JSON d'un appel REST, sur les EP qui affichent du Markdown |

---

---

*Document généré à partir de la présentation S170 (avril 2026) et de la spécification fonctionnelle Rainbow custo-manifest. Pour toute correction ou ajout, contacter l'équipe Product Management Rainbow.*
