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


---

# 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://docs.userdesk.io/api/send-a-message.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.