Integrate Zoho Cliq OAuth API in PHP Laravel using Guzzle

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:

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:

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:

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.