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:

Parameter Description
scope For sending Messages via Cliq, it's ZohoCliq.Webhooks.CREATE
client_id Client id obtained during client registration.
state A generated value that correlates the callback with its associated authorization request
response_type code
redirect_uri Redirect uri mentioned during client registration.
access_type Access 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:

Parameter Description
code Authorization code obtained during grant token generation.
client_id Client id obtained during client registration.
client_secret Client secret obtained during client registration.
redirect_uri Redirect uri mentioned during client registration.
grant_type authorization_code
scope For sending Messages via Cliq, it's ZohoCliq.Webhooks.CREATE
state A 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:

Parameter Description
client_id Client id obtained during client registration.
client_secret Client secret obtained during client registration.
redirect_uri Redirect uri mentioned during client registration.
grant_type refresh_token
scope For sending Messages via Cliq, it's ZohoCliq.Webhooks.CREATE
refresh_token The 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.

Leave a Reply

Your email address will not be published. Required fields are marked *


The reCAPTCHA verification period has expired. Please reload the page.