Website Community Tutorials Get started

Messages

Messages

You can use the API to get the message information.

The Message model

KeyTypeDescription

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

POST 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

NameTypeDescription

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

NameTypeDescription

Authorization

string

authorization token. Basic Auth or JWT

Content-Type

string

use "application/json" value

Request Body

NameTypeDescription

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

 {
      "_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
   }

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 and microlanguage example

  • 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

GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages

Fetches the messages by his or her request_id

Path Parameters

NameTypeDescription

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

NameTypeDescription

Authorization

string

authorization token. Basic Auth or JWT

[
   {
      "_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
   },
  ...
]

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

GET https://api.tiledesk.com/v3/:project_id/requests/:request_id/messages/:message_id

Fetche the message by his or her id

Path Parameters

NameTypeDescription

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

NameTypeDescription

Authorization

string

authorization token. Basic Auth or JWT

   {
      "_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
   }

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

POST 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

NameTypeDescription

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

NameTypeDescription

Authorization

string

authorization token. Basic Auth or JWT

Content-Type

string

use "application/json" value

Request Body

NameTypeDescription

text

string

the message text

attributes

object

it's the message custom attributes. Example: attributes = {"custom_attribute1": "value1"}. You can also use 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 }

 {
      "_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
   }

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
PreviousLeadsNextActivities

Last updated