# Rainbow Extensions — Custo-Manifest

**S170 Reference — April 2026**
*Source: S170 Roadmap presentation + Rainbow functional specification*

---

## 1. Overview

**Rainbow Extensions** (also called *Custo-Manifest*) make it possible to integrate Rainbow Web/Desktop with a customer's business ecosystem **without code** — simply by dropping in a JSON configuration file. An extension can:

- react to a Rainbow event (incoming call, outgoing call…);
- add a button to a part of the UI (contact list, call log, etc.);
- display content (Markdown, JSON, Adaptive Card) in a Rainbow placement;
- or open a third-party application in a frame or in a browser.

### Benefits

- **No-code**: JSON configuration only
- Boosts **user productivity** (one-click actions, contextual data)
- **Business enabler** for partners (CRM, ticketing, smart-building integrations…)

### Supported interaction types

| Type | Effect |
|---|---|
| `commandType: "file"` | Reads a file — local on Desktop, or included in the manifest ZIP on Web |
| `commandType: "rest"` | HTTP GET or POST call to an API |
| Web open | Opens a URL in the browser |
| Native execution (Desktop only) | Launches a local `.exe` or script |

### Supported display formats

- **Markdown** (default) — can also be extracted from a JSON response field via `displayJsonField`
- **Adaptive Card** (template + data)

### License prerequisites

Only **Event** extensions are supported with an **Essentials** license.
All other extensions require at least a **Business** license.

### Web vs Desktop

Since **S161**, the custo-manifest is progressively migrated from Desktop to Web. From **S170**, all extensions are available on Rainbow Web AND Desktop, **except for local application/script execution** (launching a `.exe` or a script), which remains Desktop-only. For `commandType: "file"` on Web, the file must be included in the manifest ZIP.

**Mobile** *(BETA S183)*: a first step makes `on-main-window-actions` available on Rainbow Mobile — see §6.2.

---

## 2. Manifest file structure

The custo-manifest is a JSON object following this skeleton:

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

### Global rules

- `version` must be `"2"`.
- `jsonType` must be `"Rainbow-custo-manifest"`. This field is used, inside a ZIP, to identify which JSON file is the manifest.
- Each key under `extension-points` is an array (up to **3 actions** maximum per extension point).
- Each action contains at least a `name` (except events, where it is optional) and a valid `command` object.
- `defaultDevicesSupported` *(BETA S183)* — optional array at the root of the manifest: the Rainbow clients targeted by default by all the items (see §6.2).

---

## 3. List of extension points

### 3.1 Events — automatic events (no display)

| Key | Triggered when… |
|---|---|
| `on-outgoing-pbx-call-actions` | An outgoing call is initiated |
| `on-incoming-pbx-call-actions` | An incoming call arrives |
| `on-answering-incoming-pbx-call-actions` | An incoming call is answered |
| `on-releasing-incoming-pbx-call-actions` | An incoming call is released |
| `on-makecall-insert-correlator` | At every makecall — inserts a correlator (OXE only) |

### 3.2 Buttons — clickable buttons (with optional result display)

| Key | Button placement |
|---|---|
| `on-incoming-pbx-call-button-actions` | Incoming-call pop-up |
| `on-call-log-list-actions` | Each row of the call log |
| `on-contact-list-actions` | Each row of the contact list |
| `on-contact-detail-actions` | Contact detail panel |
| `on-communication-card-actions` | Call manager bar |
| `on-bubble-actions` | Bubble property menu |
| `on-bubble-conference-actions` | Telephone-conference menu |
| `on-user-menu-actions` | User menu (Desktop / Web — not Teams) |

### 3.3 Displays — automatic information display

| Key | Placement |
|---|---|
| `on-incoming-pbx-call-display-actions` | Insertion in the incoming-call pop-up |
| `on-contact-card-display-actions` | Insertion in the contact detail panel |
| `on-main-widget-display-actions` | Widget in the main Rainbow panel |
| `on-main-display-actions` | Message in the Teams web app |
| `on-conversation-tab-actions` *(New in S179)* | Custom tab in a conversation detail (P2P or conference) |

### 3.4 Frame display — third-party WEB application

| Key | Description |
|---|---|
| `on-main-window-actions` | Displays a third-party WEB app in a Rainbow frame. With `popout: true`, opens the app in a browser window. |

---

## 4. Main fields of an action

| Field | Position | Description |
|---|---|---|
| `name` | root | Text shown (button/widget title, menu label). Mandatory depending on the EP. |
| `icon` / `iconId` | root | Button icon (URL, `${custo.path}\…` or built-in sprite). Mandatory for icon buttons. |
| `tooltip` | root | Tooltip text. Optional. |
| `command` | root | Command object (see §5). **Always mandatory**. |
| `responseType` | root | `"markdown"` (default), `"json"` or `"adaptiveCard"`. |
| Adaptive Card fields | root | `adaptiveCardTemplate`, `adaptiveCardTemplateJsonField`, `adaptiveCardContentJsonField`, `adaptiveCardSubmitUrl` |
| `displayJsonField` | root | Name of the field containing the markdown to display (when the response is JSON) |
| `redirectUrl` *(BETA S183)* | root | **Call events and buttons** — URL template opened in a new browser window once the REST call is done; requires `responseType: "json"` (see §10.1 and §10.2). |
| `markdownTemplate` *(BETA S183)* | root | **Display and button EPs** — Markdown template displayed after substitution of the Rainbow variables and `${response...}` (JSON body of the REST call); requires `commandType: "rest"` and `responseType: "json"` (see §8.4). |

### Reference table per EP

> Summary of rules: `name` mandatory/n/a, icon mandatory/n/a, allowed commandType, allowed responseType, etc.

| Extension Point | name | icon | commandType | responseType |
|---|---|---|---|---|
| `on-outgoing-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **mandatory** with `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **mandatory** with `redirectUrl` — BETA S183) |
| `on-answering-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **mandatory** with `redirectUrl` — BETA S183) |
| `on-releasing-incoming-pbx-call-actions` | n/a | n/a | `rest` | n/a (`json` **mandatory** with `redirectUrl` — BETA S183) |
| `on-incoming-pbx-call-button-actions` | "Button text" | n/a | `rest` | optional |
| `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` | "tab name" | mandatory | `rest`, `file`, `app` | optional |
| `on-main-window-actions` | "Frame name" | mandatory | Browse URL (default, `commandType` empty) | n/a |
| `on-user-menu-actions` | "menu item title" | n/a | `rest`, `file` | optional |

> `redirectUrl` *(BETA S183)* is accepted on the 4 call events (§10.1) and on the 8 button EPs (§10.2). It requires `responseType: "json"` (mandatory) — combining it with `"markdown"` or `"adaptiveCard"`, or omitting `responseType`, is invalid (a redirection replaces the display).

---

## 5. The `command` object

The `command` object is **always mandatory** and carries at least a `url`. Depending on the chosen `commandType`, additional sub-fields are valid.

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

| Field | When to use it |
|---|---|
| `url` | **mandatory**. Application path, Web URL, file or REST API. |
| `params` | Optional. Appended after `?` for GET, or as URL parameters. Variables allowed. |
| `commandType` | Optional. Default `"rest"`. Values: `"rest"`, `"file"` (depending on EP). |
| `method` | Optional (only if `commandType: "rest"`). Values: `"GET"`, `"POST"`. |
| `header` | Optional (if REST). Array of `"Header-Name: value"` strings inserted as HTTP headers. |
| `bodyParameters` | **Mandatory if `method: "POST"`**. JSON object sent as body. Variables allowed. |

---

## 6. Secondary fields (per EP)

| Field | Affected EPs | Effect |
|---|---|---|
| `AnswerOnClick` | `on-incoming-pbx-call-button-actions` | `true` → runs the action AND answers the call in one click |
| `NoShortNumber` (boolean) | call events | Does not trigger the event when the caller number is a short number |
| `RaiseChangeCall` | incoming events | `true`, `false`, `"Only"` — behavior on remote transfer (see §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`, and the 8 button EPs (§3.2) | URL template opened in a new browser window after the REST call. Variables allowed (Rainbow variables and `${response...}`, see §7.7). Requires `responseType: "json"`. |
| `popout` (boolean) | `on-main-window-actions` | `true` → opens the WEB app in a browser window (instead of displaying it in the Rainbow frame). |
| `alsoForTeams` (boolean) | `on-call-log-list-actions`, `on-main-display-actions` | Also shows the extension in the Teams add-in — **deprecated**, use `devicesSupported` (§6.2) |
| `markdownTemplate` *(BETA S183)* | all the EPs that display Markdown (display and button EPs, §8.4) | Markdown template filled with the Rainbow variables and `${response...}`. Requires `commandType: "rest"` and `responseType: "json"`. |
| `devicesSupported` *(BETA S183)* | all (`"mobile"` and `"teams"` only on some EPs — see §6.2) | Array of the Rainbow clients the item applies to: `"web"`, `"desktop"`, `"mobile"`, `"teams"`. Overrides `defaultDevicesSupported` for this item. |
| `scope` (array) | `on-conversation-tab-actions` | Conversation contexts where the tab appears: `"one_to_one"` (P2P), `"bubble"` (conference). Absent → all contexts. |
| `urlConfig` | `on-main-widget-display-actions` | HTTP/HTTPS URL for widget configuration |
| `firstNameJsonField`, `lastNameJsonField`, `companyJsonField` | `on-incoming-pbx-call-display-actions` ONLY | Caller identification (JSON response) |
| `linkJsonField` *(New in S179)* | `on-incoming-pbx-call-display-actions` ONLY | JSON field whose value is shown as a **hyperlink** to open the business app/CRM for the caller (link label = action `name` if present, else "Link") |

### 6.1 `RaiseChangeCall` values

| Value | Behavior |
|---|---|
| `false` (default) | Only direct calls are notified |
| `true` | Direct **AND** transferred calls |
| `"Only"` | Only transferred calls |

### 6.2 Target clients — `devicesSupported` *(BETA S183)*

> ⚠ **BETA (S183)** — this feature is in beta and may evolve before general availability.

By default, every item applies to **Rainbow Web and Desktop**. Two optional attributes declare which Rainbow clients an item applies to:

| Attribute | Position | Role |
|---|---|---|
| `defaultDevicesSupported` | root of the manifest (next to `version`, `jsonType`, `extension-points`) | Clients targeted by default by **all** the items of the manifest |
| `devicesSupported` | root of an item (same level as `scope`) | **Overrides** `defaultDevicesSupported` for this item only (full override, no merge) |

Allowed values for both: `"web"`, `"desktop"`, `"mobile"`, `"teams"`.

**Resolution order** for a given item: `devicesSupported` of the item (if present) → else `defaultDevicesSupported` of the manifest (if present) → else the built-in default `["web", "desktop"]`. A manifest that uses neither attribute behaves exactly as before: no migration is needed.

**Where each client is available**

| Client | Valid on |
|---|---|
| `"web"`, `"desktop"` | all the extension points |
| `"mobile"` | `on-main-window-actions` **only** (first step) |
| `"teams"` | `on-call-log-list-actions`, `on-main-display-actions` |

**Rules**
- A client requested **explicitly on an item** (`devicesSupported`) for an extension point outside the list above is reported as a **warning** by the Rainbow Validator.
- A client that is only **inherited** from `defaultDevicesSupported` and does not apply to the item's extension point is **silently ignored** — no warning.
- `alsoForTeams` is **deprecated** in favor of `devicesSupported`, but keeps working: `alsoForTeams: true` adds `"teams"` to the item's effective clients. The Rainbow Validator reports a deprecation notice.

**Mobile (first step)**
- Only **`on-main-window-actions`** is available on Mobile. On Mobile it **always opens the external application in the device browser/webview**: there is no frame embedding on Mobile, so the item's `popout` field is **not read** there (it still governs frame-or-window on Web/Desktop). It is also shown **without icon**: `icon` / `iconId` is not used on Mobile, so an item that targets Mobile only (`devicesSupported` without `"web"` and `"desktop"`) does not need one.
- On Mobile, the manifest is loaded by **cloud (administrator) deployment only**; local import is not supported.

**Example**

```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* inherits the manifest default and is therefore exposed on Mobile.
- *Internal only* overrides it and is excluded from Mobile.
- The `on-main-display-actions` item is the new-style equivalent of `alsoForTeams: true`.

---

## 7. Rainbow Variables

**`$Variables`** are replaced at runtime with their actual value. They can appear in:

- `command.url`
- `command.params`
- `command.bodyParameters`
- `urlConfig`, `adaptiveCardSubmitUrl`
- `redirectUrl` *(BETA S183)* — call events and buttons only (§10.1, §10.2)
- `markdownTemplate` *(BETA S183)* — the EPs that display Markdown (§8.4)
- `${response...}` *(BETA S183)* is available **only** in `redirectUrl` and `markdownTemplate` (§7.7)
- the **content returned to the extension for display**: may also contain Rainbow variables, which will be substituted before display

### 7.1 Syntax

```
${object.attribute}
${object.attribute.regex(pattern)}
${object.attribute.regex(pattern, replacement)}
```

### 7.2 Available objects and attributes

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

**Caller**
```
${caller.firstName}   ${caller.lastName}   ${caller.phoneNumber}
```

**Called**
```
${called.phoneNumber}
```

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

**Contact (if identified)**
```
${contact.firstName}     ${contact.lastName}
${contact.phoneNumber}   ${contact.email}
${contact.company}       ${contact.workNumber}
${contact.mobileNumber}  ${contact.personalNumber}
${contact.personalMobile}
${contact.tags}          (concatenated, comma-separated)
```

**Bubble (conversation group)**
```
${bubble.ownerEmail}   ${bubble.name}      ${bubble.shareLink}
${bubble.id}           (Cpaas)
${bubble.members}      → JSON {"organizersEmails":[…], "membersEmails":[…]}
                         **Usable only with a REST call**
```

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

### 7.3 Compatibility per EP

Each EP allows a subset of objects. Summary:

| EP | Allowed variable objects |
|---|---|
| Outgoing call events | `localUser`, `called`, `call`, `contact` |
| Incoming call events (incoming/answering/releasing) | `localUser`, `caller`, `called`, `call`, `contact` |
| Automatic OXE correlator insertion | `localUser`, `called` |
| Icon buttons (contact-list, contact-detail, call-log-list, contact-card-display) | `localUser`, `contact` |
| Call buttons (communication-card, incoming-button, incoming-display) | `localUser`, `caller`, `called`, `call`, `contact` |
| Bubbles | `localUser`, `bubble` |
| Conversation tab | `localUser`, `contact`, `bubble` |
| Display widget / main-display / main-window / user-menu | `localUser` |

### 7.4 `regex` modifier

Applies a regex to the variable value **before substitution**. ⚠ Rainbow does **not** trim whitespace around the comma separating `pattern` and `replacement` — a space after the comma ends up literally in the result (confirmed live 2026-10-02, e.g. `regex(@.*$, @example.com)` produces `"name @example.com"` with a stray space). Use **no space** around the comma:

```jsonc
// Replace +33 or +1 by 0 (normalize a number)
"params": "pbx=${localUser.phonePbx.regex(^\\+33|^\\+1,0)}"

// Replace the email domain
"params": "byEmail=${localUser.email.regex(alcatel.com,al-enterprise.com)}"

// Keep the last 9 digits (regex with no replacement = extraction)
"params": "${called.phoneNumber.regex(.{0,9}$)}"
```

### 7.5 The `${time}` variable — timestamp

Special timestamp variable, available on **all EPs**. Substituted at the moment the action is executed.

| Variable | Value | Format / comment |
|---|---|---|
| `${time}` | Full date-time | `YYYY/MM/DD HH:MM:SS`, e.g. `2026-05-18 15:30:45` (not ISO 8601, no milliseconds — confirmed live 2026-10-02) |
| `${time.year}` | Year | 4 digits, e.g. `2026` |
| `${time.month}` | Month | 2 digits, `01`–`12` |
| `${time.day}` | Day of month | 2 digits, `01`–`31` |
| `${time.hour}` | Hour | 2 digits, `00`–`23` |
| `${time.minute}` | Minute | 2 digits, `00`–`59` |
| `${time.second}` | Second | 2 digits, `00`–`59` |
| `${time.millisec}` | Milliseconds | 3 digits, `000`–`999` |
| `${time.hex}` | Unix Epoch in hex (4 bytes) | **Reserved for `hexCorrelatorData`** — do not use in an arbitrary string or JSON |

#### Examples

```jsonc
// Build a log identifier
"params": "logId=${time.year}-${time.month}-${time.day}_${time.hour}${time.minute}${time.second}"
// → logId=2026-05-18_153045

// POST body with full timestamp
"bodyParameters": { "ts": "${time}", "user": "${localUser.loginEmail}" }

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

### 7.6 Local resources — `${custo.path}`

To distribute a manifest together with local files (icons, static content):

1. Reference each resource as `${custo.path}\\file-name.ext`
2. Package everything into a **ZIP**:
   - `custo-manifest.json` at the root
   - the resource files next to it

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

The ZIP must contain: `custo-manifest.json`, `basketball.png`, `FileDisplay.txt`.

#### Manifest identification inside the ZIP

Rainbow identifies the manifest file using the following priority order:

1. **`custo-manifest.json`** — file with exactly this name, at the root of the ZIP
2. **Otherwise**, the **first `.json` file** found in the ZIP that contains `"jsonType": "Rainbow-custo-manifest"`

If no file matches either criterion, ZIP import fails.

> 💡 To guarantee unambiguous detection, name your manifest `custo-manifest.json` and place it at the root of the ZIP.

---


---

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

`${response}` represents the **JSON body returned by the REST call of the same action**. It is available in `redirectUrl` of the call events (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) and of the 8 button EPs — see §10.1 and §10.2 — and in **`markdownTemplate`** of the EPs that display Markdown — see §8.4. It is not available in any other field.

```
${response.contactId}               field of the response
${response.data.contact.id}         nested path
${response[0].contactId}            array index
```

**Lenient resolution.** Some REST APIs return a single object when there is one result and an array when there are several. Both syntaxes therefore work whatever the shape of the response:

| Syntax | Response is an object | Response is an array |
|---|---|---|
| `${response.contactId}` | the field of the object | the field of the **first element** |
| `${response[0].contactId}` | the object itself is taken as the first element | the field of the first element |

- Any other index on an object (`${response[1]...}`) is a missing field.
- An empty array (`[]`) is a missing field.

When the targeted field is missing, nothing happens (see §10.1, *Failure handling*).

---

## 8. Text / Markdown display

When an extension can display a response and `responseType: "markdown"` (or is absent — that is the default), the response content is rendered **as Markdown-enriched text** in a Rainbow popup. **Emojis** are also supported (native Unicode, pasted directly — `:smile:`-style shortcodes are **not** interpreted, they display as-is).

### 8.1 Common Markdown syntax

Rainbow supports a subset of standard Markdown. The elements most useful in an extension popup:

| Syntax | Effect |
|---|---|
| `**bold**` | **bold** |
| `*italic*` | *italic* |
| `# Title 1`, `## Title 2`, `### Title 3` | hierarchical titles |
| `- item` or `* item` | bulleted list |
| `1. item` | numbered list |
| `[label](https://url.com)` | clickable link |
| ```` ```\ncode block\n``` ```` | code block |
| `---` | horizontal rule |
| `\| col 1 \| col 2 \|` | table (with separator `\|---\|---\|`) |
| 🎉 ✅ 📞 | Unicode emojis (direct copy/paste) |

#### Example — Markdown enriched from REST output

An API returns:

```markdown
## Contact identified 📇

**Marie Curie** — *Sorbonne University*

| Field | Value |
|---|---|
| Phone | +33 1 42 34 56 78 |
| Email | [marie.curie@example.com](mailto:marie.curie@example.com) |
| Status | ✅ Active customer |

> 💡 Clicking the email opens your mail client.
```

The Rainbow popup will show the title, the formatted table, the clickable links and the emojis.

#### Example — Demo of supported syntax (local file)

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

Content of `SupportedMarkdown.txt` (delivered in the ZIP next to the manifest):

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

Rendering in Rainbow:

![Markdown rendering in Rainbow](images/markdown.png)

### 8.2 Markdown extracted from a JSON response

If `responseType: "json"` **and** `displayJsonField` is defined, Rainbow interprets the response as JSON, extracts the value of the field pointed to by `displayJsonField`, and displays it as text/Markdown.

This is useful when the server already returns a structured JSON (for example a business-API payload) that contains the markdown to display in one of its fields.

#### Example — Markdown inside a JSON field

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

API response:

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

Rainbow extracts `display`, substitutes the `${contact.*}` variables, and shows the result in the popup.

### 8.3 Display via standard output (Desktop only)

When an EP supports a Markdown-display return value, you can capture the **standard output** of a script or program:

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

The content written to `stdout` by the script is displayed in a Rainbow popup. Ideal for simple integration or prototyping without REST infrastructure.

> ⚠ **Rainbow Desktop only.** On Web, the script cannot be executed locally, so this mode is not available.

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

> ⚠ **BETA (S183)** — this feature is in beta and may evolve before general availability.

Until now, the result of a REST call could be displayed as **one field of the JSON response** (`displayJsonField`, §8.2) or laid out with an **Adaptive Card** (§9). `markdownTemplate` adds a third option: a **Markdown template declared in the manifest**, filled with the Rainbow variables and with the fields of the JSON response of the REST call.

**Rules**
- `command` is of type **`rest`** and the response of type **JSON** (`responseType: "json"`) — both are **mandatory** with `markdownTemplate`.
- `markdownTemplate` (string, Markdown) is at the root of the action. Its text is displayed after a **variable substitution**: the usual **Rainbow variables** of the EP (§7) and the variable **`${response}`** (§7.7), i.e. the JSON body returned by the REST call of the same action (`${response.contactId}`, `${response.data.contact.id}`, `${response[0].contactId}`; lenient object/array resolution, §7.7).
- The substituted values are inserted **as is**: no URL-encoding and no escaping of Markdown characters.
- **Order of execution** — when several of these elements are defined on the same action, Rainbow handles them in this order, and the first one that applies is executed: `redirectUrl`, then `markdownTemplate`, then `displayJsonField`, then Adaptive Card. In particular, if a `redirectUrl` exists and a valid REST response is returned, the redirection is applied and `markdownTemplate` is **not** displayed; if there is **no `redirectUrl`**, or if it is **empty because the REST response is empty**, the content of `markdownTemplate` is displayed.
- **Failure handling** — if the REST call fails (timeout, HTTP error), if the response is not valid JSON, or if a referenced field is missing: **nothing is displayed**.
- A client that does not know `markdownTemplate` ignores the field (no error).

**Available on** all the extension points that display Markdown:
- Display: `on-incoming-pbx-call-display-actions`, `on-contact-card-display-actions`, `on-main-widget-display-actions`, `on-main-display-actions`, `on-conversation-tab-actions`;
- Buttons displaying a result: `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`.

The call events do not display anything and are not concerned.

**Example — card built from the response**

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

With a response `{"firstName":"Jane","lastName":"Doe","company":"ACME"}`, the pop-up displays the heading *Jane Doe* followed by the company and the phone number.

---

## 9. Adaptive Cards

**Adaptive Card** is an open standard defined by **Microsoft** to represent rich content (text, lists, forms, buttons, images) in a portable JSON format, rendered consistently by every application that integrates it.

📖 [Microsoft Adaptive Card reference](https://adaptivecards.io/explorer/) — official documentation and sample library.

The Adaptive Card model separates two things:
- a **template** (presentation) described in JSON — visual structure with `${...}` variables;
- **dynamic data** also in JSON — which fills in the template variables.

Rainbow keeps this separation and renders the card in the client (Desktop or Web).
- The **template** can be predefined in the manifest (`adaptiveCardTemplate`) or included in the JSON response of a REST call (extracted via `adaptiveCardTemplateJsonField`).
- The **data** can likewise be in the manifest, in a separate file (useful for testing), but most often comes from a REST call to a business API.

Four combinations are supported on Rainbow Desktop **and** Web:

| Mode | Template | Content |
|---|---|---|
| **Everything in the manifest** | inline | inline |
| **Template in manifest** | inline | in a file |
| **Template in manifest + REST data** | inline | returned by a REST call |
| **All via REST** | returned by REST | returned by REST |

### Relevant fields (at the root of the action)

| Field | Role |
|---|---|
| `adaptiveCardTemplate` | Inline JSON template inside the manifest |
| `adaptiveCardTemplateJsonField` | Name of the REST response field containing the template |
| `adaptiveCardContentJsonField` | Name of the REST response field containing the data. **If empty or missing, variables are looked up directly at the root of the response JSON object.** |
| `adaptiveCardSubmitUrl` | REST URL called as POST when an `Action.Submit` is invoked in the card |

### Supported actions in an Adaptive Card

- **`Action.OpenUrl`** — opens a URL in the browser.
- **`Action.Submit`** — Rainbow turns this action into a **POST** to the URL defined by `adaptiveCardSubmitUrl`. The request body contains the action's `data` object (plus the values of any `Input.*`).
  - If the REST response returns **refreshed data** (same shape as the initial response, or a new template), Rainbow **refreshes the card** automatically with the new values.

### Supported Adaptive Card tags (indicative)

Reference table for the support of the main Adaptive Card elements in Rainbow. The status may change between versions — to verify precisely against your current Rainbow version, use the **Adaptive Card** test tool built into RainbowCustoServer.

| AC element | Support | Notes |
|---|:---:|---|
| `TextBlock` | ✅ | basic text element, rich styling options |
| `Image` | ✅ | http(s) URL, data URI |
| `ColumnSet` / `Column` | ✅ | column layout |
| `Container` | ✅ | grouping, background styles |
| `FactSet` | ✅ | key / value table |
| `ImageSet` | ✅ | image gallery |
| `ActionSet` | ✅ | inline button group |
| `RichTextBlock` / `TextRun` | ✅ | multi-styled text on a single line |
| `Table` | ✅ | structured table (AC 1.5+) |
| `Input.Text` | ✅ | text input |
| `Input.Number` | ✅ | numeric input |
| `Input.Date` | ✅ | date picker |
| `Input.Time` | ✅ | time picker |
| `Input.Toggle` | ✅ | check box |
| `Input.ChoiceSet` | ✅ | dropdown / radio / multi-select |
| `Action.OpenUrl` | ✅ | opens the URL in the browser |
| `Action.Submit` | ✅ | POST to `adaptiveCardSubmitUrl` |
| `Action.ToggleVisibility` | ✅ | dynamically hide / show elements |
| `Action.ShowCard` | ✅ | inline sub-card |
| `Media` | ⚠️ | limited video / audio rendering |
| `Carousel` | ⚠️ | navigation between cards — rendering limits (AC 1.4+) |
| `Badge` | ❌ | AC 1.6+ — not supported |
| `CodeBlock` | ❌ | AC 1.6+ — not supported |
| `Icon` | ❌ | AC 1.6+ — not supported |
| `CompoundButton` | ❌ | AC 1.6+ — not supported |
| `ProgressRing` | ❌ | AC 1.6+ — not supported |
| `ProgressBar` | ❌ | AC 1.6+ — not supported |
| `Action.Popover` | ❌ | AC 1.6+ — not supported |
| `Input.Rating` | ❌ | AC 1.6+ — not supported |
| `Chart.*` (Donut, Line, Bar…) | ❌ | Chart extensions not supported |

Legend: ✅ supported · ⚠️ supported with limits · ❌ not supported

### Example: widget with template and data from 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"
}]
```

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

Rendering in Rainbow:

![Adaptive Card rendering in Rainbow](images/adaptive.png)

---

## 10. Reference by extension type

This section groups extension points by functional family. Four families: **telephony events**, **buttons**, **display**, **application**.

---

### 10.1 Telephony events

![Rainbow telephony events](images/telephony-events.svg)

**Principle**: no UI of their own. These extensions automatically trigger an action (REST call, local execution, URL open) when a telephony event occurs. Typical use cases: call logging into an ERP, triggering a CRM workflow, presence update in a business system.

**Extension points**:

| Key | Trigger |
|---|---|
| `on-outgoing-pbx-call-actions` | An outgoing call is initiated |
| `on-incoming-pbx-call-actions` | An incoming call arrives |
| `on-answering-incoming-pbx-call-actions` | An incoming call is answered |
| `on-releasing-incoming-pbx-call-actions` | An incoming call is released |
| `on-makecall-insert-correlator` | At every makecall — inserts a correlator (OXE only) |

**License prerequisite**: Essentials (events are the only family supported on this license).

#### Fields (standard action)

| Field | Position | Type | Mandatory | Values / constraints |
|---|---|---|---|---|
| `command` | root | object | **YES** | command object |
| `command.url` | command | string | **YES** | HTTP(S) URL or `{{server}}/…` |
| `command.params` | command | string | no | URL parameters (appended after `?`). Variables allowed. |
| `command.commandType` | command | string | no | `"rest"` (default and only supported value for events) |
| `command.method` | command | string | no | `"GET"` (default) or `"POST"` |
| `command.header` | command | array | no | Array of `"Header-Name: value"` strings |
| `command.bodyParameters` | command | object | **YES if `method: "POST"`** | JSON sent as body. Variables allowed. |
| `NoShortNumber` | root | boolean | no | If `true`, the event is not raised when the caller is a short number |
| `RaiseChangeCall` | root | `true` \| `false` \| `"Only"` | no | (incoming events only) — handles propagation on remote transfer (§6.1) |
| `redirectUrl` *(BETA S183)* | root | string | no | URL template opened in a new browser window after the REST call (see below). Requires `responseType: "json"`. |
| `responseType` | root | `"json"` | **YES if `redirectUrl`** | Mandatory with `redirectUrl`. Otherwise no `responseType` on events. |

**Note**:
- **No `name`, `icon`** — an event is silent on the Rainbow UI side
- **No `responseType`**, except `"json"`, which is **mandatory** together with `redirectUrl` *(BETA S183)* — see below
- `commandType: "file"` not supported

**Rainbow variables allowed per 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` only | — | — | ✓ |

*¹ — `${contact.*}` is resolved only **if a contact has been identified** (number recognized by Rainbow). Otherwise, `${contact.*}` variables are empty at substitution time.*

*In `redirectUrl` only (BETA S183), `${response...}` (JSON body of the REST call of the same action) is also available — see §7.7.*

#### Redirect after a REST call — `redirectUrl` *(BETA S183)*

**Principle**: chain a REST call with the opening of a URL built from its JSON response — typically a **CTI screen-pop**: 1) a REST API is queried with the caller's number to get an identifier (e.g. `contactId`), 2) a "screen-pop" page decorated with that identifier is opened. The whole chain is declared in the manifest, with no intermediate backend.

Available on the four call events (`on-outgoing-pbx-call-actions`, `on-incoming-pbx-call-actions`, `on-answering-incoming-pbx-call-actions`, `on-releasing-incoming-pbx-call-actions`) **and on the button extension points** (§10.2).

**Rules**:
- **`redirectUrl`** (string, template): a redirection is applied when it is present. `responseType: "json"` is **mandatory** with it (the REST response is read as JSON to feed `${response}`); it is not a new `responseType` value.
- Rainbow's only job is a **variable substitution** in `redirectUrl`, whether the variable is a Rainbow variable (`${caller.phoneNumber}`, …) or a `${response...}` variable (§7.7). Two usages:
  - **the response provides a part of the destination**: `"redirectUrl": "http://server/screenPop?id=${response.contactId}"`;
  - **the response provides the whole destination**: `"redirectUrl": "${response.url}"` — the `url` field of the response is the page to open.
- The substituted value is **automatically URL-encoded** (same mechanism as the other manifest variables).
- The URL **always** opens in a **new browser window** (popup).
- **Failure handling** — if the REST call fails (timeout, HTTP error), if the targeted field is absent from the response, or if the response is not valid JSON: **nothing happens** (no popup, no error shown to the user); only a client-side log trace is written for diagnostics.
- A client that does not know `redirectUrl` ignores the field (no error).

> ⚠ **BETA (S183)** — this feature is in beta and may evolve before general availability.

**Example 1 — the response provides a part of the 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}"
}]
```

**Example 2 — the response provides the whole destination (response `{"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}"
}]
```

**Example 3 — Rainbow variable and response variable combined; the API answers an object *or* an array (lenient resolution, §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}"
}]
```

#### Caller-ID resolution
Caller identity resolution (first/last name, company) and the clickable link to the CRM record are **not** done via telephony events (which are silent on the Rainbow UI side), but via the display EP **`on-incoming-pbx-call-display-actions`** — see **§10.3.1**.

#### Special schema — `on-makecall-insert-correlator` (OXE)

This EP does not follow the standard `command` schema. It inserts a correlator (ASCII or hex) on every makecall:

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

Limited to 32 characters. Only one type (`correlatorData` **or** `hexCorrelatorData`) at a time.

#### Example 1 — incoming call logging (POST with 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}"
        }
      }
    }]
  }
}
```

> ℹ **Caller-ID resolution** (first/last name, company + CRM link) is **not** an event: it is declared via `on-incoming-pbx-call-display-actions` — see **§10.3.1**.

#### Example 2 — Web-app popup, short-number filtering

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

The event will not fire for internal calls (short extensions).

#### Example 3 — running a local script on call answer

> **⚠ Rainbow Desktop only** — running a local script or application (`.exe`, `.bat`, etc.) is not supported by Rainbow Web. On Web, this event is ignored.

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

The `log-call.bat` script is run locally when the user answers the call. Rainbow variables are substituted in `params` before the command-line invocation.

#### Example 4 — OXE correlator on makecall

> **⚠ OXE only** — this EP only works on an Alcatel-Lucent OXE PBX.

To attach a correlator to every outgoing call initiated through makecall:

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

**Rules**:
- Either `correlatorData` (ASCII) **OR** `hexCorrelatorData` (hex) — **only one type allowed**
- Limited to **32 characters**
- Allowed variables: `${localUser.*}`, `${called.phoneNumber}`, `${time.*}`
- `${time.hex}` is a special 4-byte format — only with `hexCorrelatorData`

---

### 10.2 Buttons

![Buttons in the Rainbow UI](images/buttons.png)

**Principle**: an icon-button is inserted at a specific location of the Rainbow UI. On click, an action is executed and, optionally, its result is displayed in a popup (Markdown or Adaptive Card). 3 buttons maximum per EP.

**Extension points**:

| Key | Button placement |
|---|---|
| `on-incoming-pbx-call-button-actions` | Incoming-call pop-up |
| `on-call-log-list-actions` | Each row of the call log |
| `on-contact-list-actions` | Each row of the contact list |
| `on-contact-detail-actions` | Contact detail panel |
| `on-communication-card-actions` | Call manager bar (menu) |
| `on-bubble-actions` | Bubble property menu |
| `on-bubble-conference-actions` | Telephone conference menu |
| `on-user-menu-actions` | User menu (Desktop / Web — not Teams) |

**License prerequisite**: Business minimum.

#### Fields (all buttons)

| Field | Position | Type | Mandatory | Values / constraints |
|---|---|---|---|---|
| `name` | root | string | see specifics | Button text / tooltip or menu label |
| `icon` or `iconId` | root | string | see specifics | URL `https://…`, `${custo.path}\file.png` or built-in sprite name |
| `tooltip` | root | string | no | Alternate tooltip (ignored on some EPs) |
| `command` | root | object | **YES** | command object |
| `command.url` | command | string | **YES** | HTTP(S) URL, `{{server}}/…` or file path |
| `command.params` | command | string | no | URL parameters. Variables allowed. |
| `command.commandType` | command | string | no | `"rest"` (default) or `"file"`. On Web, `"file"` requires the file inside the ZIP. |
| `command.method` | command | string | no | `"GET"` (default) or `"POST"` |
| `command.header` | command | array | no | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **YES if POST** | JSON sent as body |
| `responseType` | root | string | see specifics | `"markdown"`, `"json"` or `"adaptiveCard"`. If present → popup. Otherwise → action runs with no displayed result. |
| `displayJsonField` | root | string | no | If `responseType: "json"`, name of the JSON field containing the markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | root | — | per mode | If `responseType: "adaptiveCard"` — see §8 |
| `AnswerOnClick` | root | boolean | no | (only `on-incoming-pbx-call-button-actions`) — if `true`, also answers the call |
| `alsoForTeams` | root | boolean | no | (only `on-call-log-list-actions`) — also shown in the Teams add-in |
| `redirectUrl` *(BETA S183)* | root | string | no | URL template opened in a new browser window after the REST call (see below). Requires `responseType: "json"`. |
| `markdownTemplate` *(BETA S183)* | root | string | no | Markdown template displayed after substitution of the Rainbow variables and `${response...}`. Requires `commandType: "rest"` and `responseType: "json"` — see §8.4. |

#### Specifics per EP

| EP | `name` | `icon` | `responseType` | Allowed variables |
|---|---|---|---|---|
| `on-incoming-pbx-call-button-actions` | "Button text" | not used | optional | localUser, caller, called, call, contact |
| `on-call-log-list-actions` | tooltip | **YES** | optional | localUser, contact |
| `on-contact-list-actions` | tooltip | **YES** | optional | localUser, contact |
| `on-contact-detail-actions` | tooltip | **YES** | optional | localUser, contact |
| `on-communication-card-actions` | "menu text" | **YES** (menu) | optional | localUser, caller, called, call, contact |
| `on-bubble-actions` | "menu text" | **YES** (menu) | optional | localUser, bubble |
| `on-bubble-conference-actions` | "menu text" | **YES** (menu) | optional | localUser, bubble |
| `on-user-menu-actions` | "menu item title" | **YES** (menu) | optional | localUser |

#### Redirect after a REST call — `redirectUrl` *(BETA S183)*

Every button EP accepts `redirectUrl`: on click, the REST call is executed and the URL — built from the JSON response — is opened in a **new browser window**. The rules are the same as for the call events (see **§10.1**): `redirectUrl` requires `responseType: "json"`, variables (the Rainbow variables of the EP and `${response...}`, §7.7) are substituted and URL-encoded, nothing happens if the REST call fails, if the field is missing or if the response is not JSON.

Specifics for buttons:
- A redirection **replaces the display**: `responseType` must be `"json"` (mandatory). Combining `redirectUrl` with `"markdown"` or `"adaptiveCard"`, or omitting `responseType`, is **invalid** (reported as an error by the Rainbow Validator).
- `command.commandType` must be `"rest"` (default) — the response only exists for a REST call, not for `"file"`.

> ⚠ **BETA (S183)** — this feature is in beta and may evolve before general availability.

**Example — contact-list button that opens the CRM record resolved by a REST lookup**

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

#### Example 1 — button in the contact list that opens an external CRM

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

No `responseType` → the URL is opened in a new browser tab, with no popup inside Rainbow.

#### Example 2 — button on incoming call that creates a ticket and answers

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

The click creates the ticket **and** answers the call in a single operation (`AnswerOnClick: true`).

#### Example 3 — Adaptive Card menu inside the bubble menu

```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}` requires `commandType: "rest"` (see §7).

---

### 10.3 Display

![Automatic information display in Rainbow](images/displays.png)

**Principle**: automatically inserts content (Markdown or Adaptive Card) at a specific location of the UI — with no user interaction. The content is fetched when the placement becomes visible.

**Extension points**:

| Key | Display placement |
|---|---|
| `on-incoming-pbx-call-display-actions` | In the incoming-call pop-up |
| `on-contact-card-display-actions` | In the contact detail panel |
| `on-main-widget-display-actions` | Widget in the main Rainbow panel |
| `on-main-display-actions` | Message in the Teams webapp |
| `on-conversation-tab-actions` | Custom tab in a conversation (P2P or conference) — see below |

**License prerequisite**: Business minimum.

#### Fields (all displays)

| Field | Position | Type | Mandatory | Values / constraints |
|---|---|---|---|---|
| `name` | root | string | see specifics | Title (widget only) |
| `command` | root | object | **YES** | command object |
| `command.url` | command | string | **YES** | HTTP(S) URL, `{{server}}/…` or file |
| `command.params` | command | string | no | URL parameters. Variables allowed. |
| `command.commandType` | command | string | no | `"rest"` (default) or `"file"`. On Web, `"file"` → file inside the ZIP. |
| `command.method` | command | string | no | `"GET"` (default) or `"POST"` |
| `command.header` | command | array | no | Array `"Header-Name: value"` |
| `command.bodyParameters` | command | object | **YES if POST** | JSON body |
| `responseType` | root | string | **YES** | `"markdown"`, `"json"` or `"adaptiveCard"` ¹ — always required for displays |
| `displayJsonField` | root | string | no | If `responseType: "json"`, field containing the markdown |
| `adaptiveCardTemplate` / `adaptiveCardTemplateJsonField` / `adaptiveCardContentJsonField` / `adaptiveCardSubmitUrl` | root | — | per mode | If `responseType: "adaptiveCard"` — see §8 |
| `urlConfig` | root | string | no | (only `on-main-widget-display-actions`) — widget configuration URL |
| `alsoForTeams` | root | boolean | no | (only `on-main-display-actions`) — show in Teams web add-in |
| `markdownTemplate` *(BETA S183)* | root | string | no | Markdown template displayed after substitution of the Rainbow variables and `${response...}`. Requires `commandType: "rest"` and `responseType: "json"` — see §8.4. |

*¹ `adaptiveCard` is NOT supported by `on-incoming-pbx-call-display-actions` (incoming-call pop-up) — see §10.3.1.*

#### Specifics per EP

| EP | `name` | Allowed variables |
|---|---|---|
| `on-incoming-pbx-call-display-actions` | not used | localUser, caller, called, call, contact |
| `on-contact-card-display-actions` | not used | localUser, contact |
| `on-main-widget-display-actions` | "widget title" | localUser |
| `on-main-display-actions` | not used | localUser |
| `on-conversation-tab-actions` | "tab name" | localUser, contact, bubble |

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

**Role**: automatically display information in the **incoming-call pop-up**, with no user interaction. The content is fetched when the pop-up appears, from a source declared in `command`.

**Possible content sources**:

| Source | `command` | Effect |
|---|---|---|
| **File** | `commandType: "file"`, `url` = file path | reads a file and displays its content |
| **Script** | `commandType: "file"`, `url` = executable/script | runs the script and displays its output |
| **Web page** | `commandType: "rest"`, `url` = http(s) | opens the URL and displays its content |
| **REST API** | `commandType: "rest"`, `method` GET/POST | calls a REST API and uses the response |

**`responseType`**: `"markdown"` (default) or `"json"`.

> ⚠️ **Adaptive Card is NOT usable** for this extension point.

**Using a JSON response** (`responseType: "json"`) — several fields of the response can be extracted:

| Manifest field | Role |
|---|---|
| `displayJsonField` | name of the JSON field **whose value is displayed** (text / Markdown) in the pop-up |
| `firstNameJsonField` | **overrides/sets the caller's displayed first name** |
| `lastNameJsonField` | **overrides/sets the last name** of the caller |
| `companyJsonField` | **overrides/sets the company** of the caller |
| `linkJsonField` | name of the JSON field whose value is added as a **clickable link** in the pop-up (label = action `name` if present, else "Link") — typically to open the caller's record in the business app/CRM |

In a single call the pop-up can thus **enrich the caller identity** (first/last name and company resolved from the CRM), **display content**, and offer a **link** to the record.

**Example — caller-ID resolution + content + link from a REST API**:

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

Expected REST response (example):

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

Rainbow displays the `display` value, replaces the caller's first/last name and company with the resolved ones, and adds the `crmUrl` value as a clickable link (label = action `name`, else "Link").

> **⚠ Limited persistence** — the resolved identity (first/last name, company) **does not persist beyond the current Rainbow session**: after the session closes, the call log shows only the raw number. For persistent identification, add the contact to the Rainbow directory.

**Concrete example — Markdown stored in a CRM text field**

Tip: store **Markdown** directly in a CRM text field (here `notes`). Rainbow renders it as-is in the popup — bold, emojis and a **clickable link** included. Here the fields sit under a `contact` object (`contact.*` paths).

Manifest excerpt:

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

REST response (the `notes` field contains 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"
  }
}
```

Rendered in the incoming-call popup:

![Markdown display in the incoming-call popup](images/incomingCallDisplaySample1.png)

#### Example 1 — caller-ID Markdown card in the incoming-call popup

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

#### Example 2 — Adaptive Card widget refreshed on each open

```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` lets the card's `Action.Submit` buttons POST their `data` to that URL.

#### Example 3 — display declared for Teams as well

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

#### Conversation tab — `on-conversation-tab-actions`

> ℹ **New in S179.**

**Principle**: adds a **custom tab** in the conversation detail column, for a P2P conversation and/or a conference (bubble). The tab item is defined by `name`, `icon` and `tooltip`. On selection the action runs — a REST call (`rest`), a local script/Exec (`file`) or a web page (`app`) — and the returned content is shown in the tab (`markdown` or `adaptiveCard`). During a conference, the tab is offered in the **Meeting tools** list.

**License**: all service plans except Essential.

Unlike the other displays, `responseType` is **optional** here: a tab that only browses a web page returns no display content.

**`scope`** (array, optional) — the conversation contexts where the tab appears:

| Value | Context |
|---|---|
| `"one_to_one"` | P2P conversations |
| `"bubble"` | Conferences (bubbles) |

If `scope` is absent, the tab is proposed in all contexts.

**Allowed variables**: `${localUser.*}`, all `${contact.*}` and all `${bubble.*}` (see §7.2). `${bubble.members}` is usable only with a REST call.

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

![Third-party WEB application in a Rainbow frame](images/applications.png)

**Principle**: embeds a **third-party WEB application** inside a Rainbow UI frame. No REST `command` object — it is simply a URL loaded as an iframe. With `popout: true`, the application opens in a browser window (instead of being embedded).

**Extension point**:

| Key | Placement |
|---|---|
| `on-main-window-actions` | Frame in the main Rainbow window |

**License prerequisite**: Business minimum.

#### Fields

| Field | Position | Type | Mandatory | Values / constraints |
|---|---|---|---|---|
| `name` | root | string | **YES** | "Frame name" — application name shown in the Rainbow bar |
| `icon` or `iconId` | root | string | **YES** (not needed for an item that targets Mobile only) | URL `https://…`, `${custo.path}\file.png` or sprite |
| `tooltip` | root | string | no | Tooltip |
| `command` | root | object | **YES** | command object — at least a `url` |
| `command.url` | command | string | **YES** | HTTP(S) URL of the WEB app to embed |
| `command.params` | command | string | no | URL parameters. Variables allowed. |
| `command.commandType` | command | string | no | Empty by default → "Browse URL" behavior (URL is simply loaded) |
| `popout` | root | boolean | no | `true` → opens the app in a browser window instead of the Rainbow frame |
| `devicesSupported` *(BETA S183)* | root | array | no | Rainbow clients targeted by the item (`"web"`, `"desktop"`, `"mobile"`) — see §6.2 |

**Note**:
- **No `method`, `bodyParameters`, `header`, `responseType`** — this is a URL load, not an API call
- **No variables other than `localUser.*`** — the EP is at the Rainbow application level, not tied to a contact/call

**Allowed Rainbow variables**: `${localUser.*}`

#### Mobile *(BETA S183)*

`on-main-window-actions` is the first extension point available on Rainbow Mobile (`devicesSupported` including `"mobile"`, §6.2). On Mobile the application **always opens in the device browser/webview**, whatever the value of `popout`, which is not read there, and **without icon** (the icon is not used on Mobile). The manifest must be deployed through the administrator (cloud) mechanism.

#### Security

The loaded URL must be declared as a **trusted domain** in the Rainbow console (Company → Customization → Custo-manifest domains). Otherwise the browser will refuse to embed it (CSP). See §12.

> **⚠ The third-party WEB app must accept being shown inside a frame.**
> Many sites refuse iframe embedding by default through:
> - the HTTP header `X-Frame-Options: DENY` or `SAMEORIGIN`
> - or the CSP directive `Content-Security-Policy: frame-ancestors 'self'`
>
> If the target app uses one of these protections, the frame stays **empty** (blank page) or shows a browser error, with no message inside Rainbow. Check those headers on the app's server before embedding it. If the app cannot be modified, the alternative is `popout: true` to open it in a browser window instead of a frame.

#### Example 1 — embedding a business WEB app

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

The app appears in Rainbow under the name "My CRM". On click, the CRM dashboard loads in the frame, with the user's email as a parameter.

#### Example 2 — opening in the browser (instead of the frame)

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

`popout: true` → the app opens in a browser window. Useful when the app refuses to be embedded (restrictive CSP frame-ancestors) or when you want a large workspace.

#### Example 3 — app with no user authentication (static)

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

## 11. Creation & deployment

A manifest can be deployed in two ways:

- **Locally**, by importing the file (or ZIP) by the end user into the Rainbow client.
- **Automatically from the cloud**, when the administrator has assigned the manifest to the user via the Rainbow console. The client then downloads it at startup, with no user action.

Local deployment is recommended for the **testing phase** or when **few users** are involved. The administrator can disable this mode via a **profile flag**: in that case, the Import/Export option disappears from the user side.

**Administrator deployment takes priority**: a manifest assigned by the admin replaces any local manifest, and the user cannot override it.

**Scope**: administrator deployment applies to **all instances** of the user's Rainbow client (Desktop, Web, across all machines/sessions). Local deployment, on the other hand, only covers **the machine or browser used for the import** — it does not follow the user to other workstations.

### 11.1 Creation

There are several ways to obtain an initial manifest file:

**From the Rainbow Desktop client (export a template)**

It is possible to get a local template file by requesting an export **while no manifest has yet been imported**. The client then generates a sample file containing all supported extension points.

1. In the Rainbow Desktop client: **Settings → Telephony → Customization → Export**
2. Remove unused extension points (keep only those you want to configure)
3. Fill in the content of each kept EP (`name`, `icon`, `command`, etc.)
4. Import to test locally

**From a generator tool or example**

Manifest generation tools (for example ALE's **Rainbow Generator**) or the **examples** provided in this documentation can also serve as a starting point — copy the JSON structure, adapt it to your business context, and import it.

### 11.2 ZIP with resources

If the manifest references local files (icons, texts, scripts), create a ZIP containing the manifest **and** the resource files, then import it into the client.

**Reminders** (see §7.6):
- Reference every ZIP resource as `${custo.path}\\file-name.ext` in the manifest.
- Include the `"jsonType": "Rainbow-custo-manifest"` field at the root of the manifest — this is what allows Rainbow to identify the manifest file inside the ZIP. Otherwise, Rainbow looks for a file named exactly `custo-manifest.json`.

**Web / Desktop compatibility**: the ZIP is compatible with both Rainbow clients. On Desktop, resources are written to disk; on Web, they are loaded in memory from the downloaded ZIP. The same ZIP can therefore be deployed indifferently for both platforms.

### 11.3 Mass provisioning (by administrator)

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

1. Import the manifest into the central Rainbow administration
2. Assign a manifest to users:
   - via the admin web (Member → Information → custo-manifest)
   - via CSV
   - via LDAP connector: map the `selectedManifestName` field to the matching LDAP attribute
3. The Rainbow client automatically downloads the manifest at startup:
   - The setup's `/Custom` option is **ignored**
   - The Import/Export entry in Settings is **hidden** from the user

### 11.4 Setup CLI

> **⚠ Obsolete procedure** — prefer the **administrator deployment** (§11.3), which takes priority over this older mode and provides centralized management. This CLI mode is kept for backward compatibility with legacy Desktop integrations.

When launching Rainbow setup:
```
RainbowSetup.exe /Custom=C:\path\to\manifest.json
```
Note: `/Custom` also hides user Import/Export.

---

## 12. Security (S170)

### 12.1 Standard web mechanisms

Extensions are executed by the Rainbow Web app (even when embedded inside Desktop). Standard web protections apply:

- **CSP** (Content-Security-Policy) — Rainbow can only load a page or call an API if the domain is whitelisted
- **CORS** (Cross-Origin) — the REST server must explicitly accept Rainbow as an origin
- **LNA** (Local Network Access) — access to local machines/servers may be denied by the browser
- **Remote-side CSP** — the server can refuse to be embedded inside a Rainbow frame

### 12.2 Trusted domains (new in S170)

#### What it controls

Every URL referenced in a manifest (REST call or iframe embed) must have its **origin** declared as trusted in the Rainbow console. This applies to:

- `command.url` on all extension points (REST calls, file browsing)
- `command.url` on `on-main-window-actions` (web app embedded in the frame)
- `adaptiveCardSubmitUrl`
- `urlConfig` (widget configuration URL)

The declaration is **company-wide**: it covers all manifests deployed in the company and all users.

> **`popout: true` exception** — when `on-main-window-actions` uses `popout: true`, the URL opens in a **dedicated browser window**, not inside the Rainbow frame. The trusted-domain check is **disabled** in that case: the browser's native security applies and Rainbow does not enforce its own CSP for that URL.

> **SSO / OAuth flows** — if the embedded web application triggers an authentication flow (SSO, OAuth, SAML…), the identity provider typically lives on a **different domain** than the application itself (e.g. `login.microsoftonline.com`, `accounts.google.com`, an internal IdP…). Rainbow will attempt to load those redirect URLs inside the same frame, so **every domain involved in the authentication flow must also be declared as trusted** — not only the application's own origin. Failing to declare the IdP domain results in a blank frame at the login step, even though the application URL itself is correctly whitelisted.

#### Where to configure

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

Add one entry per origin. Each entry must follow the format:

```
<protocol>://<domain>[:<port>]
```

| Part | Rules |
|---|---|
| `protocol` | `https` or `http` — **mandatory** |
| `domain` | Exact hostname or wildcard (`*.example.com`) |
| `port` | Optional. Omit for standard ports (443 for https, 80 for http). |
| Trailing `/` | **Not allowed** — the entry is rejected or does not match if it ends with `/` |

#### Protocol constraints (HTTP / HTTPS)

Declaring an origin as trusted is **not enough**: the browser additionally enforces its own rules on the protocol. The Rainbow Web application is served over **HTTPS**, therefore:

- **`http://` is only accepted for `localhost` / `127.0.0.1` (loopback).** Any other HTTP origin (LAN IP, machine name, public domain) is **blocked by the browser** (*mixed content* rule), even if the entry is correctly declared in the console. An entry like `http://192.168.1.100:3300` is accepted as a format but the REST call will silently fail at runtime.
- **`https://` requires a valid server certificate.** The certificate must be issued by a **trusted authority** (public CA, or an enterprise CA installed on the machine) and match the hostname. A **self-signed, expired or wrong-name** certificate is refused by the browser: the REST call fails and an embedded frame stays **blank**, with no error message inside Rainbow.

> **In short**: HTTPS with a valid certificate everywhere, except `localhost`/`127.0.0.1` where HTTP is tolerated (useful for local development only).

#### Valid examples

| Entry | Matches |
|---|---|
| `https://crm.example.com` | `https://crm.example.com/any/path` |
| `https://crm.example.com:8443` | `https://crm.example.com:8443/any/path` |
| `https://*.example.com` | `https://crm.example.com`, `https://api.example.com`, … |
| `http://localhost:3300` | Local development server — the only case where HTTP is accepted at runtime |

#### Invalid examples

| Entry | Problem |
|---|---|
| `crm.example.com` | Missing protocol |
| `https://crm.example.com/` | Trailing slash — rejected |
| `https://crm.example.com/api` | Path not allowed — declare the origin only |
| `http://192.168.1.100:3300` | Format accepted, but **blocked at runtime** — HTTP not allowed outside `localhost` (mixed content) |
| `https://` with a self-signed certificate | Rejected by the browser — untrusted certificate |

#### Behavior when a domain is not declared

| Situation | Effect |
|---|---|
| Manifest loaded by the client | **Warning shown to the user** — the manifest contains untrusted domains |
| REST call (`commandType: "rest"`) | Call blocked by the browser (CSP / CORS) — no popup, no error message inside Rainbow |
| Frame (`on-main-window-actions`) | The frame is shown but the page is **blank** (or displays a browser security error) |

> **⚠ The warning appears at manifest load time, before any extension is triggered.** If the user dismisses the warning, extensions pointing to undeclared domains will silently fail at runtime.

### 12.3 CORS

Even if a domain is declared as trusted in Rainbow, the **browser** independently enforces CORS. The REST server must return:

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

The exact value of `Access-Control-Allow-Origin` depends on the Rainbow platform. Use the browser developer tools (Network tab) to identify the `Origin` header sent by Rainbow on the blocked request. Alternatively, use the wildcard:

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

> **Wildcard limitation** — incompatible with browser credentials (`withCredentials: true`, session cookies). For Rainbow extensions passing a token via the manifest `header` field (e.g. `Authorization: Bearer …`), the wildcard works because Rainbow sends the token as a standard HTTP header. For cookie-based authentication, declare the Rainbow origin explicitly and add `Access-Control-Allow-Credentials: true`.

> **Breaking change** — a manifest that worked before S170 may break if the REST server does not return CORS headers. No error is shown inside Rainbow — the call silently fails.

### 12.4 Local Network Access (LNA)

If the REST server runs on a **local or private network** (e.g. `https://192.168.1.100:8443`), Chrome and Edge enforce the **Private Network Access** policy.

> **HTTP blocked upstream** — a local server over HTTP (e.g. `http://192.168.1.100:3300`) is already blocked by the *mixed content* rule (see §12.2) **before** LNA comes into play. In practice LNA therefore only concerns local servers served over **HTTPS** (or the `localhost` exception).

> **Rainbow Desktop is not affected** — only Rainbow Web is subject to browser LNA rules.

> **Browsers affected** — LNA is only enforced by **Chrome and Edge (Chromium-based)**. Firefox and Safari do not implement this policy.

The browser sends a preflight OPTIONS with `Access-Control-Request-Private-Network: true`. The server must respond with:

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

in addition to standard CORS headers.

> **User permission (Chrome/Edge)** — even with the correct server headers, Chrome may display a permission prompt: *"Allow [site] to access resources on your local network?"*. The user must explicitly grant this permission. It can also be managed at `chrome://settings/content/privateNetworkDevices`.

### 12.5 Embedded application security

When `on-main-window-actions` loads a URL in the Rainbow frame, the target application may refuse to be embedded via server-side headers:

| Header | Typical value | Effect |
|---|---|---|
| `X-Frame-Options` | `DENY` or `SAMEORIGIN` | Browser refuses to render the page in the iframe — blank frame |
| `Content-Security-Policy` | `frame-ancestors 'self'` or `'none'` | Same effect, modern mechanism |

This is independent of the trusted-domain declaration — a declared domain can still refuse iframe embedding.

**Fix:** configure the application to allow the Rainbow origin in `frame-ancestors`, or switch to `popout: true` on `on-main-window-actions`.

> **SSO / OAuth flows** — the identity provider typically sets `X-Frame-Options: DENY` for security reasons. In that case SSO cannot complete inside the iframe regardless of domain declarations. Use `popout: true`.

### 12.6 Special case of local execution

`commandType: "file"` (`.exe` or local script execution) **is not controlled by these mechanisms**. To forbid this type of extension at the enterprise level: prevent the user from loading a manifest, and deploy only via the Rainbow cloud.

---

## 13. Best practices

### 13.1 Building

1. **Start from a template** exported by Rainbow Desktop, remove unneeded EPs
2. Perform a **local import** to validate syntax before central deployment
3. Make sure all references are **portable** (no path hard-coded to the developer's machine)
4. For local resources: systematically use `${custo.path}\…` + ZIP
5. Test on **Web** and **Desktop** (unless the EP is Desktop-exclusive)

### 13.2 Security

- Declare **all** target REST domains in the Rainbow console before deployment
- Check the REST server's **CORS headers** (`Access-Control-Allow-Origin`, `Access-Control-Allow-Methods`)
- Always use **HTTPS with a valid certificate** (not self-signed) — HTTP is only accepted for `localhost`/`127.0.0.1` (see §12.2)
- For REST servers on a **local/private network** (served over HTTPS): add `Access-Control-Allow-Private-Network: true` — Chrome/Edge enforce LNA (see §12.4)
- **Never** put a secret in clear text inside the manifest (it is downloaded by every client)
- For embedded apps refusing iframe embedding: use `popout: true` or configure `frame-ancestors` on the target app (see §12.5)

### 13.3 Variables

- Only use the variables documented for the EP — unsupported variables are silently empty
- For regex: double the `\` in JSON (`\\+33` for `\+33`)
- Keep correlators under **32 characters**

### 13.4 Adaptive Cards

- Prefer the pattern "Template in manifest + Data via REST": lets you modify data on the server side without redeploying the manifest
- Use `${variable}` in the template and provide the values in the content
- `Action.Submit` sends the entire `data` object of the action

---

## 14. Validation and debugging

A **custo-manifest validator** is available on the ALE side to check:
- manifest structure (`version`, `jsonType`, `extension-points`)
- field-by-field compliance per EP
- presence of mandatory icons
- Rainbow variables allowed for the EP
- `${object.attribute}` syntax (vs `$(object.attribute)` or `$[object.attribute]`)
- absolute paths vs `${custo.path}` resources
- `commandType` / `method` / `bodyParameters` / `header` / `responseType` compatibility

It also offers automatic fixes (adding a missing icon, moving misplaced fields back to root or under `command`, removing unsupported fields, converting absolute paths into resources).

---

## 15. Version history

| Version | Key additions |
|---|---|
| **S156** | `on-outgoing-pbx-call-actions` event · Admin mass provisioning · makecall correlator · Multi-extensions (up to 3) |
| **S161** | Custo-manifest partially supported on WEB · `contact` variable (card info) |
| **S170** | Custom widget extension (free widget area) · **Full** custo-manifest on Web and Desktop · REST hardening (trusted domains + CORS) |
| **S179** | `on-conversation-tab-actions` extension (custom tab in a conversation detail, P2P or conference — `scope`) · `linkJsonField` (hyperlink to the business app/CRM for the caller) |
| **S183** | `redirectUrl` *(preview beta)* — on the call events and the buttons, opens a browser window on a URL computed from the JSON response of a REST call (`${response}`) · `devicesSupported` / `defaultDevicesSupported` *(preview beta)* — target clients of an item (web, desktop, mobile, teams); first Mobile step on `on-main-window-actions` · `markdownTemplate` *(preview beta)* — Markdown template filled with the Rainbow variables and the JSON response of a REST call, on the EPs that display Markdown |

---

---

*Document generated from the S170 presentation (April 2026) and the Rainbow custo-manifest functional specification. For any correction or addition, contact the Rainbow Product Management team.*
