Smartify

Sending and receiving messages with Tiledesk APIs

This tutorial will help you 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

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

The APIs endpoint used in this tutorial will change when the beta version is released as Tiledesk v2; the tutorial will be updated accordingly.

After signup, follow the wizard to create your first Tiledesk project and get the PROJECT_ID of the created project under Project Settings. We will use this later.

2

Anonymous end-user authentication through APIs

In this tutorial we will authenticate end-users through anonymous authentication (more info on anonymous authentication: https://developer.tiledesk.com/apis/rest-api/authentication#anonymous-authentication-for-a-user).

All APIs in this tutorial will use the following endpoint:

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

Example request to sign in anonymously:

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

Example response (returns a JWT token to use for subsequent requests):

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

Sending messages to a conversation

You can send a message using the Send Message API: https://developer.tiledesk.com/apis/rest-api/messages#send-a-message

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

The request identifier must follow this pattern:

support-group-

Note: the first message you send to a conversation also creates the request and the corresponding conversation if they do not already exist.

Example request:

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:

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 the conversation in the Requests panel. Requests are updated in real time. If you left unchanged all the default settings, the request will be assigned to you (ensure you are "available" — check 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 opens the desktop chat).

4

Receiving new messages notifications using Webhooks

You can subscribe to message events for a conversation using Webhooks.

First, create a subscription to an event that points to a URL on your server. In this example we subscribe to the message creation event and point the webhook to a custom URL (/test) on requestcatcher.com, a free service to debug webhooks.

Example request to create the subscription:

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

Example subscription endpoint response:

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

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

Example webhook notification payload:

{
   "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":"[email protected]",
         "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
   }
}

You can use these webhook notifications to:

  • create a copy of all messages sent/received in your project,

  • generate new custom events,

  • communicate in real time on other channels, etc.

If you have feedback on this article, please send an email to [email protected].

Previousrest-apiNextwebhooks