Application API

The Application APIs are REST APIs that are based on HTTP protocol and used for accessing data as an individual user. These are developed for client-side programming languages to retrieve data into your Web & Mobile Applications.

NOTE: The Application APIs can also be accessed using the Admin API’s request header.

Find below details to access Application APIs.

Base URL

Application APIs base URL format.

https://api.channelize.io/v2/

Header

Application APIs header format.

Content-Type: application/json
Public-Key: YOUR_PUBLIC_KEY
Authorization: Bearer base_64_encode(ACCESS_TOKEN)

Content-Type: Every API request should include Content-Type having value application/json.
Public Key: For authorizing API requests you need a Public Key. Get your application's Public Key from your Channelize.io dashboard. Go to Overview > Application Credentials.

Screenshot

Authorization: A Base64 encoded Access Token is required in all API requests except login and verify access token.

Get Access Token

Every user will have a different Access Token. Here are the steps to get Access Token for a user:

Create the user in your Channelize.io Application using Create a User API call. Skip this step if you already have this user in your Channelize.io application.
Login as this user in your Channelize.io application using the Login API call. Here is the syntax for the login request, its Request Header header, Request Parameters and the Response.

Request URL

Request Headers

Request Parameters

Response

cURL

POST https://api.channelize.io/v2/users/login

Content-Type: application/json
Public-Key: YOUR_PUBLIC_KEY

{
    "email": "YOUR_EMAIL",
    "password": "YOUR_PASSWORD",
    "authenticationType": 1
}

{
    "id": "IVhBHzWChmlcZtSn7j7hIHjejdFhOihzVQvwmwjNmevcNQtUuFpgxi16v8uabcde",
    "ttl": 1209600,
    "created": "2019-04-25T10:56:12.311Z",
    "userId": "15"
}

curl -XPOST -H 'Content-Type: application/json' -H 'Public-Key: YOUR_PUBLIC_KEY' -d '{
"email": "YOUR_EMAIL",
"password": "YOUR_PASSWORD",
"authenticationType": 1
}' 'https://api.channelize.io/v2/users/login'

In response to the Login API request, an Access Token is received. In the above response, the parameter with name id is the Access Token.
Encode it to Base64.

Verify Access Token

Verifies the Access Token generated from Login / User-Authentication API calls.

POST https://api.channelize.io/v2/users/verify_access_token

Body Params

This table lists all possible parameters this API call supports.

Name	Type	Required	Default	Description
accessToken	string	yes	-	The access token of login.

Response Body

Status Code : 200

{
    "id": "QBwo1bGPDWIIHE3GBoSnAFAnXLVyC6EmmXTMW3aAU8wGDenbYFfUsabcde",
    "ttl": 1209600,
    "created": "2018-11-05T12:41:46.904Z",
    "userId": "152",
    "user": {
        "id": "152",
        "displayName": "Channelize Demo User",
        "language": "en",
        "profileImageUrl": "https://channelize.io/profileImage.jpg",
        "profileUrl": "https://channelize.io/profile",
        "isOnline": true,
        "visibility": true,
        "notification": true,
        "lastSeen": "2019-04-23T09:26:18.320Z",
        "lastLogin": "2019-04-25T11:30:37.988Z",
        "lastActivity": "2019-04-25T11:30:37.990Z",
        "createdAt": "2018-05-25T11:52:39.000Z",
        "updatedAt": "2018-05-25T11:52:39.000Z",
        "email": "test1@gmail.com"
    }
}

Login / User-Authentication

To ensure that authentic users have access to Channelize.io services, Channelize.io provides two methods of Login / User-Authentication.

Authentication with User ID

This authentication method is useful for any of the below use-cases:

GDPR and HIPAA compliant applications that don’t save or share users’ personal information like Email ID.
Applications that have their own authentication process, and can do a token-based Single Sign-On (SSO) with Channelize.io API.

Pre-requisites

Create a Login token Callback URL in your application's backend. This should be added in the Channelize.io Dashboard under App Settings > Security. This callback URL will be invoked by the Channelize.io Login API to verify the value of pmClientServerToken used in this authentication method.

Screenshot

Find below the request and response for Login token Callback URL:

Request

POST https://your-token-validation-callback-url

body: 
{
"token": "token",
"userId": "userId"
}

Response Body

Output JSON expected from the callback:

Send 200 status code and the below body in JSON response.

body: 
{
 "token": "token"
}

Steps to Implement

Make a Login API request

POST https://api.channelize.io/v2/users/login

Body Params

This table lists all parameters this Login API request supports.

Name	Type	Required	Description
authenticationType	number	yes	Specifies the type of authentication. Allowed values are 0 and 1. Set this to 0 for authentication with User Id.
userId	string	yes	The unique ID of the user to authenticate.
pmClientServerToken	string	yes	User's login token that needs to be generated by your application's backend, saved inside it and deleted post user login.

Authentication with Email and Password

This authentication method is useful for below use-cases:

Standalone Chat Applications built with Channelize.io.
Applications which do not have their own authentication process, and want to use Channelize.io API for primary user authentication as well.

Steps to Implement

Make a Login API request

POST https://api.channelize.io/v2/users/login

Body Params

This table lists all parameters this API call supports.

Name	Type	Required	Default	Description
authenticationType	number	yes	-	Specifies the type of authentication. Allowed values are 0 and 1. Set this to 1 for authentication with Email and Password.
email	string	yes	-	The email address of user to authenticate.
password	string	yes	-	The login password of user to authenticate.

Response Body

Status Code : 200

{
    "id": "QBwo1bGPDWIIHE3GBoSnAFAnXLVyC6EmmXTMW3aAU8wGDenbYFfUsabcde",
    "ttl": 1209600,
    "created": "2018-11-05T12:41:46.904Z",
    "userId": "152",
    "user": {
        "id": "152",
        "displayName": "Channelize Demo User",
        "language": "en",
        "profileImageUrl": "https://channelize.io/profileImage.jpg",
        "profileUrl": "https://channelize.io/profile",
        "isOnline": true,
        "visibility": true,
        "notification": true,
        "lastSeen": "2019-04-23T09:26:18.320Z",
        "lastLogin": "2019-04-25T11:30:37.988Z",
        "lastActivity": "2019-04-25T11:30:37.990Z",
        "createdAt": "2018-05-25T11:52:39.000Z",
        "updatedAt": "2018-05-25T11:52:39.000Z",
        "email": "test1@gmail.com"
    }
}

Both Login / Authentication methods will generate an Access Token which would be used in the header of Application APIs.

While integrating Channelize with the existing application, Login API call should be called from the client server using Admin API instead of client front-end as this will not spoil user experience at client front-end as well as the API calls are executed faster in the servers compared to browsers or mobile applications due to sufficient internet access in the server.

Logout User

Logs out a user from your Channelize.io application. The generated access token will expire on logout.

POST https://api.channelize.io/v2/users/logout

Body Params

This table lists all possible parameters this API call supports.

Name	Type	Required	Default	Description
deviceId	string	no	-	Specifies the device ID. This device ID should be the unique id of the user's device (Android / iOS OR Web Browser).

Response Body

Status Code : 204

No Content

Please make Login API request only once in a session, and save the token locally (example in a Cookie). This will terminate an inefficient practice to make Login API request on every page load.

Channelize.io | Docs

next

Base URL

Header

Get Access Token

Verify Access Token

Login / User-Authentication

Authentication with User ID

Authentication with Email and Password

Logout User