Messaging API

Introduction #

The Querlo messaging API is a REST API designed to integrate Querlo chat workflows with third party clients. Thanks to the API, you’ll be able to start new chat sessions, receive messages from Querlo scripts and send messages, just like you normally would by interacting with the Querlo web client and Querlo multi channel integrations.

Interaction with the API revolves around the concept of chat session, which is the collection of all of the events that happen since the moment of the first interaction with a chat script and the timeout or session closed event. On the Querlo web client, this corresponds to the moment when the user first opens a chat window pointing to a given chat script, and the time when the user closes the web tab, or the session times out if they never closes the tab.

Obtaining an API key #

In order to exchange messages through the Messaging API, you must first obtain a valid API key.

In order to obtain your API key, first select the team you wish to work with, then click on the gear icon:

This will open the settings dialog for your team. Now please select the APIs tab, you’ll be presented with the following screen:

This is where you can setup everything you need in order to build with Querlo Messaging API.

Click the Cycle button near the API Key field to generate an API Key. Please consider a team may only have one valid API key at any given time, so if you change your API Key by clicking the cycle button, the previous API key will be invalidated and must be replaced in any application it might have been in use with.

API Endpoints #

At this time, only one endpoint is available for the fruition of the API.

https://www.querlo.com/api/

Please point all your API calls to this URL.

Setting up a Webhook URL #

This screen is also where you can set your webhook URL. A webhook URL is necessary to receive callbacks from Querlo for incoming messages and more. Please see the appropriate section of the documentation to read more about Querlo Messaging API Webhooks.

[POST] StartSession #

Starts a chat session for a given chat and user. For any given API key, it is only possible to start sessions regarding the chats owned by the team the API key belongs. API clients should specify a client user id they can use to recognize a given user on their platforms, and maintain it consistently. Querlo does not impose any limitation regarding the client user id, and guarantees consistency across multiple sessions. This allows users to pick up their previous chat status (variables and progress) and allows Querlo to track returning users for statistical purposes. Client user ids are always unique within the team identified by the API key.

Request URL:

https://{endpoint}/api/startSession

Request Headers:

Content-Type: application/json

Request Body:

{
    "api_key": "q5D6MuAbImc8lTk0a6E78dS3O1qeK4CG",
    "chat_id": "123", 
    "user_id": "my_user_nr_1" 
}

Response 200:

Session started successfully, returns the session hash:

{
    "session_hash": "LUI9gECZcvZZamM",
    "chat_id": "123"
}

Response 403:

Access to the chat has been denied to the specified Api Key. Please check your Api Key is valid and the specified chat id belongs to a chat within the correct team.

[POST] SendMessage #

Sends a message to the chat engine to further a conversation within a given session.

It is possible to specify a text message or a choice_id. Choice_id represents the 0 based index of the pre-defined answers provided in a multi button/multi choice question structure.

Request URL:

https://{endpoint}/api/sendMessage

Request Headers:

Content-Type: application/json

Request Body:

{
    "api_key": "q5D6MuAbImc8lTk0a6E78dS3O1qeK4CG",
    "session_id": "LUI9gECZcvZamM",
    "text":"my Message",
    "choice_id":0
}

Response 200:

Message accepted:

{
    "session_hash": "LUI9gECZcvZZamM",
    "chat_id": "123"
}

Response 500:

Invalid Api Key/Session hash combination. Please check your Api Key is valid, the session has not timed out / been closed and belongs to the Api Key.

Webhooks #

To receive messages from the Querlo Messaging API, setting up a webhook endpoint is required. Querlo will consider the webhook root as previously set up in the team customization form and append the destination endpoint as needed to route the necessary calls.

[POST] https://{webhook_endpoint}/message #

Receives a new message from a chat script that is currently running as a Querlo Messaging API session.

Response Headers:

Content-Type: application/json

Example format:

{
  "b": {
    "question": "<p>This is the question text<\/p>",
    "track_codes": [],
    "dataType": "text",
    "ls": true,
    "validation_format": "",
    "answers": [
      {
        "txt": "Yes",
        "img": "",
        "txt_ext": "",
        "link": "",
        "choice_id": 0
      },
      {
        "txt": "No",
        "img": "",
        "txt_ext": "",
        "link": "",
        "choice_id": 1
      }
    ],
    "question_id": 135378,
    "questionType": 0,
    "chat_id": 14921,
    "ml": false
  },
  "t": 40
}