## class: `WyMessengerButton`, `wy-messenger-button`

The Weavy Messenger button component renders a Messenger button complete with a realtime badge for the number of unread conversations. When clicked, the button opens a built in overlay displaying the full [`<wy-messenger>`](./wy-messenger) component for multiple one-to-one conversations, group chats or agent conversations.

The Messenger displays a list of all conversations with possibility to pin, star and mark conversations as read.
Each conversation item displays an avatar, the participants or the room name as title, a line with the latest message.
It also indicates if the conversation is read/unread and if anyone in the conversation is typing.

The list has a search in the top and can open a modal for creating new conversations where the user can search for other people or agents to create private chats or chat rooms.

When a user clicks a conversation item, the conversation is loaded.
The conversation can show rich messages with markdown formatting including code syntax highlight.
Messages can have uploaded images, attached files and cloud files with full browser preview of 100+ formats.
Polls, video meetings, rich link embeds, tags and mentions can be used in messages.
Users can react with predefined emojis to each message.

Read receipts indicate which messages that has been sent and read.
The online presence for users is indicated both in the conversation list as well as in the conversation.

Typing indicators are shown when other users are typing in a conversation.

New messages are indicated as new when received.

For chat rooms, the name and avatar for the chat room can be edited. Members can be added or removed from the chat room.

The editor features markdown preview, including code syntax highlighting.
It has buttons for adding polls, video meetings, images, files and cloud files.
Mentions brings up a user selector.
Drafts are automatically saved for each conversation.

The Messenger button component can optionally be configured in *agent mode*, by defining the `agent` property, to only show conversations with a given [AI agent](https://www.weavy.com/docs/learn/integrations/agents).
In agent mode, the create conversation button instantly creates a new conversation with the agent when clicked, instead of opening a create conversation modal.

> Complement this with the [`<wy-notification-toasts>`](./wy-notification-toasts) component to also get realtime *in-app notifications* or *browser notifications* when new messages arrive.

\*\* Component layout \*\*

The button is displayed as a clickable icon that acts as a button.
The default size of the button is the icon size `1.5rem`/`24px` together with the set `--wy-padding` (which defaults to `0.5rem`/`8px`) on every side of the icon, which makes a total of `2.5rem`/`40px` per default.

The openable Messenger renders in a drawer overlay on the right side in the [top layer](https://developer.mozilla.org/en-US/docs/Glossary/Top_layer).
That means that the Messenger does not occupy any visual layout space where it's placed in the DOM, it only renders in the top layer.
The drawer can be maximized by the user to get more visual space for the Messenger.

You can add additional styling using *CSS Custom Properties* and *CSS Shadow Parts* and further customization using *slots*.

**Used sub components:**

*   [`<wy-badge>`](./components/ui/wy-badge)
*   [`<wy-button>`](./components/ui/wy-button)
*   [`<wy-conversation>`](./components/wy-conversation)
*   [`<wy-conversation-header>`](./components/wy-conversation-header)
*   [`<wy-conversation-list>`](./components/wy-conversation-list)
*   [`<wy-conversation-new>`](./components/wy-conversation-new)
*   [`<wy-context-data-progress>`](./components/wy-context-data)
*   [`<wy-empty>`](./components/wy-empty)
*   [`<wy-icon>`](./components/ui/wy-icon)
*   [`<wy-overlay>`](./components/wy-overlay)
*   [`<wy-titlebar>`](./components/wy-titlebar)

### Examples

<figure class="example"><figcaption>Messenger button with openable Messenger overlay</figcaption>

Displays a button with a badge that tracks unread conversations and can open a side drawer overlay with the Messenger on click.

```html
<wy-messenger-button></wy-messenger-button>
```

</figure>

<figure class="example"><figcaption>Messenger button component in agent mode</figcaption>

Display a button that opens a Messenger in agent mode. Also, show a dot instead of a count when there are unread notifications.

```html
<wy-messenger-button agent="assistant" badge="dot"></wy-messenger-button>
```

</figure>

### Fields

| Name             | Type                                                                       | Default            | Description                                                                                                            | Inherited From     |
| ---------------- | -------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `overlay`        | `"modal" \| "sheet" \| "drawer" \| "full" \| "none"`                       | `"drawer"`         | Overlay appearance used for the conversation list.                                                                     |                    |
| `badge`          | `"count" \| "compact" \| "dot" \| "none"`                                  | `"compact"`        | Badge appearance variant.                                                                                              |                    |
| `badgePosition`  | `"inline" \| "top-right" \| "bottom-right" \| "bottom-left" \| "top-left"` | `"top-right"`      | Badge position relative to the messenger button.                                                                       |                    |
| `agent`          | `string \| undefined`                                                      |                    | Agent uid filter. When set, conversations are limited to the agent chat.                                               | WeavyTypeComponent |
| `unread`         | `number`                                                                   |                    | Current unread conversation count.                                                                                     |                    |
| `instructions`   | `string \| undefined`                                                      |                    | Optional agent instructions appended to submitted messages.                                                            |                    |
| `placeholder`    | `string \| undefined`                                                      |                    | Placeholder text for the message editor.                                                                               |                    |
| `conversationId` | `number \| null \| undefined`                                              | `null`             | Active conversation id.                                                                                                |                    |
| `link`           | `LinkType \| undefined`                                                    |                    | Any provided link that should be loaded, shown and highlighted.                                                        | WeavyTypeComponent |
| `features`       | `string \| undefined`                                                      |                    | Config for enabling/disabling specific features in the weavy component.&#xA;Prefix a feature with minus to disable it. | WeavyTypeComponent |
| `contextualData` | `string \| undefined`                                                      |                    | Contextual data for agents to reference. Provide descriptive data for optimal results.&#xA;&#xA;### Examples           | WeavyTypeComponent |
| `annotations`    | `AnnotationsAppearanceType`                                                | `"buttons-inline"` | Appearance of annotations.                                                                                             | WeavyTypeComponent |
| `enterToSend`    | `EnterToSend`                                                              | `"auto"`           | Enter-to-send keymap in the editor. \`"modifier"\` is \`Enter\` combined with \`Ctrl\` or \`Cmd\`.                     | WeavyTypeComponent |
| `reactions`      | `string`                                                                   | `"😍 😎 😉 😜 👍"` | A space separated string of available reaction emojis in unicode.                                                      | WeavyTypeComponent |
| `weavy`          | `WeavyType \| undefined`                                                   |                    | The consumed weavy context.                                                                                            | WeavyComponent     |
| `contextId`      | `ContextIdType`                                                            |                    | Contextual guid that is unique for the client context.                                                                 | WeavyComponent     |
| `user`           | `UserType \| undefined`                                                    |                    | The current user.                                                                                                      | WeavyComponent     |

### Methods

| Name                 | Description                                                                                     | Parameters                                 | Return                    | Inherited From |
| -------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------- | -------------- |
| `createConversation` | Creates a new conversation.&#xA;&#xA;- When in agent mode, a conversation is created instantly. | `members: (number\|string)[] \| undefined` |                           |                |
| `selectMembers`      | Opens the select member dialog to let the user select members for creating a conversation.      |                                            |                           |                |
| `whenUser`           | Resolves when current user data is available.                                                   |                                            | `Promise<UserType>`       | WeavyComponent |
| `whenWeavy`          | Resolves when a weavy context is available.                                                     |                                            | `Promise<WeavyType>`      | WeavyComponent |
| `whenReady`          | Resolves when the component has rendered first time.                                            |                                            | `Promise<WeavyComponent>` | WeavyComponent |

### Events

| Name               | Type                      | Description                                                                         | Inherited From |
| ------------------ | ------------------------- | ----------------------------------------------------------------------------------- | -------------- |
| `wy-action`        | `WyActionEventType`       | Emitted when a conversation is created or an action is performed on a conversation. |                |
| `wy-preview-open`  | `WyPreviewOpenEventType`  | Fired when a preview overlay is about to open.                                      |                |
| `wy-preview-close` | `WyPreviewCloseEventType` | Fired when a preview overlay is closed.                                             |                |
| `wy-unread`        | `WyUnreadEventType`       | Emitted when the number of unread notifications change.                             |                |
| `ready`            | `CustomEvent`             | When the component has rendered.                                                    | WeavyComponent |

### Attributes

| Name             | Field          | Inherited From     |
| ---------------- | -------------- | ------------------ |
| `overlay`        | overlay        |                    |
| `badge`          | badge          |                    |
| `badgePosition`  | badgePosition  |                    |
| `agent`          | agent          | WeavyTypeComponent |
| `instructions`   | instructions   |                    |
| `placeholder`    | placeholder    |                    |
| `conversationId` | conversationId |                    |
| `link`           | link           | WeavyTypeComponent |
| `features`       | features       | WeavyTypeComponent |
| `contextualData` | contextualData | WeavyTypeComponent |
| `annotations`    | annotations    | WeavyTypeComponent |
| `enterToSend`    | enterToSend    | WeavyTypeComponent |
| `reactions`      | reactions      | WeavyTypeComponent |

### CSS Parts

| Name                             | Description                                                    |
| -------------------------------- | -------------------------------------------------------------- |
| `wy-messenger-overlay-container` | Container for the Messenger within the overlay.                |
| `wy-messenger-layout`            | Outermost messenger layout wrapper inside the overlay.         |
| `wy-messenger-overlay-container` | Container that positions the messenger content in the overlay. |
| `wy-scroll-y`                    | Scrollable surface used by list and conversation sections.     |
| `wy-messenger-conversation-list` | Container for conversation list.                               |
| `wy-messenger-conversation`      | Container for the active conversation.                         |
| `wy-close-conversation`          | Wrapper for the close-conversation icon and badge.             |

### Slots

| Name               | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `header`           | Header content rendered at the top of the conversation list overlay. |
| `title`            | Title content displayed within the overlay header.                   |
| `actions`          | Buttons placed in the top right of the conversation list.            |
| `conversation-new` | Custom content for the new-conversation button.                      |

<details><summary>Private API</summary>

### Fields

| Name                         | Privacy   | Type                                                               | Default                                                                                                                   | Description                                        | Inherited From     |
| ---------------------------- | --------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------ |
| `componentTypes`             | protected | `AppTypeGuid[]`                                                    | `[AppTypeGuid.ChatRoom, AppTypeGuid.PrivateChat]`                                                                         | Conversation types included in the messenger list. | WeavyTypeComponent |
| `visibilityElement`          | protected | `Element \| undefined`                                             |                                                                                                                           | Check visibility on the Messenger                  | WeavyTypeComponent |
| `#data`                      | private   | `ContextDataType[] \| undefined`                                   |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#annotations`               | private   | `WeavyComponentSettingProps["annotations"] \| undefined`           |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#enterToSend`               | private   | `EnterToSend \| undefined`                                         |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#reactions`                 | private   | `WeavyComponentSettingProps["reactions"] \| undefined`             |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#resolveContextDataBlobs`   | private   | `(blobs: ContextDataBlobsType) => void \| undefined`               |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenContextDataBlobs`      | private   |                                                                    | `new Promise<ContextDataBlobsType>((r) => { this.#resolveContextDataBlobs = r; })`                                        |                                                    | WeavyTypeComponent |
| `#resolveComponentFeatures`  | private   | `(componentFeatures: ComponentFeaturePolicy) => void \| undefined` |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenComponentFeatures`     | private   |                                                                    | `new Promise<ComponentFeaturePolicy>((r) => { this.#resolveComponentFeatures = r; })`                                     |                                                    | WeavyTypeComponent |
| `#resolveLink`               | private   | `(link: LinkType) => void \| undefined`                            |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenLink`                  | private   |                                                                    | `new Promise<LinkType>((r) => { this.#resolveLink = r; })`                                                                |                                                    | WeavyTypeComponent |
| `#resolveSettings`           | private   | `(settings: WeavyComponentSettingsType) => void \| undefined`      |                                                                                                                           |                                                    | WeavyTypeComponent |
| `#whenSettings`              | private   |                                                                    | `new Promise<WeavyComponentSettingsType>((r) => { this.#resolveSettings = r; })`                                          |                                                    | WeavyTypeComponent |
| `#contextDataRefs`           | private   | `Map<ContextDataType, DataRefType>`                                | `new Map()`                                                                                                               |                                                    | WeavyTypeComponent |
| `#uploadContextDataMutation` | private   |                                                                    | `new MutationController<BlobType, Error, MutateFileProps, FileMutationContextType>(this)`                                 |                                                    | WeavyTypeComponent |
| `#mutatingContextData`       | private   |                                                                    | `new MutationStateController< BlobType \| FileType \| EmbedType, Error, MutateFileProps, FileMutationContextType >(this)` |                                                    | WeavyTypeComponent |
| `#resolveContextId`          | private   | `(contextId: ContextIdType) => void \| undefined`                  |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenContextId`             | private   |                                                                    | `new Promise<ContextIdType>((r) => { this.#resolveContextId = r; })`                                                      |                                                    | WeavyComponent     |
| `#resolveUser`               | private   | `(user: UserType) => void \| undefined`                            |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenUser`                  | private   |                                                                    | `new Promise<UserType>((r) => { this.#resolveUser = r; })`                                                                |                                                    | WeavyComponent     |
| `#resolveWeavy`              | private   | `(weavy: WeavyType) => void \| undefined`                          |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenWeavy`                 | private   |                                                                    | `new Promise<WeavyType>((r) => { this.#resolveWeavy = r; })`                                                              |                                                    | WeavyComponent     |
| `#resolveReady`              | private   | `(component: WeavyComponent) => void \| undefined`                 |                                                                                                                           |                                                    | WeavyComponent     |
| `#whenReady`                 | private   |                                                                    | `new Promise<WeavyComponent>((r) => { this.#resolveReady = r; })`                                                         |                                                    | WeavyComponent     |
| `#userQuery`                 | private   |                                                                    | `new QueryController<UserType>(this)`                                                                                     |                                                    | WeavyComponent     |

</details>

<hr/>

## Exports

| Kind                        | Name                  | Declaration       | Module                     | Package |
| --------------------------- | --------------------- | ----------------- | -------------------------- | ------- |
| `js`                        | `WyMessengerButton`   | WyMessengerButton | lib/wy-messenger-button.ts |         |
| `custom-element-definition` | `wy-messenger-button` | WyMessengerButton | lib/wy-messenger-button.ts |         |
