Sending and receiving messages with Tiledesk APIs

Targets

This tutorial will help you to understand how to send and receive "support messages" between Tiledesk's End Users and Agents using Tiledesk REST APIs and Webhooks.

Steps

1. Signup a user on Tiledesk

2. Anonymous end-user authentication through APIs

3. Sending messages to a conversation

4. Receiving new messages notifications using Webhooks

Signup on Tiledesk

To use Tiledesk APIs is mandatory to signup a new user on our beta environment available on https://panel.tiledesk.com/v3/dashboard

The previous APIs end-point will change as soon as the beta version will be released as Tiledesk v2. This tutorial will be updated accordingly.

After signup please follow the proposed wizard to create your first Tiledesk project.

Get the PROJECT_ID of the created project under Project Settings menu. We will use this later.

Anonymous end-user authentication through APIs

In this tutorial we will authenticate end-users through anonymous authentication (you can find more info on anomymous authentication here).

All APIs in this tutorial will use the following endpoint:

https://api.tiledesk.com/v3/

The previous APIs end-point will change as soon as the beta version will be released as Tiledesk v2. This tutorial will be updated accordingly.

curl -v -X POST -H 'Content-Type:application/json' \
-d '{"id_project":"5e2c35c8f0dbc10017bb3aac", "firstname":"John"}' \
https://api.tiledesk.com/v3/auth/signinAnonymously

This will reply with the JWT token that we'll use to send our first message:

{
   "success":true,
   "token":"JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ....",
   "user":{
      "_id":"fc43a0e1-ba85-404e-9a44-bf0050330898",
      "firstname":"John",
      "id":"fc43a0e1-ba85-404e-9a44-bf0050330898",
      "fullName":"John"
   }
}

Sending messages to a conversation

You can send a message using the Send Message API.

To send a message you need to choose a unique request identifier. A request is an object containing the all the metadata describing the conversation between end-user and support team).

The request identifier must follow the following pattern:

support-group-<UUID>

Please consider that the first message you send to a conversation also creates request and corresponding conversation if they do not exist.

curl -v -X POST -H 'Content-Type:application/json' \
 -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ...." \
 -d '{"text":"hello from anonym user"}' \
 https://api.tiledesk.com/v3/<PROJECT_ID>/requests/support-group-<UUID>/messages

Example with realistic variables instances:

curl -v -X POST -H 'Content-Type:application/json' \
 -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.XYZ...." \
 -d '{"text":"hello my name is John and I need help"}' \
 https://api.tiledesk.com/v3/5e2c35c8f0dbc10017bb3aac/requests/support-group-27df7cbf-3946-4ca4-9b17-dc16114108f8/messages

Looking at the dashboard of your project you will see your first conversation in the Requests panel. The requests are updated in real time, so you don't have to manunally update the Requests' page. If you left unchanged all the default settings, the request will be assigned to you (make sure you are "available", looking in the lower right corner of your profile image in the left menu panel).

The agent (you) can now see the same conversation in the agent chat (first option of the menu panel will open the desktop chat).

Receiving new messages notifications using Webhooks

You can subscribe to the messages events sent to a conversation using Webhooks.

You must first create a subscription to an event that points to a url on your server.

In this case we will subscribe to message creation event on a custom url (/test) on requestcatcher.com, a free, beautiful service to debug your webhooks:

curl -v -X POST -H 'Content-Type:application/json' \
-u [e-mail]:123456 \
-d '{"event":"message.create", "target":"https://tiledesk.requestcatcher.com/test"}' \
https://api.tiledesk.com/v3/5e2c35c8f0dbc10017bb3aac/subscriptions

The subscription endpoint returns:

{
   "secret":"0fd2a8a1-a3e6-443b-9fe5-49b83612cd72",
   "_id":"5e2c6a24f5b11c00175f1705",
   "target":"https://tiledesk.requestcatcher.com/test",
   "event":"message.create",
   "id_project":"5e2c35c8f0dbc10017bb3aac",
   "createdBy":"5e2c357af0dbc10017bb3aa7",
   "createdAt":"2020-01-25T16:17:40.088Z",
   "updatedAt":"2020-01-25T16:17:40.088Z",
   "__v":0
}

Now you are notified for each messages sent to your Tiledesk project. Now, for example, if the agent sends a message to the end user, your webhook endpoint will be notified with the message payload.

This is the webhook notification with the message payload. You can use this notification to create a copy of all messages sent/received in your project, generate new custom events, communicate in real time on other channels etc.

{
   "timestamp":1579969429552,
   "payload":{
      "type":"text",
      "status":200,
      "_id":"5e2c6b958c9612001716bede",
      "sender":"5e2c357af0dbc10017bb3aa7",
      "senderFullname":"demo demo",
      "recipient":"support-group-27df7cbf-3946-4ca4-9b17-dc16114108f10",
      "text":"Hi I'm Rosy. How can help you?",
      "id_project":"5e2c35c8f0dbc10017bb3aac",
      "createdBy":"5e2c357af0dbc10017bb3aa7",
      "metadata":"",
      "attributes":{
         "client":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/76.0.3809.132 Safari/537.36",
         "sourcePage":"https://api.tiledesk.com/v3/chat/index.html",
         "userEmail":"[e-mail]",
         "userFullname":"aaa22 aaa22"
      },
      "createdAt":"2020-01-25T16:23:49.394Z",
      "updatedAt":"2020-01-25T16:23:49.394Z",
      "__v":0,
      "request":{
         ....
      }
   },
   "hook":{
      "_id":"5e2c6a24f5b11c00175f1705",
      "target":"https://tiledesk.requestcatcher.com/test",
      "event":"message.create",
      "id_project":"5e2c35c8f0dbc10017bb3aac",
      "createdBy":"5e2c357af0dbc10017bb3aa7",
      "createdAt":"2020-01-25T16:17:40.088Z",
      "updatedAt":"2020-01-25T16:17:40.088Z",
      "__v":0
   }
}

Do you have feedback on this article? Please send us your feedback writing an email to [e-mail]