# Messages

## Messages

You can use the API to get the message information.

The Message model

| Key            | Type   | Description                                                                                                                   |
| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------- |
| id             | String | The unique identifier for the message which is given by Tiledesk.                                                             |
| sender         | String | A unique identifier of the sender. It can be: the user identifier, a bot identifier or the system user                        |
| senderFullname | String | The sender fullname. It can be: the user fullname, the bot name or an alias                                                   |
| recipient      | String | A unique identifier of the recipient. It can be: the request\_id field (external id) of the request                           |
| status         | Number | The message status: FAILED : -100, SENDING : 0, SENT : 100, DELIVERED : 150, RECEIVED : 200, RETURN\_RECEIPT: 250, SEEN : 300 |
| text           | String | The message text.                                                                                                             |
| type           | String | The message type. Accepted values: text (default), image                                                                      |
| metadata       | Object | The message metadata.                                                                                                         |
| attributes     | Object | The custom attributes which are set for the message.                                                                          |
| createdAt      | String | The time (ISO-8601 date string) when the message was created.                                                                 |
| updatedAt      | String | The time (ISO-8601 date string) when the message was updated.                                                                 |
| createdBy      | String | The unique identifier of the row creator                                                                                      |
| id\_project    | String | The unique identifier of the project                                                                                          |

## Send a message

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages`

Allows to send a message. This method also creates a new conversation (request) if it didn’t exist at the time of the call.

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| request\_id | string | The request identifier. Must follow this pattern 'support-group-UUID'                    |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name         | Type   | Description                                                                                                                                                                                                                                                                                         |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text         | string | the message text                                                                                                                                                                                                                                                                                    |
| departmentid | string | The selected department identifier. Accepted only on the first message.                                                                                                                                                                                                                             |
| sourcePage   | string | The source page of the request. Accepted only on the first message.                                                                                                                                                                                                                                 |
| language     | string | The language of the request. Accepted only on the first message.                                                                                                                                                                                                                                    |
| userAgent    | string | The userAgent string of the request. Accepted only on the first message.                                                                                                                                                                                                                            |
| attributes   | object | it's the message custom attributes. Example: attributes = {"custom\_attribute1": "value1"}. You can also use [attributes](#attributes) to enable advanced features.                                                                                                                                 |
| type         | string | it's the message type. "text" value for textual message and "image" for sending image message(you must set metadata field). Available values: text (default) and image.                                                                                                                             |
| metadata     | object | it's the image properties: src is the absolute source path of the image, width is the image width, height is the image height. Width and height are optional. Example: metadata = { "src": "<https://www.tiledesk.com/wp-content/uploads/2018/03/tiledesk-logo.png>", "width": 200, "height": 200 } |

{% tabs %}
{% tab title="200 " %}

```
 {
      "_id":"5c81593adf767b0017d1aa68",
      "updatedAt":"2019-03-07T17:47:38.411Z",
      "createdAt":"2019-03-07T17:47:38.411Z",
      "sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "senderFullname":"Guest",
      "recipient":"support-group-L_OG76RYhR0XFiMf2PK",
      "text":"hello from api",
      "id_project":"5b55e806c93dde00143163dd",
      "createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "__v":0,
      "status":200
   }
```

{% endtab %}
{% endtabs %}

Example sending text message:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"text":"hello from api"}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages
```

Example sending image:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '{"text":"Alternative text from api", "type":"image", "metadata": {"src": "https://tiledesk.com/tiledesk-logo-x1.png", "width": 200, "height": 200}}' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages
```

## Attributes

When you send a message you can use the following attributes to activate advanced features:

* attributes.clienttimestamp: use this property to force the message timestamp in milliseconds. This parameter is used by the clients (widgets and chat agents) to perform a client side reordering of messages based on the value of the timestamp field. This property doesn’t guarantees the order of arrival, but only the ordering or reordering on the client side.
* attributes.attachment: use this property to set the response additional reply componenst as quick replies, buttons, links etc. (see: <https://developer.tiledesk.com/widget/advanced/widget-json-protocol>)
* attributes.subtype.info: If “true” it hides the message to the end-user channels (Widget, whatsapp, Telegram, Facebook etc.)
* attributes.microlanguage: set this property to true to enable the microlanguage pre-processor. You can find more info here: [Chatbot buttons, images, video](https://docs.tiledesk.com/knowledge-base/response-bot-images-buttons-videos-and-more/) and [microlanguage example](https://developer.tiledesk.com/external-chatbot/buttons-media-actions-more#microlanguage)
* attributes.disableInputMessage: if true it disables the input message, until the next message arrival
* attributes.inputMessagePlaceholder: if set, it modify the default input text placeholder
* attributes.updateUserEmail and attributes.updateUserFullname: If set, the back forward user fullname and email to the widget. Useful if you set user fullname or email in a webhook or external service.

## Advanced features

Tiledesk uses Chat21 as messaging engine. When you send a message to Tiledesk using the REST API, Tiledesk will forward the call to the Chat21 REST API. You can see how the Chat21 REST Api works here: <https://github.com/chat21/chat21-cloud-functions/blob/master/docs/api.md#send-a-message>

You can enable special message features following this paragraph: <https://github.com/chat21/chat21-cloud-functions/blob/master/docs/api.md#message-attributes>

## Get the messages of a request by id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages`

Fetches the messages by his or her request\_id

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| request\_id | string | the request\_id field. It's the external request identifier.                             |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
[
   {
      "_id":"5c81593adf767b0017d1aa68",
      "updatedAt":"2019-03-07T17:47:38.411Z",
      "createdAt":"2019-03-07T17:47:38.411Z",
      "sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "senderFullname":"Guest",
      "recipient":"support-group-L_OG76RYhR0XFiMf2PK",
      "text":"test56",
      "id_project":"5b55e806c93dde00143163dd",
      "createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "__v":0,
      "status":200
   },
   {
      "_id":"5c81593adf767b0017d1aa69",
      "updatedAt":"2019-03-07T17:47:38.625Z",
      "createdAt":"2019-03-07T17:47:38.625Z",
      "sender":"system",
      "senderFullname":"Bot",
      "recipient":"support-group-L_OG76RYhR0XFiMf2PK",
      "text":"La stiamo mettendo in contatto con un operatore. Attenda...",
      "id_project":"5b55e806c93dde00143163dd",
      "createdBy":"system",
      "__v":0,
      "status":200
   },
  ...
]
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-L_OG76RYhR0XFiMf2PK/messages
```

## Get the message by request id and message id

<mark style="color:blue;">`GET`</mark> `https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages/:message_id`

Fetche the message by his or her id

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| request\_id | string | the request\_id field. It's the external request identifier.                             |
| message\_id | string | the message identifier                                                                   |
| project\_id | string | the Project Id is a unique code assigned to your project when you create it in Tiledesk. |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |

{% tabs %}
{% tab title="200 " %}

```
   {
      "_id":"5c81593adf767b0017d1aa68",
      "updatedAt":"2019-03-07T17:47:38.411Z",
      "createdAt":"2019-03-07T17:47:38.411Z",
      "sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "senderFullname":"Guest",
      "recipient":"support-group-L_OG76RYhR0XFiMf2PK",
      "text":"test56",
      "id_project":"5b55e806c93dde00143163dd",
      "createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "__v":0,
      "status":200
   }
```

{% endtab %}
{% endtabs %}

Example:

```
curl -v -X GET -u andrea.leo@f21.it:123456 https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-L_OG76RYhR0XFiMf2PK/messages/5c81593adf767b0017d1aa68
```

## Insert multiple messages

<mark style="color:green;">`POST`</mark> `https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages/multi`

This method should be used for mass importing of messages. For common cases, use Send message REST API

#### Path Parameters

| Name        | Type   | Description                                                                              |
| ----------- | ------ | ---------------------------------------------------------------------------------------- |
| project\_id | string | The project\_id is a unique code assigned to your project when you create it in Tiledesk |
| request\_id | string | The request identifier. Must follow this pattern 'support-group-UUID'                    |

#### Headers

| Name          | Type   | Description                            |
| ------------- | ------ | -------------------------------------- |
| Authorization | string | authorization token. Basic Auth or JWT |
| Content-Type  | string | use "application/json" value           |

#### Request Body

| Name       | Type   | Description                                                                                                                                                                                                                                                                                         |
| ---------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| text       | string | the message text                                                                                                                                                                                                                                                                                    |
| attributes | object | it's the message custom attributes. Example: attributes = {"custom\_attribute1": "value1"}. You can also use [attributes](#attributes) to enable advanced features.                                                                                                                                 |
| type       | string | it's the message type. "text" value for textual message and "image" for sending image message(you must set metadata field). Available values: text (default) and image.                                                                                                                             |
| metadata   | object | it's the image properties: src is the absolute source path of the image, width is the image width, height is the image height. Width and height are optional. Example: metadata = { "src": "<https://www.tiledesk.com/wp-content/uploads/2018/03/tiledesk-logo.png>", "width": 200, "height": 200 } |

{% tabs %}
{% tab title="200 " %}

```
 {
      "_id":"5c81593adf767b0017d1aa68",
      "updatedAt":"2019-03-07T17:47:38.411Z",
      "createdAt":"2019-03-07T17:47:38.411Z",
      "sender":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "senderFullname":"Guest",
      "recipient":"support-group-L_OG76RYhR0XFiMf2PK",
      "text":"hello from api",
      "id_project":"5b55e806c93dde00143163dd",
      "createdBy":"SRbb2PfbSFcgICv9VQBcURZeloh1",
      "__v":0,
      "status":200
   }
```

{% endtab %}
{% endtabs %}

Example of inserting multiple messages:

```
curl -v -X POST -H 'Content-Type: application/json' -u andrea.leo@f21.it:123456  -d '[{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619","text":"1"},{"sender":"bb0d809b-b093-419b-8b48-11a192cc3619", "text":"2"}]' https://api.tiledesk.com/v3/5b55e806c93dde00143163dd/requests/support-group-1234/messages/multi
```


---

# 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://developer.tiledesk.com/apis/rest-api/messages.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.