Introduction

Welcome to the KeyReply Developer Documentation V1! Our API and webhooks enable you to build custom solutions on top of the KeyReply platform.

Key features available in V1:

Integrate your existing livechat system with the KeyReply platform
Create middleware services to connect external livechat systems with KeyReply
Generate customized reports from the KeyReply platform

Prerequisites

To access the API, you must first enable the Developer menu in Settings -> Developer. Here, you can configure access for incoming requests and outgoing event hooks.

Getting Started

To integrate with the KeyReply API, you'll need:

Enable the Developer menu in Settings -> Developer
Provide your development team with:
- This API documentation
- API key from Settings -> Developer
- KeyReply dashboard URL for testing and debugging

API Base URL

The base URL for all KeyReply API endpoints is:

[server_url]/api/developer/v1/[endpoint_name]

Example:

https://sandbox.keyreply.com/server/api/developer/v1/sessions

If the Developer menu is not enabled, the API will return a 403 status with this message:

{
  "errors": "Incoming request is disabled"
}

Authentication

Incoming Requests

Replace x-api-key with your API key from the dashboard.

# Basic request
curl "api_endpoint_here" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

# Request with idempotency key
curl "api_endpoint_here" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -H "Idempotency-Key: kZmFzZ"

Invalid API key will result in a 401 status:

{
  "message": "Unauthorized"
}

Duplicate requests in process will return a 409 status:

{
  "message": "Request already processed"
}

Rate limit exceeded will return a 423 status:

{
  "message": "You have requested too many times. Please wait a moment."
}

API Key Authentication

KeyReply uses API keys to authenticate requests. Include your API key in the header of all requests to the server, as shown in the examples above.

Administrators can manage API keys through the dashboard. Each integration partner should be assigned their own unique API key.

2-add-api-keys

Idempotent Requests

Our API supports idempotency to prevent duplicate operations when retrying failed requests. This is particularly useful when network issues occur and you don't receive a response. For example, if a message send request fails due to network error, you can safely retry using the same idempotency key to ensure the message is sent exactly once.

To make an idempotent request, add the Idempotency-Key: <key> header to your request.

Rate Limit

For security, each API key is limited to 600 requests per minute. Exceeding this limit will result in an error response.

Outgoing Requests

When receiving webhook events from KeyReply, implement these security measures:

Validate that requests originate from KeyReply servers
Verify that request payloads match the documented format

Virtual Assistant (VA)

Use this endpoint for your visitors to send messages to our Virtual Assistant (VA) and get responses back. You can parse the response according to your application's needs. The response from VA is configured through your dashboard settings (e.g., content node setting, trigger setting, FAQ setting).

Please note that sending messages to VA during an active live chat session is not supported yet. This feature will be updated shortly.

All requests for VA begin with /virtual-assistant

Send Message

curl -X POST [API_URL]/virtual-assistant/message
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{
    "sender": {
      "id": "613b5897-062e-40ba-bf49-ebda02a95475",
    },
    "recipient": {
      "id": "app.keyreply.com"
    },
    "message": {
      "text": "hi",
      "isPreview": false,
      "id": "ckrg7bcrt00043h6cxm2to7ot"
    }
  }
  '

Successful request will return the following JSON structure. You should parse the content inside response according to your application needs. Every response might contain multiple contents from VA.

{
  "response": [
    {
      "content": [
        {
          "text": "Welcome to KeyReply. How can I help you today?",
          "buttons": [
            {
              "text": "Service Information",
              "type": "event",
              "event": "goto",
              "data": "appointment booking_choose department"
            },
            {
              "text": "Talk to an agent",
              "type": "event",
              "event": "goto",
              "data": "singpass_login"
            },
            {
              "text": "Appointment Booking",
              "type": "event",
              "event": "goto",
              "data": "appointment booking_welcome message"
            }
          ]
        }
      ],
      "listStyle": null,
      "quickReplies": [
        {
          "text": "Myinfo",
          "event": "goto",
          "data": "singpass_myinfo"
        },
        {
          "text": "Login",
          "event": "goto",
          "data": "singpass_login"
        }
      ],
      "options": {
        "disableTextInput": false,
        "feedbackCollectionMode": "default",
        "nodeId": "conversation_start"
      },
      "meta": {
        "hideSuggestions": false,
        "lang": "default"
      }
    }
  ]
}

Send message to virtual assistant and get a response based on settings configured on your KeyReply dashboard.

Example use cases:

You have a chatbot application and want visitors to get responses from VA.
You have your own webchat and want visitors to get responses from VA.

HTTP Request

POST [API_URL]/virtual-assistant/message

Body

Parameter	Mandatory	Description	Example Value
sender.id	required	unique visitor id from your application	VISITOR007
recipient.id	required	identifier from your application	jamesbond@yoursystem.com
message.text	required	the chat / text to be send	Hello world!
message.isPreview	optional	whether VA should use preview content (if using maker checker module)	true
message.id	optional	the chat id from your application	ckrg7bcrt00043h6cxm2to7ot

Send Postback Message

curl -X POST [API_URL]/virtual-assistant/message
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{
    "id": "ckrg6vjyo00003h6cpaxlqo9i",
    "sender": {
      "id": "90d2874e-60f3-4568-88f6-4f59120206a6",
      "session_id": "d4020f73-2d0c-409d-8198-4f7b6c350765"
    },
    "recipient": {
      "id": "app.keyreply.com"
    },
    "postback": {
      "event": "goto",
      "data": "conversation_start",
      "isPreview": false,
      "options": {}
    }
  }'

Successful request will return the following JSON structure. You should parse the content inside response according to your application needs. Every response might contain multiple contents from VA.

{
  "response": [
    {
      "content": [
        {
          "text": "Welcome to KeyReply. How can I help you today?",
          "buttons": [
            {
              "text": "Service Information",
              "type": "event",
              "event": "goto",
              "data": "appointment booking_choose department"
            },
            {
              "text": "Talk to an agent",
              "type": "event",
              "event": "goto",
              "data": "singpass_login"
            },
            {
              "text": "Appointment Booking",
              "type": "event",
              "event": "goto",
              "data": "appointment booking_welcome message"
            }
          ]
        }
      ],
      "listStyle": null,
      "quickReplies": [
        {
          "text": "Myinfo",
          "event": "goto",
          "data": "singpass_myinfo"
        },
        {
          "text": "Login",
          "event": "goto",
          "data": "singpass_login"
        }
      ],
      "options": {
        "disableTextInput": false,
        "feedbackCollectionMode": "default",
        "nodeId": "conversation_start"
      },
      "meta": {
        "hideSuggestions": false,
        "lang": "default"
      }
    }
  ]
}

Send postback message to virtual assistant and get a response back. A postback message is a type of request to execute an event. This is typically used after a visitor selects a button or quick reply.

For example, if you want visitors to get greetings from the chatbot, you can request an event "goto" with data "conversational_start". This will make VA respond with "conversational_start" content to your application. If you want visitors to be escalated to live chat, you can request an event "handover_start". This will make VA start the live chat flow and respond with the appropriate content node.

For a full list of events and data, please check your dashboard.

Example use cases:

Your visitor clicks a button and wants to get a response back.
Your visitor wants to execute a certain event from VA.

HTTP Request

POST [API_URL]/virtual-assistant/message

Body

Parameter	Mandatory	Description	Example Value
sender.id	required	unique visitor id from your application	VISITOR007
recipient.id	required	identifier from your application	jamesbond@yoursystem.com
postback.event	required	event to be executed	goto
postback.data	optional	data for the event	conversation_start
postback.isPreview	optional	whether VA should use preview content (if using maker checker module)	true
postback.options	optional	additional options	ckrg7bcrt00043h6cxm2to7ot

Sessions

Sessions are chat session data initiated by visitors to the KeyReply webchat.

All requests for session data begin with /sessions.

Get All Sessions

curl "[API_URL]/sessions?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 2175,
  "results": [
    {
      "id": 45501,
      "sessionId": "d5dfee60-2137-4cb2-b84a-3c3ddc106dc3",
      "stateId": "8a085c67-f8d7-4287-b6e3-e20faff1fdb3",
      "statePartitionKey": "localhost",
      "createdAt": "2022-08-23T05:00:51.466Z",
      "updatedAt": "2022-08-23T05:01:39.923Z",
      "expireAt": "2022-08-23T05:01:37.916Z"
    },
    {
      "id": 45502,
      "sessionId": "5baf2927-48be-43dd-96a9-efb6114fad7c",
      "stateId": "26846d9b-2e50-47f2-a7d7-f28483eef07b",
      "statePartitionKey": "localhost",
      "createdAt": "2022-08-23T05:01:40.397Z",
      "updatedAt": "2022-08-23T05:04:32.715Z",
      "expireAt": "2022-08-23T05:04:30.713Z"
    }
  ]
}

This endpoint retrieves all sessions based on specified conditions.

Example use cases:

Generate chat session reports
List chat sessions for a specific visitor

HTTP Request

GET [API_URL]/sessions

Query Parameters

Parameter	Mandatory	Default	Description
fromDate	required		ISO 8601 format (ex: 2022-08-01)
toDate	required		ISO 8601 format (ex: 2022-08-31)
sort	optional	desc	"asc" (ascending) or "desc" (descending)
limit	optional	100	max number of data that will be returned
offset	optional	0	offset of data that will be returned
stateId	optional		filter sessions by state id

Get a Specific Session

curl "[API_URL]/sessions/d5dfee60-2137-4cb2-b84a-3c3ddc106dc3" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "id": 45501,
  "sessionId": "d5dfee60-2137-4cb2-b84a-3c3ddc106dc3",
  "stateId": "8a085c67-f8d7-4287-b6e3-e20faff1fdb3",
  "statePartitionKey": "localhost",
  "createdAt": "2022-08-23T05:00:51.466Z",
  "updatedAt": "2022-08-23T05:01:39.923Z",
  "expireAt": "2022-08-23T05:01:37.916Z"
}

This endpoint retrieves a specific session.

Example use cases:

Find a single session data

HTTP Request

GET [API_URL]/session/:sessionId

End / Renew Chat Session

curl -X POST [API_URL]/sessions/720e983c-9e51-48a2-9765-812bc46dfaf8/localhost/end
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "id": 49418,
  "sessionId": "720e983c-9e51-48a2-9765-812bc46dfaf8",
  "stateId": "f7f44a01-29ed-409e-9730-5eb3251be4c0",
  "statePartitionKey": "localhost",
  "createdAt": "2022-09-23T06:09:38.460Z",
  "updatedAt": "2022-09-23T06:09:38.539Z",
  "expireAt": "2023-03-22T06:09:38.539Z"
}

Use this endpoint to force end a visitor's chat session and create a new one.

Example use cases:

Force a user's session to expire after certain conditions on your side

HTTP Request

POST [API_URL]/sessions/:sessionId/:partitionKey

Path Parameters

Parameter	Example	Description
sessionId	720e983c-9e51-48a2-9765-812bc46dfaf8	The unique ID of the session
partitionKey	localhost	The partition key for session

Visitor

Visitor data consists of profile information about visitors, similar to what is shown on the "Visitors" tab. This data includes all information captured from content nodes or during chat sessions.

The data displayed via the visitor API is configurable.

4-manage-visitor-data

All requests for visitor data should begin with /states.

If you are using a statically typed language, please be aware that the data returned from this API might have different fields for each request, depending on what users have configured on the Dashboard.

Get All Visitors

curl "[API_URL]/states?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 15,
  "results": [
    {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "localhost",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "userQueryTopic": "department A"
    }
  ]
}

This endpoint retrieves all states based on specified conditions, similar to what is shown on KeyReply Dashboard -> Visitors tab.

Example use cases:

Generate visitor reports

HTTP Request

GET [API_URL]/states

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	max number of data that will be returned	10
offset	optional	0	offset of data that will be returned	10
PartitionKey	optional		filter by PartitionKey	keyreply.com
channel	optional		filter by channel	webchat

Get Specific Visitor

curl "[API_URL]/states/5db0d549-c45a-439d-af6a-ab91aa85eaf0" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
    "RowKey": "5db0d549-c45a-439d-af6a-ab91aa85eaf0",
    "PartitionKey": "localhost",
    "last_modified": "2022-09-21T06:20:14.153Z",
    "date_created": "2022-09-21T04:30:45.472Z",
    "channel": "webchat",
    "entities": "{}",
    "department": "00000000-0000-0000-0000-000000000000",
    "source": "webchat",
    ...
}

This endpoint retrieves a single visitor (state) object.

Example use cases:

Get data for a single visitor

HTTP Request

GET [API_URL]/states/:PartitionKey/:RowKey

Path Parameters

Parameter	Description	Example
PartitionKey	domain / origin of the widget where visitor open the webchat	keyreply.com
RowKey	the rowkey of the visitor	webchat

Update Visitor Data

curl -X POST [API_URL]/localhost/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/private_variables
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"name":"John Doe"}'

Successful request will return the following JSON structure:

{
  "RowKey": "2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e",
  "PartitionKey": "localhost",
  "externalData": {
    "name": "John Doe"
  },
  ... // other visitor's existing data
}

Set visitor data. For security purposes, all of your data will be stored under "externalData".

Example use cases:

Update visitor data with any key/column
Your next content node depends on certain user data (e.g., if user has JWT, then go to content node "X")

HTTP Request

POST [API_URL]/states/:PartitionKey/:RowKey/private_variables

Path Parameters

Parameter	Example	Description
RowKey	2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e	The state RowKey
PartitionKey	localhost	the state PartitionKey

Body

Parameter	Mandatory	Description	Example Value
[key]	required	any { key: value } can be stored into visitor data, under key `externalData`	[value]

Send Reply to Specific Visitor

curl -X POST [API_URL]/localhost/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/reply
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"message":"Bot replied."}'

Successful request will return the following JSON structure:

{
  "id": "cl8b75ubl0049n6oq1758hp4x",
  "success": true
}

This endpoint sends a reply message to a specific visitor.

Example use cases:

To send a reply message to a single visitor

HTTP Request

POST [API_URL]/states/:PartitionKey/:RowKey/reply

Path Parameters

Parameter	Description	Example
PartitionKey	Domain/origin of the widget where visitor opened the webchat	keyreply.com
RowKey	The RowKey of the visitor	webchat

Body

Parameter	Mandatory	Description	Example Value
message	required	message text	Hi, replied from bot.

Interactions

Interactions are data containing chat messages that appear in the webchat widget.

All requests for interaction data begin with /interactions.

Get Interactions

curl "[API_URL]/interactions?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 171,
  "results": [
    {
      "RowKey": "cl8b75ubl0049n6oq1758hp4x",
      "PartitionKey": "localhost",
      "last_modified": "2022-09-21T05:41:02.529Z",
      "date_created": "2022-09-21T05:41:02.529Z",
      "source": "webchat",
      "type": "reply",
      "user_id": "2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e",
      "session": "59e6e15f-080d-4007-82bc-3591b9808c96",
      "data": {
        "content": [
          {
            "text": "Agent Yudha has joined the chat.",
            "buttons": []
          }
        ],
        "listStyle": null,
        "options": {
          "disableTextInput": false,
          "feedbackCollectionMode": "default",
          "nodeId": "handover_livechat_agent_join"
        },
        "meta": {
          "hideSuggestions": false,
          "lang": "default"
        }
      }
    }
  ]
}

This endpoint retrieves all interactions based on specified conditions

Example use cases:

List user chats on your website
Audit user chat contents for AI training

HTTP Request

GET [API_URL]/interactions

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
type	optional		Filter by interaction type	message
PartitionKey	optional		Filter by PartitionKey	keyreply.com
userId	optional		Filter by user ID	5db0d549-c45a-439d-af6a-ab91aa85eaf0
session	optional		Filter by session ID	d5dfee60-2137-4cb2-b84a-3c3ddc106dc3

Dashboard Users

This section details the data related to users on the KeyReply dashboard.

All requests associated with dashboard users should begin with /dashboard-users.

Get All Dashboard Users

curl "[API_URL]/dashboard-users" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

A successful request will return the following JSON structure:

{
  "count": 26,
  "results": [
    {
      "email": "agent@keyreply.com",
      "name": "John Doe",
      "data": "{\"app_metadata\":{\"departments\":[\"customer service\",\"claims\"],\"permissions\":[\"admin\"],\"roles\":[\"admin\"]},\"user_metadata\":{\"name\":\"John Doe\"}}",
      "livechat_status": "OFFLINE",
      "dashboard_status": "ONLINE",
      "livechat_settings": {
        "queues": [
            "customer service"
        ],
        "limit": 3
      }
    },
    ...
  ]
}

This endpoint retrieves all dashboard users based on the specified filter conditions.

HTTP Request

GET [API_URL]/dashboard-users

Query Parameters

Parameter	Mandatory	Default	Description	Example
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
email	optional		Filter by user's email address	"agent@keyreply.com"
name	optional		Filter by user's name	"John Doe"
livechat_status	optional		Filter by live chat status	"OFFLINE"
dashboard_status	optional		Filter by dashboard status	"ONLINE"

Agent Status

This section contains data related to live chat agent statuses. The default statuses are "ONLINE" and "OFFLINE". Additional statuses can be configured through the KeyReply dashboard. All requests for this data must begin with /agent-status-sessions.

Get All Agent Status Sessions

curl "[API_URL]/agent-status-sessions?fromDate=2022-09-01&toDate=2022-09-30" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

A successful request will return the following JSON structure:

{
  "count": 5,
  "results": [
    {
      "id": 29395,
      "agentId": "agent@keyreply.com",
      "agent_auth_type": "KEYCLOAK",
      "startTime": "2022-09-21T05:40:35.410Z",
      "endTime": "2022-09-21T05:56:46.037Z",
      "status": "ONLINE",
      "createdAt": "2022-09-21T05:40:35.447Z",
      "updatedAt": "2022-09-21T05:56:46.039Z"
    },
    ...
  ]
}

This endpoint retrieves all agent statuses based on specified conditions.

Example use cases:

Display agent activity within your applications

HTTP Request

GET [API_URL]/agent-status-sessions

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
agentId	optional		Filter by agent ID	"agent@keyreply.com"
status	optional		Filter by status	"OFFLINE"

Livechat

Livechat sessions are chat sessions that enter livechat mode. This is similar to the data shown on the "Livechat" page.

All requests for livechat session data begin with /livechatsessions.

Get All Livechat Sessions

# Get all livechat sessions for a specific date range
curl "[API_URL]/livechatsessions?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

# Get all livechat sessions waiting for assignment
curl "[API_URL]/livechatsessions?fromDate=2022-08-01&toDate=2022-08-31&waiting_for_assignment=true" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

# Get all resolved livechat sessions
curl "[API_URL]/livechatsessions?fromDate=2022-08-01&toDate=2022-08-31&resolved=true" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 1,
  "results": [
    {
      "meta": {},
      "agents": ["agent@keyreply.com"],
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:a304194d-e301-4d49-8910-84d3561852ac"
      ],
      "status": "pending",
      "resolved": false,
      "formData": {
        "channel": "Web Chat"
      },
      "RowKey": "cl8e3ou5o001jp4oqadvzdc8u",
      "PartitionKey": "localhost",
      "date_created": "2022-09-23T06:27:08.845Z",
      "last_modified": "2022-09-23T06:27:09.242Z",
      "user_id": "a304194d-e301-4d49-8910-84d3561852ac",
      "sessionId": "3257b6ed-7751-4fce-b37e-b3a1c452799b",
      "startQueueTime": "2022-09-23T06:27:08.845Z",
      "startResolveTime": "2022-09-23T06:27:08.845Z",
      "endResolveTime": null,
      "endedBy": null,
      "department": "00000000-0000-0000-0000-000000000000",
      "provider": "keyreply",
      "waiting_for_assignment": true
    }
  ]
}

This endpoint retrieves all livechat sessions based on specified conditions.

Example use cases:

Get all livechat sessions
Get all visitors in the queue
Get all resolved livechat sessions for reporting

HTTP Request

GET [API_URL]/livechatsessions

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
resolved	optional		Filter by resolved status	true
user_id	optional		Filter by user ID (visitor RowKey)	5db0d549-c45a-439d-af6a-ab91aa85eaf0
waiting_for_assignment	optional		Filter by assignment waiting status	false
sessionId	optional		Filter by session ID	3257b6ed-7751-4fce-b37e-b3a1c452799b

Get All Livechat Departments

curl "[API_URL]/livechatsessions/departments" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 2,
  "result": [
    {
      "id": "88cfe361-05e6-4aba-b408-df776109ebf3",
      "name": "customer service",
      "createdAt": "2021-12-13T06:31:21.701Z",
      "updatedAt": "2021-12-13T06:31:21.701Z"
    },
    {
      "id": "64b4942f-264e-4427-9beb-ed4012c31adf",
      "name": "customer service priority",
      "createdAt": "2021-12-15T02:44:10.368Z",
      "updatedAt": "2021-12-15T02:44:10.368Z"
    }
  ]
}

This endpoint retrieves all departments without any limits or offsets.

Example use cases:

You want to obtain the department name based on the department ID provided in the livechat session data.

HTTP Request

GET [API_URL]/livechatsessions/departments

Query Parameters

There are no query parameters for this API.

Get Specific Livechat Session

curl "[API_URL]/livechatsessions/cl8e3ou5o001jp4oqadvzdc8u" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
    "interactions": [{
            "PartitionKey": "localhost",
            "RowKey": "cl8e3otzl00043b6qsci55alf",
            "user_id": "a304194d-e301-4d49-8910-84d3561852ac",
            "session": "3257b6ed-7751-4fce-b37e-b3a1c452799b",
            "type": "postback",
            "source": "webchat",
            "date_created": "2022-09-23T06:27:08.746Z",
            "Timestamp": "2022-09-23T06:27:08.746Z",
            "data": {
                "content": [{
                    "event": "goto",
                    "data": "handover_livechat_start",
                    "postbackText": "Proceed"
                }]
            }
        },
        ...
    ],
    ...
}

This endpoint retrieves a specific livechat session.

Example use cases:

Show updated livechat data on your agent dashboard

HTTP Request

GET [API_URL]/livechatsessions/:RowKey

Get Queue Information

curl "[API_URL]/livechatsessions/queue-position?RowKey=cl8e3ou5o001jp4oqadvzdc8u" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

curl "[API_URL]/livechatsessions/queue-position?visitorId=7c38dc7b-57f5-4671-9a1d-862100e9f294&PartitionKey=localhost" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "queuePosition": 1, // Visitor's position in queue. Null value means visitor is no longer in queue.
  "estimatedWaitTime": 3 // Waiting time in minutes
}

This endpoint retrieves queue information for a livechat visitor.

Example use cases:

Check a visitor's position in queue
Check a visitor's estimated waiting time

HTTP Request

GET [API_URL]/livechatsessions/queue-position

Query Parameters

Parameter	Mandatory	Description	Example
visitorId	optional*	Visitor ID (required if RowKey not provided)	5db0d549-c45a-439d-af6a-ab91aa85eaf0
PartitionKey	optional*	Partition key (required if RowKey not provided)	sandbox.keyreply.com
RowKey	optional*	Livechat session RowKey	3257b6ed-7751-4fce-b37e-b3a1c452799b

Join a Livechat

curl -X POST [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/join
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"agentName":"John Doe", "agentEmail":"john@keyreply.com", "agentId" : "Y6YXNk"}'

Successful request will return the following JSON structure:

{
    "interactions": [
        ...
    ],
    "meta": {},
    "agents": [
        "loremipsum@keyreply.com"
    ],
    "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:a304194d-e301-4d49-8910-84d3561852ac"
    ],
    "status": "attending",
    "resolved": false,
    "formData": {
        "channel": "Web Chat"
    },
    "RowKey": "cl8e3ou5o001jp4oqadvzdc8u",
    "PartitionKey": "localhost",
    "date_created": "2022-09-23T06:27:08.845Z",
    "last_modified": "2022-09-23T06:46:36.444Z",
    "user_id": "a304194d-e301-4d49-8910-84d3561852ac",
    "sessionId": "3257b6ed-7751-4fce-b37e-b3a1c452799b",
    "startQueueTime": "2022-09-23T06:27:08.845Z",
    "startResolveTime": "2022-09-23T06:46:36.443Z",
    "endResolveTime": null,
    "endedBy": null,
    "department": "00000000-0000-0000-0000-000000000000",
    "provider": "keyreply",
    "waiting_for_assignment": false
}

Set your agent to join a livechat session

Example use case:

You want to connect your agent to join a livechat session

HTTP Request

POST [API_URL]/livechatsessions/:RowKey/join

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentName	required	Agent name to be shown in livechat message	James Bond
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com

Reply Livechat

curl -X POST [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/reply
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"agentName":"John Doe", "agentEmail":"john@keyreply.com", "agentId" : "Y6YXNk", "text":"how can I help?"}'

Successful request will return the following JSON structure:

// @TODO : update this
{
  "isInserted": true,
  "pid": 20344,
  "podId": "wealthy_red_swordfish"
}

Send a reply to a livechat session

Example use cases:

Forward agent replies from your system to KeyReply system, so the end visitor can see them

HTTP Request

POST [API_URL]/livechatsessions/:RowKey/reply

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentName	required	Agent name to be shown in livechat message	James Bond
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com
message	required	The message text to be sent	Hello world!

End a Livechat

curl -X POST [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/end
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"agentName":"John Doe", "agentEmail":"john@keyreply.com", "agentId" : "Y6YXNk", "endedBy":"agent"}'

Successful request will return the following JSON structure:

{
    "interactions": [{
            "PartitionKey": "localhost",
            "RowKey": "cl8e3otzl00043b6qsci55alf",
            "user_id": "a304194d-e301-4d49-8910-84d3561852ac",
            "session": "3257b6ed-7751-4fce-b37e-b3a1c452799b",
            "type": "postback",
            "source": "webchat",
            "date_created": "2022-09-23T06:27:08.746Z",
            "Timestamp": "2022-09-23T06:27:08.746Z",
            "data": {
                "content": [{
                    "event": "goto",
                    "data": "handover_livechat_start",
                    "postbackText": "Proceed"
                }]
            }
        },
        ...
    ],
    ...
}

End a livechat session and close the green banner on the web chat

Example use cases:

Your agent ends the session on your system and wants to forward this event to KeyReply system

HTTP Request

POST [API_URL]/livechatsessions/:RowKey/end

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentName	required	Agent name to be shown in livechat message	James Bond
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com
endedBy	optional	Who ended this chat ("agent" or "system"). Defaults to "agent"	system

Send File to Livechat

curl -X POST [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/send-file
  -H "Content-Type: multipart/form-data" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -F "file=@/path/to/file" \
  -F "text=hello" \
  -F "agentName=John Doe" \
  -F "agentEmail=john@keyreply.com" \
  -F "agentId=Y6YXNk"

Successful request will return the following JSON structure:

{
  "isInserted": true,
  "pid": 6213,
  "podId": "gleaming_bronze_kiwi"
}

Send a file or image to a livechat session

Example use cases:

Send a file from your agent dashboard to webchat user

HTTP Request

POST [API_URL]/livechatsessions/:RowKey/send-file

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentName	required	Agent name to be shown in livechat message	James Bond
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com
file	required	File content

Retrieve File from Livechat

curl -X GET [API_URL]/request-file?blobName=files/uploads/temp/c1d6abb0-7baa-4d84-a8b8-3967287abc9e/dummy-img.jpg \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "url": "https://yourkeyreplyserver.com/files/uploads/temp/c1d6abb0-7baa-4d84-a8b8-3967287abc9e/dummy-img.jpg?st=2023-02-16T02%3A40%3A42Z&se=2023-02-16T04%3A40%3A42Z&sp=r&sv=2018-03-28&sr=b&sig=z7ydJ7IMYy5TUHMtpECIo5lR8cN63va7Vr0WqeN5WIY%3D"
}

Retrieve the file URL from an image or file sent by a user to your system. Accessing the URL directly (e.g. https://yourkeyreplyserver.com/files/uploads/temp/c1d6abb0-7baa-4d84-a8b8-3967287abc9e/dummy-img.jpg) without the additional metadata like above might result in an authentication error.

Example use cases:

Display image or file sent by user to your agent

HTTP Request

GET [API_URL]/livechatsessions/request-file

Query Parameters

Parameter	Example	Description
blobName	files/uploads/temp/c1d6abb0-7baa-4d84-a8b8-3967287abc9e/dummy-img.jpg	The blobName or URL found in the user chat

Post Livechat Survey

curl -X POST [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/post-survey \
  -H "Content-Type: application/json" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"agentId":"agent123", "agentEmail":"agent@keyreply.com", "surveyJSON":{"customerName":"John Smith","customerId":"CUS123456","policyNumber":"POL-987654","inquiryType":"Claims","contactNumber":"+65 9123 4567","preferredContactTime":"Morning"}}'

Request Body:

{
  "agentId": "agent123",
  "agentEmail": "agent@keyreply.com",
  "surveyJSON": {
    "customerName": "John Smith",
    "customerId": "CUS123456",
    "policyNumber": "POL-987654",
    "inquiryType": "Claims",
    "contactNumber": "+65 9123 4567",
    "preferredContactTime": "Morning"
  }
}

Successful request will return the following JSON structure:

{
  "livechatsessionRowKey": "2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e",
  "success": true
}

Error Response:

{
  "message": "Data not found"
}

{
  "message": "Agent is not authorized to submit survey for this session"
}

Submit a post-survey for a livechat session

Example use cases:

Process post-survey data for a particular livechat session

HTTP Request

POST [API_URL]/livechatsessions/:RowKey/post-survey

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com
surveyJSON	required	Stringified JSON that will be recorded as survey data	{"message": "prospect user"}

Get Livechat Survey Data

curl -X GET [API_URL]/livechatsessions/2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e/post-survey \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "livechatsessionRowKey": "2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e",
  "surveyJSON": {
    "customerName": "John Smith",
    "customerId": "CUS123456",
    "policyNumber": "POL-987654",
    "inquiryType": "Claims",
    "contactNumber": "+65 9123 4567",
    "preferredContactTime": "Morning"
  }
}

Retrieve survey data for a specific livechat session

Example use cases:

Get post-survey responses for a particular livechat session
Analyze customer feedback and satisfaction data

HTTP Request

GET [API_URL]/livechatsessions/:RowKey/survey

Path Parameters

Parameter	Example	Description
RowKey	cl8e3ou5o001jp4oqadvzdc8u	The livechat session RowKey

Response

Field	Type	Description
livechatsessionRowKey	string	The RowKey of the livechat session
surveyData	object	The survey data submitted for this livechat session

Create a Livechat Session

curl -X POST [API_URL]/create-livechatsession
  -H "Content-Type: application/json"  \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f" \
  -d '{"agentName":"John Doe", "agentEmail":"john@keyreply.com", "agentId" : "Y6YXNk", "userId": "a304194d-e301-4d49-8910-84d3561852ac"}'

Successful request will return the following JSON structure:

{
    "interactions": [
        ...
    ],
    "meta": {},
    "agents": [
        "john@keyreply.com"
    ],
    "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:a304194d-e301-4d49-8910-84d3561852ac"
    ],
    "status": "attending",
    "resolved": false,
    "formData": {
        "channel": "Web Chat"
    },
    "RowKey": "cl8e3ou5o001jp4oqadvzdc8u",
    "PartitionKey": "localhost",
    "date_created": "2022-09-23T06:27:08.845Z",
    "last_modified": "2022-09-23T06:46:36.444Z",
    "user_id": "a304194d-e301-4d49-8910-84d3561852ac",
    "sessionId": "3257b6ed-7751-4fce-b37e-b3a1c452799b",
    "startQueueTime": "2022-09-23T06:27:08.845Z",
    "startResolveTime": "2022-09-23T06:46:36.443Z",
    "endResolveTime": null,
    "endedBy": null,
    "department": "00000000-0000-0000-0000-000000000000",
    "provider": "keyreply",
    "waiting_for_assignment": false
}

Create a new livechat session

Example use cases:

Create a new livechat session for your agent

HTTP Request

POST [API_URL]/create-livechatsession

Path Parameters

No path parameters required.

Body

Parameter	Mandatory	Description	Example Value
agentId	required	Unique agent ID from your system	AGENT007
agentName	required	Agent name to be shown in livechat message	James Bond
agentEmail	required	Agent email to be shown on audit page	jamesbond@yoursystem.com
userId	required	Visitor ID that will be pulled into livechat session	jamesbond@yoursystem.com

Chat Events

Chat events are data containing all events that occur during a chat session. This data is similar to what is shown in the "Visitor" tab -> "Show visitor interactions"

All requests for events data begin with /events

Get All Events

curl "[API_URL]/events?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 26402,
  "results": [
    {
      "RowKey": "cl7a99ayh00xgk8oq37ddfk22",
      "PartitionKey": "localhost",
      "last_modified": "2022-08-26T09:12:14.778Z",
      "date_created": "2022-08-26T09:12:14.778Z",
      "data": "handover_livechat_agent_join",
      "event": "GOTO",
      "page_id": "localhost",
      "source": "webchat",
      "user_id": "78c82d51-b89a-4c32-94ec-b872718d656c",
      "session": "78c82d51-b89a-4c32-94ec-b872718d656c",
      "from": "CS_Help_livechat_SMS_Auto"
    },
    {
      "RowKey": "cl7a99a9d00x0k8oqa8ti57bg",
      "PartitionKey": "localhost",
      "last_modified": "2022-08-26T09:12:13.874Z",
      "date_created": "2022-08-26T09:12:13.874Z",
      "data": "handover_livechat_agent_join",
      "event": "GOTO",
      "page_id": "localhost",
      "source": "webchat",
      "user_id": "616610a9-5299-4e0c-a244-026f09f76a40",
      "session": "616610a9-5299-4e0c-a244-026f09f76a40",
      "from": "handover_livechat_wait"
    }
  ]
}

This endpoint retrieves all events based on specified conditions.

Example use cases:

Retrieve detailed user action history

HTTP Request

GET [API_URL]/events

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
event	optional		Filter by event name	message
PartitionKey	optional		Filter by PartitionKey	keyreply.com
userId	optional		Filter by user ID	5db0d549-c45a-439d-af6a-ab91aa85eaf0
session	optional		Filter by session ID	d5dfee60-2137-4cb2-b84a-3c3ddc106dc3

Ratings

Ratings are data containing feedback given by visitors at the end of their livechat sessions.

All requests for ratings data begin with /ratings

Get All Ratings

curl "[API_URL]/ratings?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 1,
  "results": [
    {
      "RowKey": "cl3p7b0x9001an9oq9xeg0fh5",
      "PartitionKey": "AIA",
      "last_modified": "2022-05-28T01:35:19.150Z",
      "date_created": "2022-05-28T01:35:19.150Z",
      "rating": 1,
      "user": "74bff792-baf9-49f0-8e0e-af9cf103e5ab",
      "rating_comment": null,
      "sessionId": "369cd0bb-f548-44e7-90b5-2bea538bc205",
      "category": null,
      "livechatsession_id": "cl3p7alve000pn9oq0r900u9x"
    }
  ]
}

This endpoint retrieves all ratings based on specified conditions.

Example use cases:

Generate rating reports for livechat sessions

HTTP Request

GET [API_URL]/ratings

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
rating	optional		Filter by rating value	1
userId	optional		Filter by user ID	5db0d549-c45a-439d-af6a-ab91aa85eaf0

Form Results

Form results contain data from forms created in the form builder (not from post-livechat surveys) that visitors have completed. This data is similar to what is shown in "Editor" -> "Form" -> "Results"

All requests for form results data begin with /form-results

Get Form Results

curl "[API_URL]/form-results?fromDate=2022-08-01&toDate=2022-08-31" \
  -H "x-api-key: 9cac117e-d211-4193-9068-74ec449011f"

Successful request will return the following JSON structure:

{
  "count": 171,
  "results": [
    {
      "RowKey": "cl8b75ubl0049n6oq1758hp4x",
      "PartitionKey": "localhost",
      "last_modified": "2022-09-21T05:41:02.529Z",
      "date_created": "2022-09-21T05:41:02.529Z",
      "source": "webchat",
      "type": "reply",
      "user_id": "2c6a0cd1-863f-4e7e-bc7d-fcc3d4b34f9e",
      "session": "59e6e15f-080d-4007-82bc-3591b9808c96",
      "data": {
        "content": [
          {
            "text": "Agent Yudha has joined the chat.",
            "buttons": []
          }
        ],
        "listStyle": null,
        "options": {
          "disableTextInput": false,
          "feedbackCollectionMode": "default",
          "nodeId": "handover_livechat_agent_join"
        },
        "meta": {
          "hideSuggestions": false,
          "lang": "default"
        }
      }
    }
  ]
}

This endpoint retrieves all form results based on specified conditions.

Example use cases:

Generate reports from form submissions

HTTP Request

GET [API_URL]/form-results

Query Parameters

Parameter	Mandatory	Default	Description	Example
fromDate	required		ISO 8601 format	2022-08-01
toDate	required		ISO 8601 format	2022-08-31
sort	optional	desc	"asc" (ascending) or "desc" (descending)	desc
limit	optional	100	Maximum number of records to return	10
offset	optional	0	Number of records to skip	10
formId	optional		Filter by form ID	d5dfee60-2137-4cb2-b84a-3c3ddc106dc3
userId	optional		Filter by user ID	5db0d549-c45a-439d-af6a-ab91aa85eaf0
sessionId	optional		Filter by session ID	d5dfee60-2137-4cb2-b84a-3c3ddc106dc3

Event Hooks

This section describes all events that trigger requests to your specified endpoint. You can configure a single request URL for all events through "Settings -> Developer." The URL must include the full protocol (e.g., "https://mysite.com/webhook"). When an event is triggered, our system sends a POST request to this endpoint.

Every request body contains four required JSON keys: "id", "event", "payload", and "sentAt".

Parameter	Description	Example
id	Unique identifier of the payload, used for idempotency checks (preventing duplicate request processing)	cledva3j10014088z0dtj0f8s
sentAt	Timestamp in ISO string format indicating when the request was sent	2023-08-04T03:16:56.937Z
event	Name of the event	"handover:afterLivechatSessionEnded"
payload	Data object containing event-specific information	{RowKey: "...", ...}

Getting Started

To begin, configure the outgoing request settings in the developer module.

3-add-event-hooks

Notes

4-manage-visitor-data

When a Visitor Sends a Text Message

Triggered when:

A visitor sends a typed message
Note: This event is not triggered when a visitor clicks a button or quick reply

Example use cases:

Display visitor messages in real-time on your agent dashboard

Payload:

{
  "id": "clkw0kqgb001cw3bp53gq5gl7",
  "event": "bot:beforeTextHandler",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "keyreply.com",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0"
    },
    "text": "talk to agent"
  },
  "sentAt": "2023-08-04T03:16:17.771Z"
}

After an Agent Changes Status

Triggered when:

A livechat agent changes their status (e.g., from "OFFLINE" to "ONLINE")

Example use cases:

Update agent status in real-time on your dashboard

Payload:

{
  "id": "clkw0lko9002lw3bp53qf2v8j",
  "event": "handover:agentChangedStatus",
  "payload": {
    "agent": "agent@keyreply.com",
    "status": "OFFLINE",
    "startTime": "2023-08-04T03:16:56.829Z",
    "departments": ["department A", "department B"],
    "previousStatus": "ONLINE"
  },
  "sentAt": "2023-08-04T03:16:56.937Z"
}

After a Visitor Requests a Livechat

Triggered when:

A visitor requests a livechat session
This occurs after the request but before agent assignment; the visitor remains in the waiting queue

Example use cases:

Update visitor queue in real-time on your agent dashboard

Payload:

{
  "id": "clkw0ktxa001xw3bpewv55oiy",
  "event": "handover:afterUserRequestedLivechat",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "localhost",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "userQueryTopic": "department A"
    },
    "livechat": {
      "RowKey": "clkw0ktug001vw3bp5soc694a",
      "PartitionKey": "localhost",
      "startQueueTime": "2023-08-04T03:16:22.170Z",
      "startResolveTime": "2023-08-04T03:16:22.171Z",
      "agents": [],
      "date_created": "2023-08-04T03:16:22.171Z",
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:e229a5cd-8bfc-44d3-99cc-589dcc8af1c6"
      ],
      "resolved": false,
      "user_id": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "department": "00000000-0000-0000-0000-000000000000",
      "sessionId": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "waiting_for_assignment": true,
      "status": "pending",
      "formData": {
        "channel": "Web Chat"
      },
      "provider": "keyreply"
    }
  },
  "sentAt": "2023-08-04T03:16:22.270Z"
}

After an Agent Joins a Livechat

Triggered when:

An agent joins a livechat session through manual assignment or auto-assignment

Example use cases:

Track active livechat sessions in real-time on your dashboard

Payload:

{
  "id": "clkw0kw0l0025w3bp21cq5i3m",
  "event": "handover:afterAgentJoinedLivechat",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "localhost",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "userQueryTopic": "department A"
    },
    "livechat": {
      "meta": {},
      "agents": ["agent@keyreply.com"],
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:e229a5cd-8bfc-44d3-99cc-589dcc8af1c6"
      ],
      "status": "attending",
      "resolved": false,
      "formData": {
        "channel": "Web Chat"
      },
      "RowKey": "clkw0ktug001vw3bp5soc694a",
      "PartitionKey": "localhost",
      "date_created": "2023-08-04T03:16:22.171Z",
      "last_modified": "2023-08-04T03:16:24.406Z",
      "user_id": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "sessionId": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "startQueueTime": "2023-08-04T03:16:22.172Z",
      "startResolveTime": "2023-08-04T03:16:24.406Z",
      "endResolveTime": null,
      "endedBy": null,
      "department": "00000000-0000-0000-0000-000000000000",
      "provider": "keyreply",
      "waiting_for_assignment": false
    }
  },
  "sentAt": "2023-08-04T03:16:24.981Z"
}

After an Agent Accepted a Livechat Invitation

Triggered when:

An agent accepts a livechat session invitation from another agent

Payload:

{
  "id": "clkw0kw0l0025w3bp21cq5i3m",
  "event": "handover:afterAgentAcceptedInvitation",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "localhost",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "userQueryTopic": "department A"
    },
    "livechat": {
      "meta": {},
      "agents": ["agent@keyreply.com", "agent2@keyreply.com"],
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:e229a5cd-8bfc-44d3-99cc-589dcc8af1c6"
      ],
      "status": "attending",
      "resolved": false,
      "formData": {
        "channel": "Web Chat"
      },
      "RowKey": "clkw0ktug001vw3bp5soc694a",
      "PartitionKey": "localhost",
      "date_created": "2023-08-04T03:16:22.171Z",
      "last_modified": "2023-08-04T03:16:24.406Z",
      "user_id": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "sessionId": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "startQueueTime": "2023-08-04T03:16:22.172Z",
      "startResolveTime": "2023-08-04T03:16:24.406Z",
      "endResolveTime": null,
      "endedBy": null,
      "department": "00000000-0000-0000-0000-000000000000",
      "provider": "keyreply",
      "waiting_for_assignment": false
    }
  },
  "sentAt": "2023-08-04T03:16:24.981Z"
}

After Livechat Session Ends

Triggered when:

A visitor, agent, or system ends a livechat session
The system can end a livechat session if the inactivity manager is triggered

Example use cases:

Update livechat session status in real-time on your dashboard

Payload:

{
  "id": "clkw0le1t002iw3bpdnsagsoz",
  "event": "handover:afterLivechatSessionEnded",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "localhost",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "userQueryTopic": "department A"
    },
    "livechat": {
      "meta": {},
      "agents": ["agent@keyreply.com"],
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:e229a5cd-8bfc-44d3-99cc-589dcc8af1c6"
      ],
      "status": "resolved",
      "resolved": true,
      "formData": {
        "channel": "Web Chat"
      },
      "RowKey": "clkw0ktug001vw3bp5soc694a",
      "PartitionKey": "localhost",
      "date_created": "2023-08-04T03:16:22.171Z",
      "last_modified": "2023-08-04T03:16:48.282Z",
      "user_id": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "sessionId": "c98817d2-ed3b-4162-b865-bbe66ae831a0",
      "startQueueTime": "2023-08-04T03:16:22.172Z",
      "startResolveTime": "2023-08-04T03:16:24.406Z",
      "endResolveTime": "2023-08-04T03:16:48.282Z",
      "endedBy": "agent",
      "department": "00000000-0000-0000-0000-000000000000",
      "provider": "keyreply",
      "waiting_for_assignment": false
    }
  },
  "sentAt": "2023-08-04T03:16:48.353Z"
}

After a Livechat is Escalated

Triggered when:

An agent escalates a livechat session to another queue or department

Example use cases:

Notify the new department about the escalated livechat session

Payload information:

"livechat" refers to the previous livechat session that was escalated
"escalatedLivechat" refers to the new livechat session that has been escalated to
"visitor" data contains the visitor data after the chat has been successfully escalated, not the visitor data before the chat was escalated

Payload:

{
  "id": "clos331xj005bw0bq7phx0upq",
  "event": "handover:afterLivechatSessionEscalated",
  "payload": {
    "visitor": {
      "userQueryTopic": "department B",
      "RowKey": "9f56c9ee-af55-4ff2-bc72-66757fe42903",
      "PartitionKey": "localhost",
      "session_id": "a46becd6-b456-4826-9123-7ca5dc413581"
    },
    "livechat": {
      "meta": {
        "escalate_logs": "[{\"department\":\"department A\",\"date_created\":\"2023-11-10T03:54:06.785Z\"}]"
      },
      "agents": ["agent_load_testing_1@keyreply.com"],
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:9f56c9ee-af55-4ff2-bc72-66757fe42903"
      ],
      "status": "resolved",
      "resolved": true,
      "formData": {
        "channel": "Web Chat"
      },
      "RowKey": "clos3235k004jw0bqfjgs0t91",
      "PartitionKey": "localhost",
      "date_created": "2023-11-10T03:53:31.256Z",
      "last_modified": "2023-11-10T03:54:07.327Z",
      "user_id": "9f56c9ee-af55-4ff2-bc72-66757fe42903",
      "sessionId": "a46becd6-b456-4826-9123-7ca5dc413581",
      "startQueueTime": "2023-11-10T03:53:31.257Z",
      "startResolveTime": "2023-11-10T03:53:34.033Z",
      "endResolveTime": "2023-11-10T03:54:07.327Z",
      "endedBy": "agent",
      "department": "00000000-0000-0000-0000-000000000000",
      "provider": "keyreply",
      "waiting_for_assignment": false
    },
    "escalatedLivechat": {
      "RowKey": "clos32v4k005aw0bq0pb0eszo",
      "PartitionKey": "localhost",
      "startQueueTime": "2023-11-10T03:54:07.509Z",
      "startResolveTime": "2023-11-10T03:54:07.509Z",
      "agents": [],
      "date_created": "2023-11-10T03:54:07.509Z",
      "tags": [
        "channel:webchat",
        "PartitionKey:localhost",
        "RowKey:9f56c9ee-af55-4ff2-bc72-66757fe42903"
      ],
      "resolved": false,
      "user_id": "9f56c9ee-af55-4ff2-bc72-66757fe42903",
      "department": "b26a630e-e388-4c64-a415-429d1a97f1ae",
      "sessionId": "a46becd6-b456-4826-9123-7ca5dc413581",
      "waiting_for_assignment": true,
      "status": "pending",
      "formData": {
        "channel": "Web Chat"
      },
      "provider": "keyreply",
      "meta": {
        "escalate_logs": "[{\"department\":\"department A\",\"date_created\":\"2023-11-10T03:54:06.785Z\"}]"
      }
    }
  },
  "sentAt": "2023-11-10T03:54:16.330Z"
}

After Agent Updates Livechat Form Data

Triggered when:

A livechat session's form data is updated (e.g., post-survey submission)

Example use cases:

Track form submissions and survey responses in real-time
Integrate survey data with external analytics systems

Payload:

{
  "id": "clkw0le1t002iw3bpdnsagsoz",
  "event": "handover:afterFormDataUpdate",
  "payload": {
    "livechatsessionRowKey": "clos3235k004jw0bqfjgs0t91",
    "surveyJSON": {
      "customerName": "John Smith",
      "customerId": "CUS123456",
      "policyNumber": "POL-987654",
      "inquiryType": "Claims",
      "contactNumber": "+65 9123 4567",
      "preferredContactTime": "Morning"
    }
  },
  "sentAt": "2024-12-24T02:35:44.353Z"
}

When Agent Sends Text Message

Triggered when:

The agent sends a typed message

Example use cases:

Monitor agent messages in real-time

Payload:

{
  "id": "cm46uncfs00040ck1frox1ulc",
  "event": "handover:afterAgentReply",
  "payload": {
    "recipient": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "keyreply.com",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0"
    },
    "agentMeta": {
      "email": "support@keyreply.com",
      "name": "Support Agent",
      "alias": "SA"
    },
    "text": "Hi, this is your agent assisting you today, how can I help you?"
  },
  "sentAt": "2024-12-02T03:16:17.771Z"
}

Triggered when:

A visitor sends a request for Singpass Login

Example use cases:

Track Singpass Login requests made by visitors

Payload:

{
  "id": "clkw0kqgb001cw3bp53gq5gl7",
  "event": "singpass:requestLogin",
  "payload": {
    "visitor": {
      "RowKey": "e229a5cd-8bfc-44d3-99cc-589dcc8af1c6",
      "PartitionKey": "keyreply.com",
      "session_id": "c98817d2-ed3b-4162-b865-bbe66ae831a0"
    }
  },
  "sentAt": "2023-08-04T03:16:17.771Z"
}

Receiving WhatsApp Notification Event

Triggered when:

Triggered by a WhatsApp notification hook request from Meta, indicating a status update for a previously sent message template

Example use cases:

Update the status of a previously sent message template

Payload information:

"id" refers to the unique identifier of the message template sent via WhatsApp
"status" refers to the latest status update of the message
"timestamp" refers to the Unix timestamp indicating when the status was last updated
"recipient_phone_number" refers to the phone number of the message recipient, including the country code
"business_phone_number" refers to the phone number of the business that sent the message, including the country code
"template_id" refers to the name of the message template used
"template_version" refers to the language version of the message template, if applicable
"error_log" refers to the error log entry created when the message status is 'failed'

Payload type:

{
  id: string;
  event: "whatsapp:notification";
  payload: {
    id: string;
    status: "sent" | "delivered" | "read" | "failed" | "deleted";
    timestamp: string; // unix format
    recipient_phone_number: string; // non-seperatable from country code
    business_phone_number: string; // non-seperatable from country code
    template_id: string;
    template_version: string | null;
    error_log: string | null;
  }
  sentAt: string; // ISO format
}

Payload:

{
  "id": "cm2bnvgm1000f4ui1f1lhe97h",
  "event": "whatsapp:notification",
  "payload": {
    "status": "delivered",
    "id": "gBG******",
    "timestamp": "1729070401",
    "recipient_phone_number": "65*****",
    "business_phone_number": "65*****",
    "template_id": "template_test",
    "template_version": "en",
    "error_log": null
  },
  "sentAt": "2024-10-16T09:20:01.753Z"
}
// message id and phone numbers are masked for doc purpose only

Errors

The KeyReply API uses the following HTTP status codes:

Status Code	Description
400	Bad Request - The request format is invalid
401	Unauthorized - Invalid API key
403	Forbidden - Access restricted to administrators
404	Not Found - The requested resource does not exist
405	Method Not Allowed - Invalid HTTP method for this resource
429	Too Many Requests - Request rate limit exceeded
500	Internal Server Error - Server encountered an error, please try again
503	Service Unavailable - System is under maintenance, please try again later