Rest API

Introduction

This article explains how to use Rest API response type in bot. With this thing basically you can integrate any third party API without any coding.

In order to get all working you have to setup two things

Rest API Call

Rest API call building window is build such way that you can execute almost any request you want.

Fields definition for Rest API

Name

Name for your own purposes.

Description

Description for your own purposes.

Host

This should be not changing URL part. To this part always are appended Sub URL part.

Add request

This button ads new request options to this API. You can have as many request as you want. Request name is visible in trigger method choosing dropdown.

Request fields

Name of the request

Visible in method choosing dropdown in trigger.

Method

Just appropriate method type for the request

Sub URL

URL to append to host. It can be one of the replaceable variables.

Params

In Params section you define arguments which should be accessible as GET parameters.

Authorization

If you are using authorization API. You can setup basic authorization methods there.

Headers

These values will be added to header. They are combined like.

<Key>: <value>

Body

Body can be send either as RAW also known as JSON Body or as regular POST parameters.

User parameters

These parameters can be entered directly in bot trigger itself once method is chosen.

If you choose Body Param you can use this variable Location/Key as replaceable variable in your body json content.

{{<Location/Key>}}

If you choose Query or Body Post Param key will be used as post/get parameter directly.

In Rest API

In the trigger it would look like

Output parsing

Output parsing is dedicated to extracting usefull variables from API response.

Name

Name will be visible within option to execute specific trigger based on response.

In the trigger it will be visible here

HTTP status code E.g 200,301,500

For this response to match you can to define expected HTTP status code. It's optional. This way you can separate success response from failed one.

Response Location 1/2/3/4.

If you define success location it will parse response as JSON and will try to extract specified attribute.

Examples of variables extraction

status as location value would return success

{
"status": "success"
}

response:location as location value would return Lithuania

{
"response": {
"location" : "Lithuania"
}
}

items:0:name as location value would return Sub item name

{
"items": [
{
"name" : "Sub item name"
}
]
}

Conditions checking

Sometimes it makes sense to check was something found based on response attribute. So you can define condition to check.

Here we expect that status value would be success.

JSON should look like this

{
"status": "success"
}

Meta msg location.

Here we can extract meta_msg if you provide Live Helper Chat compatible JSON response. Meta message will be used in chosen response trigger [text message] if this trigger does not have any meta message information.

{
"msg": "Standard message text from REST API",
"meta_msg": {
"content": {
"quick_replies": [
{
"type": "button",
"content": {
"name": "Rest API Button",
"payload": "rest_api_button"
}
}
]
}
}
}

In order for rest API to receive these clicks you should also check in trigger Default for unknown button click

tip

Each trigger at the bottom has Show code button. This code is supported only by Execute trigger body response type. If you just want to build trigger and get code for response and reuse it, it's the response type you should use instead.

Replaceable variables

Rest API in value fields you can use these replaceable variables

  • {{msg}} - user message
  • {{msg_clean}} - user message without [file=616_6f13fafc726e119f5a0a3f49221b45f7] in it's body if it's the only content in message.
  • {{msg_url}} - user message will contain links instead of bbcode tags.
  • {{chat_id}} - chat ID
  • {{lhc.nick}} - visitor nick
  • {{lhc.email}} - e-mail
  • {{lhc.department}} - department name
  • {{lhc.dep_id}} - department ID
  • {{ip}} - visitor ip. If you are running background worker this value will be localhost.
  • {{lhc.add.<additional variable key/identifier>}} - these values you are passing additionaly. It's either Field identifier from Start a chat form settings > Custom fields or if you are passing manually it's name attribute.

Example:

If you put Field identifier value as gender in Start a chat form settings > Custom fields. In Rest API Call you can access this field like {{lhc.add.gender}}

  • {{lhc.var.<chat variable key>}} - these values can be set using extensions etc. It's data is taken by json_decode function from chat_variables column value. This column stores JSON as {<key> : <value>,..}. Usually in this column extensions stores their own data.
  • {{media}} - Will hold JSON encoded related files to send message.
[
{
"id": 636,
"size": 10007,
"upload_name": "image.png",
"type": "image/png",
"extension": "png",
"hash": "4bcda854ef4f27e8b4003b42c84f1cb6",
"url": "https://devmysql.livehelperchat.com/file/downloadfile/636/4bcda854ef4f27e8b4003b42c84f1cb6"
}
]

So your JSON body in rest API can look like

{
"msg":{{msg}}, // OR {{msg_clean}}
"query":{{query}},
"media":{{media}}
}

Replaceable variables works only in

  • Params
  • Body

They do not work on Headers section.

Trigger workflow

In trigger once everything is setup it will look like this.

Fields description

  • Rest API - it's our main Rest API Name we are working with
  • Method - it's our Name of the request from Rest API building window.
  • User entered parameter - it's just defined parameter which is coming from Rest API builder window User parameters tab.
  • Execute trigger for [UUID Set] - It's defined output parsing option which we defined in Rest API Output parsing tab.
  • Default trigger to execute - if we did not found any matching output combination this trigger will be executed.
  • Send Rest API Call in the background. - by default Rest API calls are send as soon visitor sends a message, they are happening on same request. This can lead to a problems if Rest API is slow. We can send Rest API calls in the background, but for that you have to be running lhc-php-resque extension. You won't need to code anything just setup extension itself.

Output variables in triggers

Use can use these variables in your text triggers response text.

  • {content_1}
  • {content_2}
  • {content_3}
  • {content_4}
  • {http_code}

Video usage example

Last updated on by Remigijus Kiminas