# Welcome to Userdesk

## Overview

Userdesk is a live chat support platform that helps you provide timely replies to the users' questions, via AI Chatbots trained on your own data.\
\
With Userdesk, you can import your public website pages, Notion pages, or PDF files to train your AI Chatbot.\
\
With Userdesk, you can monitor the questions of the users, and step into the live chat conversation, or via email, to provide further support.


# What we do

## Video overview

Got 2 minutes? Check out a video overview of our product:

{% embed url="<https://www.loom.com/share/827f463ec02f41159aca700e9597fd1c?sid=3248e4ca-d54f-46d2-9f5f-82ea293e19b0>" %}


# Training data


# Sitemaps

A sitemap is a file where you provide information about the pages, videos, and other files on your site, and the relationships between them. Search engines like Google read this file to crawl your site more efficiently.&#x20;

Using a sitemap is the most precise and reliable way to inform Userdesk about all the pages present on your website.<br>

A sitemap is usually available at `/sitemap.xml`, check if your website has one.

***

See the integrations for:

* [Shopify Stores](/product-guides/training-data/sitemaps/shopify-store)
* [Gitbook](/product-guides/training-data/sitemaps/gitbook)


# Shopify Store

Easily import and train the Chatbot using your Shopify Store

The easiest way to train an AI Chatbot on your Shopify Store in Userdesk, is to use the Sitemap import feature.

{% embed url="<https://www.loom.com/share/a1eb2e373f0b48f680e3d09642862a10?sid=5dc0ced0-61ad-479b-8d57-507e737395c1>" %}

* Go to [Sitemaps](https://www.userdesk.io/sitemaps)
* Click on **Add Shopify Store**
* Type the URL of your Shopify Store website
* Click on **Add Shopify Store**

Userdesk will automatically retrieve the pages of your store.

You can now select a Chatbot and train it on your Shopify Store content (products, blog, pages and so on).

{% hint style="info" %}
Discover how easy it is to show the Order Status to your customers, using the [Userdesk Chat widget](/product-guides/add-the-chatbot-widget-to-your-website/shopify).
{% endhint %}


# Gitbook

Import and train your Chatbot on a Gitbook website

The easiest way to import your Gitbook website is to follow these steps:

{% embed url="<https://www.loom.com/share/b9a493e0bdc04443a8707f44cf76f9b2>" fullWidth="false" %}

* Go to Sitemaps
* Click **on Add Gitbook**
* Type the URL of your Gitbook website
* Click on **Add Gitbook**

Once done, pick up a chatbot to train.

Select the previously loaded Gitbook website URL, and click on **Train**.


# Chatbot configuration

There are several configurations you can apply to your AI Chatbot widget.

{% content-ref url="/pages/oIyVLvefV14D51Ej1nzV" %}
[Welcome message](/product-guides/chatbot-configuration/welcome-message)
{% endcontent-ref %}

{% content-ref url="/pages/nRqWEroPyRklMpVfXHiE" %}
[Escalate to human](/product-guides/chatbot-configuration/escalate-to-human)
{% endcontent-ref %}

{% content-ref url="/pages/XCrq4VnI7xv8bDLq9g2U" %}
[Missing response message](/product-guides/chatbot-configuration/missing-response-message)
{% endcontent-ref %}


# Welcome message

When a user opens the Web Chatbot widget, you can show a predefined welcome message.

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

To configure it, go to your [Chatbot page](https://userdesk.io).\
Click on **Widget,** and update the Welcome message field.

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

{% hint style="info" %}
Important: remember to click on the **Save** button at the bottom of the page to save your changes.
{% endhint %}


# Escalate to human

Sometimes your users need to contact humans to ask specific questions.

You can configure your AI Chatbot to show a button to escalate the conversation to a human.\
\
This is the final result:

{% embed url="<https://www.loom.com/share/bf8a394a7aac4882a745efd1c531ef99?sid=6ccf3f6d-5863-41f6-8b71-c44bf7a6c076>" %}

When a user submits a request, you will receive an email with **contact details**, the whole conversation between the user and the AI Chatbot, and a link to the conversation (the Open conversation link at the bottom of the email).

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

### How to enable Escalate to human

To create an Escalate to human action, you need to access your [Chatbot configuration](https://userdesk.io/home) in Userdesk.

Click on the name of the **Chatbot** you want to configure on the left sidebar, click on **Widget** and activate **Escalate to human**.

You can configure all the labels you see in the widget so that you can adjust the tone of voice, or translate the labels in a language different than English.

You can configure:

* Request support button
* Title of the form
* Description of the form
* Confirmation button
* Deny button
* Thank you message
* A set of emails to send the contact request to
* Ask Name label
* Ask Email label
* Ask Phone label

{% hint style="info" %}
Important: remember to click the **Save** button at the bottom of the page to save your changes.
{% endhint %}

### How to integrate an external ticketing system

Most of you will use Userdesk to reply to customer requests (you can invite an unlimited number of support agents), but in case you still prefer to use an external platform, configure **Support emails** with the unified inbox email address of your ticketing system (like Zendesk).

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


# Missing response message

We know how important it is for you to nurture the visitors of your website.\
\
A knowledge base sometimes can be incomplete, and your users don't get the exact answer to their questions, or they need personalized support (about their own ticket, order, and so on).\
\
That's why a Chatbot can be configured with a Missing response message.\
\
Here's the final result:

{% embed url="<https://www.loom.com/share/e08e8684dd884ceda3fad4db2907a365?sid=57174976-361c-4581-8a08-69dc6be32557>" fullWidth="false" %}
Missing response message user experience
{% endembed %}

When the user submits the **Missing response form**, you receive an email with all the details and the full conversation the user had with the AI Chatbot for context.

<figure><img src="/files/FPq8L3xSczIq2uwJtPuM" alt=""><figcaption><p>Email you'll receive</p></figcaption></figure>

### How to configure the Missing response message for your Chatbot

Log in to Userdesk, and click on your Chatbot name on the left sidebar.

Go to Widget and enable **Missing response message.**

You can customize your message (and change language also), the label for Name, Email, and Phone, and enable / disable each one of those fields.

{% embed url="<https://www.loom.com/share/149f449f64c24821b1bd6514465b4ffb?sid=6ccde408-aa24-483c-8326-e84135a7ad7e>" %}
Configure the Missing response message
{% endembed %}

Your **Missing response message** is configured 🎉

Remember that you can chat live with your users in the [Messages](https://www.userdesk.io/messages) section of Userdesk 🙌


# Add the Chatbot widget to your website

The Web Chatbot widget is the best way to allow your users to ask questions about your product / service / community to the AI Chatbot.\
\
After you've created your AI Chatbot, you need to embed it on your website.

Here's the user experience of the Web Chatbot widget:

{% embed url="<https://www.loom.com/share/ea969ddd1eaa42d78d90cb95d934d762?sid=8c06124b-bfde-4830-b660-1c310be41c50>" fullWidth="false" %}

Follow the guides to embed the Web Chatbot widget on your website:

* [WordPress](/product-guides/add-the-chatbot-widget-to-your-website/wordpress)
* [Shopify](/product-guides/add-the-chatbot-widget-to-your-website/shopify)
* [Webflow](/product-guides/add-the-chatbot-widget-to-your-website/webflow)
* [Wix](/product-guides/add-the-chatbot-widget-to-your-website/wix)
* [Any website](/product-guides/add-the-chatbot-widget-to-your-website/any-website)


# WordPress

Add the Web Chatbot widget to your WordPress website

After you have customized your live chat, you will now learn how to install the Userdesk Chatbot into your WordPress site to give you the ability to chat directly with website visitors in real time.

First, you will need to **log in to your WordPress settings** and then **add a plugin** to install the Userdesk Chatbot code into your site.

<div align="center" data-full-width="false"><img src="https://chative.io/en/docs/assets/images/add-plugins-to-wordpress-2e1f065d099289c7aa9e8b817072d6c8.png" alt="Add plugins to Wordpress"></div>

There are many plugins that you can use and here are some plugins that we think you could consider:

* [Code Snippets](https://wordpress.org/plugins/code-snippets/)
* [Custom CSS and JavaScript.](https://wordpress.org/plugins/custom-css-and-javascript/)
* [Insert Headers and Footers](https://wordpress.org/plugins/insert-headers-and-footers/)
* [Code Embed](https://wordpress.org/plugins/simple-embed-code/#description)
* [Scripts n Styles](https://wordpress.org/plugins/scripts-n-styles/)
* [Simple Custom CSS and JS](https://wordpress.org/plugins/custom-css-js/)

**Note:** The above plugins are our recommendations but you can always choose another one [here](https://wordpress.org/plugins/)

We will use the plugin [Simple Custom CSS and JS](https://wordpress.org/plugins/custom-css-js/) for this setup example. And after installing the plugin, please follow these steps:

**Step 1**: Go to **Plugins** section > Search Simple Custom CSS and JS > Click **Settings**.

![Install plugins to Wordpress](https://chative.io/en/docs/assets/images/install-plugins-to-wordpress-5cbacd24af79a88cec8458785ce4a477.png)

**Step 2**: Click **Add HTML Code** button.

**Step 3: Go back to Userdesk and copy the Chatbot embed code that you want to install by going to CHATBOTS >** Choose the Chatbot **> Embed.**[**​**](https://chative.io/en/docs/add-livechat-to-wordpress#step-3-go-back-to-chativeio-system-and-copy-the-live-chat-code-that-you-want-to-install-by-going-tochannels-choose-the-channel-installation)

**Step 4**: Copy the Chatbot embed code in the **Install the Chat widget on your website** section.

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

**Step 5**: Go to WordPress plugins and click on **Settings** for **Simple Custom CSS and JS**.

<figure><img src="/files/54zU9v643LlB7xJCYTpp" alt=""><figcaption></figcaption></figure>

**Step 6**: paste the code copied in **Step 4**.

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

**Step 7**: Save the process by clicking the **Publish** button on the right corner.

Now, the Chatbot widget will be available to your WordPress website visitors 🎉

If you have any issues, or you need to support another platform, feel free to [reach out to us](mailto:undefined).


# Shopify

Add an AI Chatbot to your store in less than 5 minutes

Providing timely responses to your eCommerce website is key to gaining trust and making more sales online.

You can embed the Userdesk AI Chatbot to your Shopify store, to reply to the questions of your users, even on your products!

## Train the AI Chatbot on your store

All Shopify stores automatically generate a `sitemap.xml` file that contains links to all your products, primary product images, pages, collections, and blog posts.

You can find your sitemap in the root directory of your Shopify store's domains, such as `johns-apparel.com/sitemap.xml`.

Add the [sitemap URL to Userdesk](https://www.userdesk.io/sitemaps) and train your Chatbot on it. The AI will retrieve the information of your products, and automatically reply to the questions of your visitors.

## Orders status

The Chatbot widget of Userdesk provides a special integration with your Shopify store.

It automatically retrieves the status of the orders, so that they are available to your users in the support chat.

{% embed url="<https://www.loom.com/share/a5e0fc5eddd346be9bfa58dbb0d8f80d?sid=4c969525-3636-46b2-a6f5-c960152cf0af>" %}
Shopify store integration
{% endembed %}

## How to add the AI Chatbot bubble to your e-commerce store website

To add the AI Chatbot bubble widget to your Shopify store follow these instructions:

* Open the [Shopify Admin panel](https://admin.shopify.com/store)
* Select your store
* Click on **Online Store**
* Click on **Themes**
* Click on the **Customize button** on your current theme
* Click on the three dots at the top of the page and click **Edit code**

<figure><img src="/files/9dvAd11fa1BJrmwFBzMC" alt=""><figcaption></figcaption></figure>

Now you need to find a theme file that is used on every page, usually, it is called `index.liquid`

Click on the file name and paste this code.

```
<script 
	async 
	src="https://d3kno6bpmj270m.cloudfront.net/widget/userdesk.js" 
	data-userdesk="your_chatbot_id">
</script>

<script>
    window.userdeskShopifyCustomer = { "has_account": {{ customer.has_account }}, "email": "{{ customer.email }}"};
    window.userdeskOrders = [];
      {% for order in customer.orders -%}
        userdeskOrders.push({ 
          "order_status_url": "{{order.order_status_url}}",
          "fulfillment_status_label": "{{order.fulfillment_status_label}}",
          "order_name": "{{order.name}}",
          "total_price": "{{ order.total_price }}",
          "items_size": {{order.line_items.size}},
          "line_items": [
            {% for line_item in order.line_items -%}
            {
              "tracking_company": "{{line_item.fulfillment.tracking_company}}",
              "tracking_number": "{{line_item.fulfillment.tracking_number}}",
              "tracking_url": "{{line_item.fulfillment.tracking_url}}",
              "item_count": "{{line_item.fulfillment.item_count}}",
              "product_description": "{{line_item.product.description}}",
              "product_title": "{{line_item.product.title}}",
              "featured_image": "{{line_item.product.featured_image | img_url: '120x' }}",
              "product_images": [
                {% for image in line_item.product.images -%}
                  {
                    "preview_image": "{{image.preview_image | img_url: '120x' }}",
                    "src": "{{image.src  | img_url: '120x' }}",
                    "aspect_ratio": "{{image.aspect_ratio}}"
                  }{%- if forloop.last == false -%},{%- endif -%}
                {%- endfor %}
              ],
              "url": "{{line_item.url}}",
              "title": "{{line_item.title}}"
            }{%- if forloop.last == false -%},{%- endif -%}
            {%- endfor %}
          ]
        });
      {%- endfor %}
</script>
```

{% hint style="info" %}
Remember to replace `your_chatbot_id` with the ID of your Chatbot. You can take it from the [Embed section](https://userdes.io/home) of your Chatbot on Userdesk.
{% endhint %}

Finally, click on **Save**\
\
Your Shopify store is now configured with an AI Chatbot 🎉\
\
If you have any issues adding Userdesk to your Shopify Store, feel free to reach out to us at <support@userdesk.io>


# Webflow

Add live chat to your Webflow in less than 2 minutes

All you need to do is **copy the Userdesk Chatbot code and paste it into your website source code**.

**Step 1** Go to [Userdesk](https://userdesk.io/home) and copy the Embed Chatbot code that you want to install by going to **CHATBOTS** > *Choose the Chatbot* > **Embed.**

**Step 2** Copy the Chatbot code under the section **Install the Chat widget on your website** by clicking on the copy icon

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

**Step 3** Go to **Webflow**

**Step 5** Visit **Site settings** > **Custom code** tab

**Step 6** Paste the Chat code in the **Head code** section

**Step 7** Click **Save changes**

\
You'll now be able to see the Chatbot widget on your Webflow website 🎉

If you have any issues, or you need to support another platform, feel free to send an email to <support@userdesk.io>


# Wix

Add the Web AI Chatbot widget to your Wix website

To embed the Chatbot widget on Wix you need to retrieve the Chatbot embed code.

**Go to Userdesk and copy the Chatbot embed code that you want to install by going to CHATBOTS >** Choose the Chatbot **> Embed.**[**​**](https://chative.io/en/docs/add-livechat-to-wordpress#step-3-go-back-to-chativeio-system-and-copy-the-live-chat-code-that-you-want-to-install-by-going-tochannels-choose-the-channel-installation)

Copy the Chatbot embed code in the **Install the Chat widget on your website** section.

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

And follow the official guide of Wix to add it to your website\
<https://support.wix.com/en/article/embedding-custom-code-on-your-site>

If you have any issues, or you need to support another platform, feel free to [reach out to us](mailto:undefined).


# Notion pages

How to embed a chatbot into your Notion pages

With this feature, you'll be able to embed an AI Chatbot into your Notion pages, so that your teams can take advantage of the content discovery.

Notion allows you to embed links, using the **Embed** block.

To embed a Userdesk AI Chatbot into a Notion page follow these steps:

* go to Userdesk, select your chatbot, go to **Widget**, click on the share icon, and click on **Chatbot standalone**, copy the URL of the opened page

{% embed url="<https://www.loom.com/share/8ec36a0ede0f44d79c3ca369f0a0741c?sid=5d0e3374-5d83-4987-a208-23eafd3ded74>" %}
Get AI Chatbot Standalone link
{% endembed %}

* go to Notion, open a page, and type `/embed` click on the Embed block option, and paste the Chatbot standalone URL

{% embed url="<https://www.loom.com/share/d3d16def25684ad69d6ba18cdf33a308?sid=e482c197-d29a-4e9f-9f90-7ad394b58e27>" %}
Embed AI Chatbot in Notion Page
{% endembed %}

The AI Chatbot should be visible now and your Notion workspace members can ask questions to it 🎉


# Any Website

Add live chat to your website

All you need to do is **copy the Userdesk Chatbot code and paste it into your website source code**.

For more detail on how to process these steps, please follow the guideline below:

**Step 1**: Go to Userdesk and copy the Embed Chatbot code that you want to install by going to **CHATBOTS** > Choose the Chatbot > **Embed.**

**Step 2**: Copy the Chatbot code under the section **Install the Chat widget on your website**

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

**Step 3**: Open the source code of your website and paste the copied code right below the `<body>` tag\
\
**Step 4**: Deploy the changes to your website\
\
You'll now be able to see the Chatbot widget on your website 🎉

If you have any issues, or you need to support another platform, feel free to send an email to <support@userdesk.io>


# Slack integration

With Userdesk, you can integrate an AI Chatbot right into your Slack workspace.\
\
This is particularly useful if you have a community, or your team members need to quickly find the answers to their questions.

By integrating Userdesk into Slack, all the members of the Slack workspace will get a special command \`/userdesk ask \[question]\` to get an answer to a question from your AI Chatbot

To install Userdesk for Slack go to [this page](https://www.userdesk.io/userdesk-for-slack) and click on the button **Add to Slack.**

Confirm the installation by clicking **Allow.**

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

Slack will automatically open, and you'll be on the Home tab of Userdesk for Slack.

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

Go to the Messages tab, you will receive a message like this

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

Click on the **Click here** link, it will redirect you to Userdesk.\
\
If you are not logged in, login into Userdesk, and click the "Click here" link again.

{% hint style="info" %}
You need to have at least one AI Chatbot created in Userdesk to use the Slack integration.
{% endhint %}

If everything was correct, you can close the browser tab and return to Slack.

Click on the **Select Active Chatbot** dropdown and select your Chatbot from the list.\
Finally, click on the **Submit** button.

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

Your AI Chatbot is now linked and enabled on your Slack workspace!\
\
Use the \`/userdesk ask \[question]\` command to ask anything to your AI Chatbot.

<div align="center"><figure><img src="/files/kb8qdpgHd5CYdTfwXV5V" alt=""><figcaption></figcaption></figure></div>

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

You're ready to give extra power to your community or team!


# JavaScript Widget

Embed and control the JavaScript widget

With Userdesk you can embed a JavaScript Widget on your website, and a chat bubble will appear on your website.

This widget exposes a global JavaScript object called `Userdesk` and you can execute some advanced actions.

## Set the user name

Set the current user's name, which is useful if the person is logged in to your website, and you want to see the name in the **Messages** section.

```javascript
Userdesk.setName('John Doe')
```

## Set user email

Set the current user's email, which is useful if the person is logged in to your website, and you want to see the email in the Messages section and be able to send them emails when they are not online.

```javascript
Userdesk.setEmail('john@doe.com')
```

## Open the widget

```javascript
Userdesk.openWidget()
```

## Close the widget

```javascript
Userdesk.closeWidget()
```

## Hide the widget

Completely hides the widget from the page.

```javascript
Userdesk.hideWidget()
```

## Show the widget

```javascript
Userdesk.showWidget()
```

## Set dark mode

It programmatically switches the widget to dark mode. It is useful if you have a dark mode selector on your website.\
Otherwise, the widget automatically takes the color mode of the user system.

```javascript
Userdesk.setDarkMode()
```

## Set light mode

```javascript
Userdesk.setLightMode()
```

## Escalate to human callback

Userdesk allows you to define an Escalate to Human button, via the Widget settings. It also provides a flow to ask for user details and receive an email.

But you can also define a custom callback to execute your JavaScript code when the user clicks the button.

For instance, you could close the widget, and open your own contact details form.

To define your callback use:

```javascript
Userdesk.onEscalateToHuman = () => {
    ...your code...
}
```

## Ask questions on behalf of the user

```javascript
Userdesk.askUserQuestion("question")
```


# Customize Widget CSS

Use CSS to customize the look and feel of the widget

{% hint style="info" %}
Available since widget version 1.10.0
{% endhint %}

In order to override the default CSS styles of the Chat bubble widget, the widget exposes a global function `Userdesk.setCustomCSS(<css string>)`.

To globally update the text settings use

```
Userdesk.setCustomCSS(`
  * {
    letter-spacing: 0.05em;
  }
`)
```

To update the settings of the header use

```
Userdesk.setCustomCSS(`
  .userdesk-header {
    letter-spacing: 0.1em;
  }
`)
```

To reset the CSS settings use

```
Userdesk.setCustomCSS(``)
```

{% hint style="info" %}
If you want to update multiple elements, you need to define all the styles.<br>

For instance:

```
Userdesk.setCustomCSS(`
  * {
    letter-spacing: 0.05em;
  }

  .userdesk-header {
    letter-spacing: 0.1em;
  }
`)
```

{% endhint %}

## CSS classes

These are the classes currently present

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

<figure><img src="/files/8rOMEjpGEYYoH3thkYdZ" alt=""><figcaption></figcaption></figure>


# Chat Widget Changelog

## v1.13.0 — 2024-01-25

Added `Userdesk.askUserQuestion`.\
See the [docs page](/product-guides/javascript-widget#ask-questions-on-behalf-of-the-user) for more details.\
\
Added new `escalate-human` prefixed classes to customize the Escalate to Human button.

## v1.10.0 — 2023-10-16

Added `Userdesk.setCustomCSS`\
See the [docs page](/product-guides/customize-widget-css) for more information.

## v1.10.1 — 2023-10-18

Replace `console.error` with `console.debug`.\
This is useful in case you have tools like Sentry in place, Userdesk will not consume your quota.\
At the same time, you can check the browser console to see the errors.\
In the future, we will provide a specific mechanism to intercept remote errors for the Userdesk widget.


# Authentication

To use the Userdesk API it is required to have an API Key.

Creating an API Key is as simple as creating a Chatbot, going to the API section, and creating a new API Key.

{% embed url="<https://www.loom.com/share/47367f36bb634fcf94f8966c7726c758?sid=502658bb-1580-4ff1-b4a3-455d4486e06b>" %}
Create an API Key
{% endembed %}

### Bearer Token Authorization

Every API endpoint needs to be authenticated via the Bearer Token.

It means that every HTTP request has to include this HTTP Header:

```
Authorization: Bearer <your_chatbot_api_key>
```


# Create a conversation

Create a new conversation by making an HTTP POST request

<mark style="color:green;">`POST`</mark> `https://api.userdesk.io/v1/chatbot/:chabot_id/conversation`

Create a new conversation for a specific chatbot.

*The fields marked with <mark style="color:red;">`*`</mark> are mandatory*

#### Headers

| Name                                            | Type   | Description                       |
| ----------------------------------------------- | ------ | --------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<your\_chatbot\_api\_key> |

#### Request Body

| Name      | Type   | Description       |
| --------- | ------ | ----------------- |
| userName  | String | Name of the user  |
| userEmail | String | Email of the user |

{% tabs %}
{% tab title="200: OK Conversation successfully created" %}

```json
{
  "success": true,
  "conversationId": "7bb301ad-e691-4341-8afb-b4407c4ffdf2",
  "response": "Hello, how can I help you?"
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing API Key" %}

{% endtab %}

{% tab title="401: Unauthorized Wrong API Key" %}

{% endtab %}

{% tab title="403: Forbidden Access to this chatbot is denied" %}

{% endtab %}

{% tab title="500: Internal Server Error An error occurred on the server" %}

{% endtab %}
{% endtabs %}

If the request is successful, the response includes the `conversationId` and the first message from the Chatbot, if configured.

```json
{
  "success": true,
  "conversationId": "7bb301ad-e691-4341-8afb-b4407c4ffdf2",
  "response": "Hello, how can I help you?"
}
```


# Send a message

Send a message to your Chatbot and get an AI generated response

This endpoint allows you to send a message to your Chatbot, if you haven’t started a conversation one will be created, and the `conversationId` will be returned.

<mark style="color:green;">`POST`</mark> `https://api.userdesk.io/v1/chatbot/<chatbot_id>/message`

*The fields marked with <mark style="color:red;">`*`</mark> are mandatory*

#### Headers

| Name                                            | Type   | Description                       |
| ----------------------------------------------- | ------ | --------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | Bearer \<your\_chatbot\_api\_key> |

#### Request Body

| Name                                      | Type    | Description                  |
| ----------------------------------------- | ------- | ---------------------------- |
| message<mark style="color:red;">\*</mark> | String  | Your message for the Chatbot |
| stream                                    | Boolean | Enable streaming response    |
| conversationId                            | String  | Conversation id              |
| userName                                  | String  | Name of the user             |
| userEmail                                 | String  | Email of the user            |

{% tabs %}
{% tab title="200: OK Messsage received and response provided" %}

```json
{
  "success": true,
  "conversationId": "ea74ba3d-6645-4a88-92d1-7f78b1f83688",
  "response": "The average distance from the Earth to the Moon is about 238,855 miles (384,400 kilometers)."
}
```

{% endtab %}

{% tab title="401: Unauthorized Missing API Key" %}

{% endtab %}

{% tab title="401: Unauthorized Wrong API Key" %}

{% endtab %}

{% tab title="403: Forbidden Access to this Chatbot is denied" %}

{% endtab %}

{% tab title="500: Internal Server Error An error occurred on the server" %}

{% endtab %}

{% tab title="400: Bad Request The request was malformed or missing required fields" %}

{% endtab %}

{% tab title="400: Bad Request The conversationId is not valid" %}

{% endtab %}
{% endtabs %}

### Continue a conversation

If the field `conversationId` is set to `true` in the request body, the message will be added to the same conversation.

### Streaming responses

If the field `stream` is set to `true` in the request body, the response will be streamed returning partial message deltas.

This allows the implementation of the ChatGPT-like experience, in which the response from the Chatbot is shown progressively. This usually provides a better user experience, as they don't have to wait until the full response is provided.

This is an example of NodeJS code to use the streaming response:

```javascript
const response = await fetch("https://api.userdesk.io/v1/chatbot/123456/message", {
  headers: {
    Authorization: "Bearer 1234567890",
  }
});

// Stream response
if (!response.body) throw new Error("No response body");
const reader = response.body.getReader();

let message = ""
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const text = new TextDecoder("utf-8").decode(value);
  message += text;
  // progressive message
  console.log(message)
}
// message complete
```

{% hint style="success" %}
Interested in Userdesk?

[Create your AI Chatbot today](https://userdek.io)
{% endhint %}