# Lynn Javascript API

Lynn provides a JavaScript API to control some of the widget functionalities. This guide will teach you how to use the Javascript API to interact with the widget.

## **Prerequisites**

* [Integrate a widget into the target webpage.](https://www.notion.so/lynn-docs/How-do-I-add-Lynn-to-my-website-620d963e9fda44c5bd61dc3d3f2ddb92)

Once you integrate a widget into a webpage, Lynn attaches a global variable `LynnAPI` to the `window` object. This variable is your gateway to interacting with Lynn programmatically.

## API features

### Detect when Lynn widget is ready to be used (`LynnAPI.onLoad`)

Method signature: `onLoad(callbackFn: () => unknown):void`

Example snippet:

```jsx
LynnAPI.onLoad(handleLynnWidgetLoaded);

function handleLynnWidgetLoaded(){
	// Do stuff
}
```

### Set **conversation metadata (`LynnAPI.setMetadata`)**

Method signature: `setMetadata(key: string, value: unknown):void`

Example snippet:

```jsx
LynnAPI.onload(setupWidget);

function setupWidget(){
	LynnAPI.setMetadata('foo', 'bar');
}
```

Once you set metadata to a conversation, it can be accessed through Lynn’s back office & in handover requests.

<figure><img src="/files/cOnLxOOI9teJK9TFeOkj" alt=""><figcaption></figcaption></figure>

Screenshot showcasing where you can find metadata in a conversation through Lynn’s back-office application

### Remove conversation metadata (`LynnAPI.removeMetadata`)

Method signature: `removeMetadata(key: string):void`

Example snippet:

```jsx
if(somethingHasHappened){
	LynnAPI.removeMetadata('foo');
}
```

### Reset conversation metadata (`LynnAPI.resetMetadata`)

Method signature: `resetMetadata():void`

Example snippet:

```jsx
if(needToResetAllMetadata){
	LynnAPI.resetMetadata();
}
```

This is going to clear all the metadata that had been set.

### Open widget (`LynnAPI.open`)

Method signature: `open():void`

Example snippet:

```jsx
LynnAPI.onlad(() => {
	LynnAPI.open();
});
```

### Close widget (`LynnAPI.close`)

Method signature: `close():void`

Example snippet:

```jsx
if(needToCloseTheWidget){
	LynnAPI.close();
}
```

### **Send chat message (`LynnAPI.sendMessage`)**

Method signature: `sendMessage(text:string):void`

Example snippet:

```jsx
if(err){
	// Open the widget
	LynnAPI.open();

	// Send message
	LynnAPI.sendMessage(`Hey, I'm on page ${pageUrl} and I'm running into ${err.message}. What can I do?`);
}
```

### **Adjusting the Position of the Lynn Widget (`LynnAPI.updateWidgetPositionConfig`)**

Method Signature: \*\*\*\*`updateWidgetPositionConfig(config: { yOffset: number, xOffset: number, zIndex: number }): void`

This method allows you to customize the position and stacking order of the Lynn widget on your page by specifying the vertical offset (**`yOffset`**), horizontal offset (**`xOffset`**), and z-index (**`zIndex`**).

Example snippet:

```jsx
LynnAPI.updateWidgetPositionConfig({
  yOffset: 50, // Vertical offset in pixels
  xOffset: 200, // Horizontal offset in pixels
  zIndex: 100  // Stacking order
});
```

**Function Description**

* **`yOffset`**: The number of pixels to move the widget up from its default position/bottom of the page.
* **`xOffset`**: The number of pixels to move the widget to the right/left from its default position/start or end of the page.
* **`zIndex`**: The CSS z-index property specifies the stack order of the widget. A higher index means the widget will be in front of other elements.

**Notes**

* Ensure that the Lynn API is fully loaded and available before calling this function. You might want to call this function within the **`LynnAPI.onLoad`** callback to ensure the API is ready.
* Adjusting the **`zIndex`** is particularly useful in complex layouts where multiple elements overlap.
* The values for **`yOffset`** and **`xOffset`** are relative to the edge of the page , not the widget's default position.

### **Hiding/Showing the Chat Bubble of the Lynn Widget (`LynnAPI.hideChatBubble` or `LynnAPI.showChatBubble`)**

Method Signature: **`hideChatBubble(): void` or `showChatBubble(): void`**

This method allows you to programmatically hide the chat bubble of the Lynn widget on your page. This can be useful for manage the visibility of the widget under certain conditions.

```jsx
if(needToHideTheWidget){
	LynnAPI.hideChatBubble();
} else {
	LynnAPI.showChatBubble();
}
```

**Note**

* Ensure that the Lynn API is fully loaded and available before calling this function. You might want to call this function within the **`LynnAPI.onLoad`** callback to ensure the API is ready.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://support.lynn.chat/lynn-javascript-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.