Zoho has created amazing Product ecosystem but is very poor while implementing the Clean API’s for it’s users.

Reference API Docs: https://www.zoho.com/cliq/help/restapi/v2/

In this article we will be demonstrating How to send a simple Message to Cliq Channel and ** Bot Subscribers**.

1. Setup a Server-based Application

Zoho Admin Panel Link: https://api-console.zoho.com

Add http://app.test/cliq-redirect url as ‘Authorized Redirect URIs ‘.

Create a Organization Channel in Cliq named mychannel.

Create a Bot with ** Listen** and ** Send** Permission and name it mybot.

Create a new Laravel Config config\cliq.php"

<?php
return [
    'client_id' => env('CLIQ_CLIENT_ID', '1000.----Generate-This----'),
    'client_secret' => env('CLIQ_CLIENT_SECRET', '----Generate-This----'),

    'default_channel' => env('CLIQ_DEFAULT_CHANNEL', 'mychannel')
    'default_bot' => env('CLIQ_DEFAULT_BOT', 'mybot')
];

2. Authenticating the API’s

Create a Auth URL with Scope ZohoCliq.Webhooks.CREATE and redirect in Controller and url http://app.test/cliq-auth

Request:

GET
https://cliq.zoho.com/oauth/v2/auth

URL Parameters:

ParameterDescription
scopeFor sending Messages via Cliq, it’s ZohoCliq.Webhooks.CREATE
client_idClient id obtained during client registration.
stateA generated value that correlates the callback with its associated authorization request
response_typecode
redirect_uriRedirect uri mentioned during client registration.
access_typeAccess type will be either online or offline .

Implementation:

$params = [
    'scope'       => 'ZohoCliq.Webhooks.CREATE',
    'client_id'   => config("cliq.client_id"),
    'state'       => '1234',
    'response_type' => 'code',
    'redirect_uri'    => url('cliq-redirect'),
    'access_type'     => 'offline',
];
return Response::make('', 302 )->header( 'Location', 'https://accounts.zoho.com/oauth/v2/auth?' . http_build_query($params) );

After hitting the url http://app.test/cliq-auth, you will be asked to login and give Permissions. Once successfull, you will receive a code in GET request of http://app.test/cliq-redirect.

3. Generate the access_token and refresh_token from received code

Request:

POST
https://cliq.zoho.com/oauth/v2/token

Form Parameters:

ParameterDescription
codeAuthorization code obtained during grant token generation.
client_idClient id obtained during client registration.
client_secretClient secret obtained during client registration.
redirect_uriRedirect uri mentioned during client registration.
grant_typeauthorization_code
scopeFor sending Messages via Cliq, it’s ZohoCliq.Webhooks.CREATE
stateA generated value that correlates the callback with its associated authorization request.Has to be maintained the same during the entire process for authenticity.

Implementation:

$code = $req->input('code');

$client = new Client([
    'base_uri' => 'https://accounts.zoho.com/oauth/v2/',
    'timeout'  => 10.0,
]);
$params = [
    'code'            => $code,
    'client_id'   => config("cliq.client_id"),
    'client_secret' => config("cliq.client_secret"),
    'redirect_uri'    => url('cliq-redirect'),
    'grant_type'  => 'authorization_code',
    'scope'       => 'ZohoCliq.Webhooks.CREATE',
    'state'       => '1234',
];
$response = $client->request('POST', 'token', [
    'form_params' => $params
]);
$body = json_decode($response->getBody());
if(isset($body->access_token)) {
    // Save the access_token in DB
    // Save the refresh_token in DB
    // Save access_token timeout time of one hour in DB
    $cliq_token_exp = Carbon::now()->addHour()->timestamp
}

4. Make sure to get new access_token after every hour using refresh_token

Request:

POST
https://cliq.zoho.com/oauth/v2/token

Form Parameters:

ParameterDescription
client_idClient id obtained during client registration.
client_secretClient secret obtained during client registration.
redirect_uriRedirect uri mentioned during client registration.
grant_typerefresh_token
scopeFor sending Messages via Cliq, it’s ZohoCliq.Webhooks.CREATE
refresh_tokenThe refresh token obtained during access token generation.

Implementation:

$refresh_token = fromDB();
$cliq_token_exp = fromDB();
$cliq_token_exp = intval($cliq_token_exp);
// Check if Access Token has expired (1 hour)
if(Carbon::now()->timestamp >= $cliq_token_exp) {
    // Regenerate access_token
    $client = new Client([
        'base_uri' => 'https://accounts.zoho.com/oauth/v2/',
        'timeout'  => 10.0,
    ]);
    $params = [
        'client_id'   => config("cliq.client_id"),
        'client_secret' => config("cliq.client_secret"),
        'redirect_uri'    => url('/cliq-redirect'),
        'grant_type'  => 'refresh_token',
        'scope'       => 'ZohoCliq.Webhooks.CREATE',
        'refresh_token' => $refresh_token,
    ];
    $response = $client->request('POST', 'token', [
        'form_params' => $params
    ]);
    $body = json_decode($response->getBody());
    if(isset($body->access_token)) {
        // Save the access_token in DB
        // Save access_token timeout time of one hour in DB
        $cliq_token_exp = Carbon::now()->addHour()->timestamp
    }
}

5. Send Message as a Bot to it’s Subscribers

Request:

POST
https://cliq.zoho.com/api/v2/bots/{BOT_UNIQUE_NAME}/message

Payload:

{
  "text": "Hello there",
  "broadcast": "true"
}

Implementation:

$payload = [
    "text" => "Hello there",
    "broadcast" => "true"
];
$client = new Client([
    'base_uri' => 'https://cliq.zoho.com/api/v2/',
    'timeout'  => 10.0,
]);
$response = $client->request('POST', 'bots/'.config("cliq.default_bot").'/message', [
    'json' => $payload,
    'headers' => [
        'Authorization'   => 'Zoho-oauthtoken  '.$access_token,
        'Content-Type'        => 'application/json'
    ]
]);

6. Send Message to Channel

Request:

POST
https://cliq.zoho.com/api/v2/channelsbyname/{CHANNEL_UNIQUE_NAME}/message

Payload:

{
  "text": "Hello there",
}

Implementation:

$payload = [
    "text" => "Hello there",
];
$client = new Client([
    'base_uri' => 'https://cliq.zoho.com/api/v2/',
    'timeout'  => 10.0,
]);
$response = $client->request('POST', 'channelsbyname/'.config("cliq.default_channel")."/message", [
    'json' => $payload,
    'headers' => [
        'Authorization'   => 'Zoho-oauthtoken  '.$access_token,
        'Content-Type'        => 'application/json'
    ]
]);

I hope this helps you in achieving the proper implementation. You can create a dedicated CliqController to handle auth and redirect requests and CliqAPI Helper to create the API calls. Make sure to create proper CliqNotification in Laravel along with a JobCliqNotification to actually send the Notification.

For any issues in Implementation please put comment below.