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