Messaging APIs in practice

3 minutes reading time • last modified 12/05/2019

If you're not sure how to use our Messaging APIs, this tutorial will guide you through the process of sending a sample request. We'll cover all necessary aspects including authorization, the request format, as well as recommended tools. To demonstrate the process, we'll show you how to get chat summaries using the Agent Chat Web API.

In short, there are 3 main steps:

  1. Creating an app in Developer Console

  2. Acquiring an access token

  3. Sending a request

Getting started

Before you start, make sure you have acess to the LiveChat Admin or Owner account. If you don't have an account yet, take a minute to sign up for free. Apart from that, you'll also need:

  • an application in Developer Console
  • correct scopes for the selected method
  • an access token with the chosen scopes
  • any tool that will allow you to send requests (Postman, terminal, etc.)

When you already know what you need, let's find out how to get it!

Step 1 Creating an app in Developer Console

Start by logging in to Developer Console and create a new server-side app.

LiveChat New App

To use any method from the Agent Chat, Customer Chat, and Configuration API, your app needs to contain an Authorization building block. This is where you'll configure authorization. Server-side apps come with such a block by default, so we can skipp adding it and go straight to configuration.

Go to the Authorization building block and fill in the Redirect URI whitelist field. Redirect URI is the address of your app that will receive the access token in a URL. Using only this address one can acquire a token.

LiveChat Developer Console

You also need to choose the right scopes to be able to use the method. All methods require certain scopes. For get_chat_summaries, you'll need chats--all:ro and chats--access:ro, and chats--my:ro. You can check out method details in our API documentation.

LiveChat Developer Console

When it's all set, we can proceed with token generation. Make sure to have your Client Id and Redirect URI at hand.

Step 2 Acquiring the access token

Start by pasting your Client Id and Redirect URI in the following request:

https://accounts.livechatinc.com/
?response_type=token
&client_id=<Client_Id_from_Developer_Console>
&redirect_uri=<Redirect_URI_from_Developer_console>

Given that your Client Id is 0805e283233042b37f460ed8fbf22160 and Redirect URI is https://www.livechatinc.com/, this is how your request will look:

https://accounts.livechatinc.com/
?response_type=token
&client_id=0805e283233042b37f460ed8fbf22160
&redirect_uri=https://www.livechatinc.com/

Paste your request in the browser, click Enter, and copy the returned response. Make sure you're logged in to the exact same LiveChat account that was used to create the app in Developer Console. Otherwise, you'll be asked to log in first.

LiveChat request

Your access token will be returned in a long string:

LiveChat response

It contains lots of information, but you need only the part between access_token= and &expires_in:

https://www.livechatinc.com/
#access_token=dal%3AMpubEGdISJCCiFelap3Qtg
&expires_in=28800
...

If you ever get a token that contains %3A, change it to : (a colon). Normally, URL encoding replaces : with %3A. In that case, our token is the following:

dal:MpubEGdISJCCiFelap3Qtg

Managed to get your token? Great! You can now use it to authorize the request sent via Agent Chat API and Configuration API. Keep in mind the token is temporary and will expire in 8 hours due to security reasons.

It's worth remembering that the token you got doesn't belong to an agent. It's the token of your app - that's why you specify the client_id in the request. It's the same in case of tokens acquired for the Customer API. Your application uses its own token for making requests on behalf of an agent or a customer to access certain resources. By the way, everything you need to know about authorization can be found in this document, so keep this source for future reference.

Step 3 Sending the request via Postman

Once you have the token, we're ready to send the actual request. To do that, you can use e.g. terminal, but Postman is our recommendation.

Let's start with our request URL:

POST https://api.livechatinc.com/v3.1/agent/action/get_chats_summary

After that, we can head to the Authorization tab:

LiveChat Postman Authorization

Then, go to Headers and add Content-Type with value application/json:

LiveChat Postman Headers

Last step before sending the request is filling in Body with parameters. In case of get_chats_summary, you can send a basic request without specifying any parameters, like this:

{}

LiveChat Postman Body

You could, however, filter chat summaries or look for them on a particular page. For more details on possible parameters, refer to our docs.

Finally, hit Send button and wait for your response:

LiveChat Postman Response

Questions?

And that would be about it! We hope you managed to successfully send the request. You can use your access token for other methods from the Agent Chat and Configuration APIs. Remember that you cannot use the same token for Customer Chat API. Instead, use the token you have for creating a customer, and acquire a new one. In case of doubts, make sure to check out our documentation. You can always reach out to us at developers@livechatinc.com.