linkchat Public API v1.0.2

General notes

Integrate linkchat functionalities to your web-based or mobile apps

linkchat Developers Site offers you access to our web services to build your own applications and to integrate our features and workflow to your dashboards, websites and management systems.

linkchat Public API is built using REST principles which ensures predictable URLs that makes writing applications easy. This API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API

Important note: The linkchat Developer API is currently undergoing BETA testing. If you want more information or if you want to use the API in your project, don't hesitate to contact us by our contact form or the following e-mail: info@linkchat.io. We will provide you with everything you need. We appreciate every feedback.

Authentication

linkchat Public API requires a mandatory header x-linkchat-api. The header contains the api key of the resource you need to access. The api key must be created via the admin GUI for each resource (domain, subdomain) and must be send in each reqest.

HTTP Methods

linkchat API uses appropriate HTTP verbs for every action:

Method Description
GET Used for retrieving resources.
POST Used for creating resources and performing resource actions.
PUT Used for updating resources.
DELETE Used for deleting resources.

Response

Responses will be in the JSON format.

Node Name Description
code linkchat error code. This will be zero for a success response and non-zero in case of an error.
message Message for the invoked API.
resource name Comprises the invoked API’s Data.

Error Codes

linkchat API uses HTTP status codes to indicate success or failure of an API call. In general, status codes in the 2xx range means success, 4xx range means there was an error in the provided information, and those in the 5xx range indicates server side errors. Commonly used HTTP status codes are listed below.

Status Code Descriptions
2xxSuccess
4xxBad request sent to server
5xxServer side error

Status Code Description
200 Success: The request was successfully completed.
201 Created: The request was a success and one or more resources have been created.
400 Bad request: The request cannot be performed. Usually because of malformed parameter or missing parameter.
401 Unauthorized (Invalid API key): Request was rejected because of invalid API key.
403 Forbidden: The user does not have enough permission or possibly not an user of the respective organization to access the resource.
404 URL Not Found: The URL you’ve sent is wrong. It’s possible that the resource you’ve requested has been moved to another URL.
405 Method Not Allowed: The requested resource does not support the HTTP method used. For example, requesting List of all customers API with PUT as the HTTP method.
406 Not Acceptable: The requested response type is not supported by the client.
429 Too many requests: Too many requests within a certain time frame. To know more about api call limits
500 Server error: linkchat server encountered an error which prevents it from fulfilling the request. Although this rarely happens, we recommend you to contact us at support@linkchat.io if you receive this error.

API Call Limit

API calls are limited to provide better quality of service and availability to all the users. The limits on total calls are illustrated below:

  • Premium - 2500 API calls/day and 100 API calls/minute
  • Free & Test Organization - 1000 API calls/day and 100 API calls/minute

API detail

List all rooms

Retrieving details of all rooms

curl -X GET -H "x-linkchat-api: {{api_key}}" "https://api.linkchat.io/rooms?page=0&page_size=20"
GET /rooms?page=0&page_size=20 HTTP/1.1
Host: api.linkchat.io
x-linkchat-api: {{api_key}}
Status200
{
    "code": 0,
    "success": "Successfully retrived",
    "page": {
        "size": 3,
        "totalElements": 5,
        "totalPages": 2,
        "number": 0
    },
    "result": [
        {
            "enableOpeningHours": true,
            "startTime": "2018-07-05T22:16:18Z",
            "endTime": "2018-07-06T22:16:18Z",
            "openingHoursRepeat": 1,
            "enableRoomPassword": true,
            "roomPassword": "asd678asF",
            "roomTitle": "linkchat test room 1",
            "roomId": "linkchat-test-room-1",
            "link": "https://linkchat.io/linkchat-test-room-1"
        },
        {
            "enableOpeningHours": false,
            "enableRoomPassword": false,
            "roomTitle": "linkchat test room 2",
            "roomId": "linkchat-test-room-1",
            "link": "https://linkchat.io/linkchat-test-room-2"
        },
        {
            "enableOpeningHours": false,
            "enableRoomPassword": false,
            "roomTitle": "linkchat test room 3",
            "roomId": "linkchat-test-room-3",
            "link": "https://linkchat.io/linkchat-test-room-3"
        }
    ]
}
Status500
{
    "code": 1000,
    "message": "Internal error"
}
Status200
{
    "code": 1001,
    "message": "Invalid API key"
}

Retrive a room

Retrieving details of a particular room

curl -X GET -H "x-linkchat-api: {{api_key}}" "https://api.linkchat.io/rooms/{{room_id}}"
GET /rooms/%7B%7Broom_id%7D%7D HTTP/1.1
Host: api.linkchat.io
x-linkchat-api: {{api_key}}
Status404
{
    "code": 1004,
    "message": "Room does not exist"
}
Status500
{
    "code": 1000,
    "message": "Internal error"
}
Status200
{
    "code": 0,
    "success": "OK",
    "result": {
        "enableOpeningHours": true,
        "startTime": "2018-07-05T22:16:18Z",
        "endTime": "2018-07-06T22:16:18Z",
        "openingHoursRepeat": 1,
        "enableRoomPassword": true,
        "roomPassword": "asd678asF",
        "roomTitle": "linkchat room found",
        "roomId": "linkchat-room-found",
        "link": "https://linkchat.io/linkchat-room-found"
    }
}
Status200
{
    "code": 1001,
    "message": "Invalid API key"
}

Creating a new room

Creates a new room

The body parameters are optional. If not set the random value will be generated. Timestamps are in ISO 8601 format.

curl -X POST -H "x-linkchat-api: {{api_key}}" -H "Content-Type: application/json" -d '{
    "enableOpeningHours": {{enableOpeningHours}},
    "startTime": {{startDate}},
    "endTime": {{endTime}},
    "openingHoursRepeat": {{openingHoursRepeat}},
    "enableRoomPassword": {{enableRoomPassword}},
    "roomPassword": {{roomPassword}},
    "roomTitle": {{roomTitle}}
}' "https://api.linkchat.io/rooms/{{room_id}}"
POST /rooms/%7B%7Broom_id%7D%7D HTTP/1.1
Host: api.linkchat.io
x-linkchat-api: {{api_key}}
Content-Type: application/json

{
    "enableOpeningHours": {{enableOpeningHours}},
    "startTime": {{startDate}},
    "endTime": {{endTime}},
    "openingHoursRepeat": {{openingHoursRepeat}},
    "enableRoomPassword": {{enableRoomPassword}},
    "roomPassword": {{roomPassword}},
    "roomTitle": {{roomTitle}}
}
Status200
{
    "code": 1001,
    "message": "Invalid API key"
}
Status500
{
    "code": 1000,
    "message": "Internal error"
}
Status200
{
    "code": 0,
    "success": "Successfully created",
    "result": {
        "enableOpeningHours": true,
        "startTime": "2018-07-05T22:16:18Z",
        "endTime": "2018-07-06T22:16:18Z",
        "openingHoursRepeat": 1,
        "enableRoomPassword": true,
        "roomPassword": "asd678asF",
        "roomTitle": "linkchat create new room room",
        "roomId": "linkchat-successfully-created-room",
        "link": "https://linkchat.io/linkchat-successfully-created-room"
    }
}
Status403
{
    "code": 1003,
    "message": "Room already exists"
}

Updating a room

Editing the existing room

Timestamps are in ISO 8601 format.

curl -X PUT -H "x-linkchat-api: {{api_key}}" -H "Content-Type: application/json" -d '{
    "enableOpeningHours": {{enableOpeningHours}},
    "startTime": {{startDate}},
    "endTime": {{endTime}},
    "openingHoursRepeat": {{openingHoursRepeat}},
    "enableRoomPassword": {{enableRoomPassword}},
    "roomPassword": {{roomPassword}},
    "roomTitle": {{roomTitle}}
}' "https://api.linkchat.io/rooms/{{room_id}}"
PUT /rooms/%7B%7Broom_id%7D%7D HTTP/1.1
Host: api.linkchat.io
x-linkchat-api: {{api_key}}
Content-Type: application/json

{
    "enableOpeningHours": {{enableOpeningHours}},
    "startTime": {{startDate}},
    "endTime": {{endTime}},
    "openingHoursRepeat": {{openingHoursRepeat}},
    "enableRoomPassword": {{enableRoomPassword}},
    "roomPassword": {{roomPassword}},
    "roomTitle": {{roomTitle}}
}
Status200
{
    "code": 0,
    "success": "Successfully updated"
}
Status404
{
    "code": 1004,
    "message": "Room does not exist"
}
Status500
{
    "code": 1000,
    "message": "Internal error"
}
Status200
{
    "code": 1001,
    "message": "Invalid API key"
}

Deleting a room

Deleting a particular room

curl -X DELETE -H "Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW" -H "x-linkchat-api: {{api_key}}" "https://api.linkchat.io/rooms/{{room_id}}"
DELETE /rooms/%7B%7Broom_id%7D%7D HTTP/1.1
Host: api.linkchat.io
x-linkchat-api: {{api_key}}
Status404
{
    "code": 1004,
    "message": "Room does not exist"
}
Status500
{
    "code": 1000,
    "message": "Internal error"
}
Status200
{
    "code": 1001,
    "message": "Invalid API key"
}
Status200
{
    "code": 0,
    "success": "Successfully deleted"
}