> For the complete documentation index, see [llms.txt](https://docs.userdesk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.userdesk.io/api/send-a-message.md).

# Send a message

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 %}