# Interop Methods

Source: https://docs.interop.io/adapters/instant-bloomberg/interop-methods/index.html

## Overview

The Instant Bloomberg Adapter registers a set of Interop methods that allow io.Connect apps to interact with the Bloomberg IB Connect API — discover streams, subscribe for real-time messages, send ideas, initiate chats, and more. The Instant Bloomberg Adapter also exposes an Interop stream for monitoring its status.

To invoke a method, use `io.interop.invoke()` with the method name and an arguments object:

```javascript
const methodName = "IO.BBG.IB_Chat.GetStreams";

const result = await io.interop.invoke(methodName);

console.log(result.returned);
// { allStreams: ["stream-1", "stream-2"] }
```

## Streams

Interop methods related to Instant Bloomberg streams.

### IO.BBG.IB_Chat.GetLastMessages

Retrieves cached messages for a stream. Optionally accepts a `backfillId` to return only messages after that point.

The `IO.BBG.IB_Chat.GetLastMessages` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"backfillId"` | `string` | If provided, only messages after this backfill ID are returned. |
| `"streamId"` | `string` | **Required.** The stream ID for which to retrieve messages. |

The `IO.BBG.IB_Chat.GetLastMessages` method returns as a result an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"lastBackfillId"` | `string` | The backfill ID of the last returned message. Can be used for pagination or to resume from this point. |
| `"messages"` | `object[]` | Array of cached stream events. Each object is one of `ContentEvent`, `IdeaDrawerFeedbackEvent`, or `CustomActionFeedbackEvent`, distinguished by the `@type` property. |

### IO.BBG.IB_Chat.GetStatusStream

Pushes service status updates periodically (at the interval configured via `healthCheckInterval`) and on status change.

To subscribe to the stream:

```javascript
const subscription = await io.interop.subscribe("IO.BBG.IB_Chat.GetStatusStream");

subscription.onData((data) => {
    console.log(data.data);
    // { isRunning: true, timestamp: "2026-03-09T12:00:00.000Z" }
});
```

Each status update contains the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"isRunning"` | `boolean` | If `true`, the service is operational and the IB tunnel is live. |
| `"timestamp"` | `Date` | Timestamp of the status update. |

### IO.BBG.IB_Chat.GetStreams

Discovers all visible IB Chat streams.

The `IO.BBG.IB_Chat.GetStreams` method accepts no arguments.

The `IO.BBG.IB_Chat.GetStreams` method returns as a result an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"allStreams"` | `string[]` | List of all visible stream IDs. |

### IO.BBG.IB_Chat.SubscribeToStream

Subscribes to a stream to receive real-time messages. The Instant Bloomberg Adapter uses the `peerId` and `application` properties of the subscriber to manage per-subscriber state.

The `IO.BBG.IB_Chat.SubscribeToStream` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"backfillId"` | `string` | Resume streaming from after this backfill ID. |
| `"correlationId"` | `string` | **Required.** Passed back in every forwarded message for this subscription. |
| `"includeCachedSince"` | `Date` | If provided, cached messages after this timestamp are sent first (with `isCached` set to `true`). |
| `"onMessageApiName"` | `string` | **Required.** Interop method name for receiving forwarded messages. Defaults to `"IO.BBG.IB_Chat.ReceivedMessage"`. |
| `"streamId"` | `string` | **Required.** The stream ID to which to subscribe. |

The `IO.BBG.IB_Chat.SubscribeToStream` method returns `{ success: true }` on success or `{ error }` on failure.

### IO.BBG.IB_Chat.UnsubscribeFromStream

Unsubscribes from a previously subscribed stream.

The `IO.BBG.IB_Chat.UnsubscribeFromStream` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"streamId"` | `string` | **Required.** The stream ID from which to unsubscribe. |

The `IO.BBG.IB_Chat.UnsubscribeFromStream` method returns `{ success: true }` on success or `{ error }` on failure.

## Chat

Methods for initiating conversations and receiving messages.

### IO.BBG.IB_Chat.NewChat

Initiates a new IB Chat conversation. Supports two input modes — a full payload object or flat properties. If both are provided, the payload object takes precedence.

The `IO.BBG.IB_Chat.NewChat` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"message"` | `string` | Message text. Used with flat properties mode. |
| `"payload"` | `object` | Full chat initiation request object. Takes precedence over flat properties. `"rawData"` is accepted as an alias. |
| `"recipientId"` | `number` | Bloomberg UUID of the recipient. Used with flat properties mode. |
| `"roomId"` | `string` | IB Chat room ID to which to send. Used with flat properties mode as an alternative to `"recipientId"`. |
| `"senderId"` | `number` | Bloomberg UUID of the sender. Used with flat properties mode. |

The `"payload"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"chatMessage"` | `object` | Message to include. |
| `"recipients"` | `object[]` | **Required.** Array of recipient identifiers. At least one required. |
| `"sender"` | `object` | **Required.** Sender identity. |
| `"structuredTemplate"` | `object[]` | Structured template elements. |
| `"table"` | `object` | Table data to include. |

The `"chatMessage"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"text"` | `string` | Message text. |

The `"sender"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"uuid"` | `number` | Bloomberg UUID of the sender. |

The `"table"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"json"` | `object` | JSON table data. Contains a `"rows"` array. |

Each object in the `"recipients"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"roomId"` | `string` | IB Chat room ID. Provide either `"uuid"` or `"roomId"`. |
| `"uuid"` | `number` | Bloomberg UUID of the recipient. Provide either `"uuid"` or `"roomId"`. |

The `IO.BBG.IB_Chat.NewChat` method returns as a result an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"externalId"` | `string` | External ID of the created chat. |
| `"recipients"` | `object[]` | Array of recipient identifiers. |

### IO.BBG.IB_Chat.ReceivedMessage

This isn't a method registered by the Instant Bloomberg Adapter — it's the default Interop method name that the Instant Bloomberg Adapter uses to forward stream events to subscribed apps via `io.interop.invoke()`. The method name is configurable per subscriber via the `onMessageApiName` property in `IO.BBG.IB_Chat.SubscribeToStream`.

To receive messages, register a method with the expected name:

```javascript
await io.interop.register("IO.BBG.IB_Chat.ReceivedMessage", (args) => {
    console.log(args);
});
```

Each forwarded message contains the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"correlationId"` | `string` | The correlation ID specified in the subscription. |
| `"error"` | `Error` | Present when the message represents an error or stream shutdown. |
| `"isActive"` | `boolean` | If `true`, the stream is active. |
| `"isCached"` | `boolean` | If `true`, the message was retrieved from cache rather than received in real time. |
| `"message"` | `object` | The actual stream event. One of `ContentEvent`, `IdeaDrawerFeedbackEvent`, or `CustomActionFeedbackEvent`, distinguished by the `@type` property. |
| `"streamId"` | `string` | ID of the stream that produced the event. |
| `"timestamp"` | `string` | ISO 8601 timestamp of when the message was forwarded. |

## IDEA

Methods for posting, replying with, and retracting idea suggestions.

### IO.BBG.IB_Chat.PostUnsolicitedIdea

Posts an unsolicited idea (UIDEA) to a stream. Unlike `IO.BBG.IB_Chat.ReplyWithIdea`, no `eventCorrelationId` is needed. Requires at least one recipient and one suggestion.

The `IO.BBG.IB_Chat.PostUnsolicitedIdea` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"confirmButton"` | `object` | Shorthand for a confirm button. |
| `"customActionButtons"` | `object[]` | Array of custom action buttons. Each item has the same structure as the `"confirmButton"` object. |
| `"declineButton"` | `object` | Shorthand for a decline button. Same structure as the `"confirmButton"` object. |
| `"destinationIds"` | `object[]` | User or room IDs as destination list. |
| `"headerDescription"` | `string` | Idea header description displayed as a tooltip. |
| `"headerTitle"` | `string` | Idea header title. |
| `"ideaHeaderProperties"` | `object` | Full idea header properties object. |
| `"payload"` | `object` | Full UIDEA payload object. Takes precedence over flat properties. `"rawData"` is accepted as an alias. |
| `"recipientUuid"` | `number` | Bloomberg UUID of a single recipient. |
| `"recipients"` | `object[]` | Multiple recipients. At least one recipient is required when using flat properties. |
| `"roomIds"` | `object[]` | Room IDs to which recipients can share the idea. |
| `"streamId"` | `string` | **Required.** The stream ID to which to post the idea. |
| `"suggestionAction"` | `string` | Accepted values: `"VIEW_ONLY"`, `"ORIGINAL_ROOM"`. |
| `"suggestionText"` | `string` | Suggestion message text. |
| `"suggestions"` | `object[]` | Full suggestions array. Overrides `"suggestionText"` and `"suggestionAction"` if provided. |

The `"payload"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"@type"` | `string` | **Required.** Must be `"UIDEA"`. |
| `"destinations"` | `object` | **Required.** Destinations to which recipients can share the idea. |
| `"ideaHeaderProperties"` | `object` | Custom idea header properties. |
| `"recipients"` | `object[]` | **Required.** Array of recipient identifiers. At least one required. |
| `"suggestions"` | `object[]` | **Required.** Array of suggestion objects (1–3). |

The `"confirmButton"`, `"declineButton"`, and `"customActionButtons"` items are objects with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"actionPayload"` | `string` | **Required.** Feedback returned via stream when the button is clicked. |
| `"label"` | `string` | **Required.** Text displayed on the button. |
| `"tooltip"` | `string` | **Required.** Tooltip displayed when hovering on the button. |

The `"ideaHeaderProperties"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"@type"` | `string` | Must be `"IdeaHeaderProperties"`. |
| `"description"` | `string` | **Required.** Additional context displayed as a tooltip for the idea title. |
| `"title"` | `string` | **Required.** Short customized title displayed in the idea header. |

The `"destinations"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"destinationIds"` | `object[]` | User or room IDs as destination list. |
| `"roomIds"` | `object[]` | Room IDs to which recipients can share the idea. |

Each object in the `"destinationIds"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"roomId"` | `string` | IB Chat room ID. Provide either `"uuid"` or `"roomId"`. |
| `"uuid"` | `number` | Bloomberg UUID of the user. Provide either `"uuid"` or `"roomId"`. |

Each object in the `"recipients"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"uuid"` | `number` | Bloomberg UUID of the recipient. |

Each object in the `"roomIds"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"roomId"` | `string` | IB Chat room ID. |

Each object in the `"suggestions"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"action"` | `string` | **Required.** Accepted values: `"VIEW_ONLY"`, `"ORIGINAL_ROOM"`. |
| `"customActionButtons"` | `object[]` | **Required.** Array of custom action button objects. At least one required. |
| `"structuredElements"` | `object[]` | **Required.** Array of structured elements. Each contains `"contentType"` (`"TEXT"` or `"LINK"`), and optionally `"text"`, `"href"`, `"title"`. |
| `"structuredTemplate"` | `object[]` | **Required.** Array of structured template objects. |
| `"text"` | `string` | **Required.** Suggestion text. |
| `"textElements"` | `object[]` | **Required.** Array of text elements. Same structure as `"structuredElements"`. |

### IO.BBG.IB_Chat.ReplyWithIdea

Replies to a stream event with an IDEA suggestion. Supports two input modes — a full payload object or flat properties. If both are provided, the payload object takes precedence.

The `IO.BBG.IB_Chat.ReplyWithIdea` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"confirmButton"` | `object` | Shorthand for a confirm button. |
| `"customActionButtons"` | `object[]` | Array of custom action buttons. Each item has the same structure as the `"confirmButton"` object. |
| `"declineButton"` | `object` | Shorthand for a decline button. Same structure as the `"confirmButton"` object. |
| `"eventCorrelationId"` | `string` | The `eventId` of the received `ContentEvent` to which to reply. Required when using flat properties. |
| `"headerDescription"` | `string` | Idea header description displayed as a tooltip. |
| `"headerTitle"` | `string` | Idea header title. |
| `"ideaHeaderProperties"` | `object` | Full idea header properties object. |
| `"payload"` | `object` | Full IDEA payload object. Takes precedence over flat properties. `"rawData"` is accepted as an alias. |
| `"recipientUuid"` | `number` | Bloomberg UUID of a single recipient. |
| `"recipients"` | `object[]` | Multiple recipients. |
| `"streamId"` | `string` | **Required.** The stream ID to which to post the idea. |
| `"suggestionAction"` | `string` | Accepted values: `"VIEW_ONLY"`, `"ORIGINAL_ROOM"`. |
| `"suggestionText"` | `string` | Suggestion message text. |
| `"suggestions"` | `object[]` | Full suggestions array. Overrides `"suggestionText"` and `"suggestionAction"` if provided. |

The `"payload"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"@type"` | `string` | **Required.** Must be `"IDEA"`. |
| `"eventCorrelationId"` | `string` | **Required.** The `eventId` of the received `ContentEvent` to which to reply. |
| `"ideaHeaderProperties"` | `object` | Custom idea header properties. |
| `"recipients"` | `object[]` | Array of recipient identifiers. |
| `"suggestions"` | `object[]` | **Required.** Array of suggestion objects (max 3). |

The `"confirmButton"`, `"declineButton"`, and `"customActionButtons"` items are objects with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"actionPayload"` | `string` | **Required.** Feedback returned via stream when the button is clicked. |
| `"label"` | `string` | **Required.** Text displayed on the button. |
| `"tooltip"` | `string` | **Required.** Tooltip displayed when hovering on the button. |

The `"ideaHeaderProperties"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"@type"` | `string` | Must be `"IdeaHeaderProperties"`. |
| `"description"` | `string` | **Required.** Additional context displayed as a tooltip for the idea title. |
| `"title"` | `string` | **Required.** Short customized title displayed in the idea header. |

Each object in the `"recipients"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"uuid"` | `number` | Bloomberg UUID of the recipient. |

Each object in the `"suggestions"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"action"` | `string` | **Required.** Accepted values: `"VIEW_ONLY"`, `"ORIGINAL_ROOM"`. |
| `"customActionButtons"` | `object[]` | **Required.** Array of custom action button objects. At least one required. |
| `"structuredElements"` | `object[]` | **Required.** Array of structured elements. Each contains `"contentType"` (`"TEXT"` or `"LINK"`), and optionally `"text"`, `"href"`, `"title"`. |
| `"structuredTemplate"` | `object[]` | **Required.** Array of structured template objects. |
| `"text"` | `string` | **Required.** Suggestion text. |
| `"textElements"` | `object[]` | **Required.** Array of text elements. Same structure as `"structuredElements"`. |

### IO.BBG.IB_Chat.RetractSuggestion

Retracts a previously posted suggestion. Supports two input modes — a full payload object or flat properties. If both are provided, the payload object takes precedence.

The `IO.BBG.IB_Chat.RetractSuggestion` method accepts as an argument an object with the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"payload"` | `object` | Full retract suggestion payload object (with `@type` set to `"RETRACT_SUGGESTION"`). Takes precedence over flat properties. `"rawData"` is accepted as an alias. |
| `"recipientUuid"` | `number` | Single recipient UUID from which to retract. |
| `"recipients"` | `object[]` | Multiple recipients from which to retract. At least one recipient is required. |
| `"streamId"` | `string` | **Required.** The stream ID in which the suggestion was posted. |
| `"suggestionId"` | `string` | Unique identifier of the suggestion to retract. Required when using flat properties. |

The `"payload"` object has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"@type"` | `string` | **Required.** Must be set to `"RETRACT_SUGGESTION"`. |
| `"recipients"` | `object[]` | **Required.** Users from which to retract the suggestion (1–50). |
| `"suggestionId"` | `string` | **Required.** Unique identifier of the suggestion to retract. |

Each object in the `"recipients"` array has the following properties:

| Property | Type | Description |
|----------|------|-------------|
| `"uuid"` | `number` | Bloomberg UUID of the recipient. |