# 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="https://2762017608-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWsuD6nsscVhXqYf6UuRj%2Fuploads%2FwJjTro5dUMsfqFVFKwnX%2FUntitled.png?alt=media&#x26;token=37ea233a-9b73-4e34-accf-c19258f23ead" 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.