Invoke URL

 

Invoke URL task

An Invoke URL task is used to access third party services from Cliq through Connections. The Invoke URL task supports four HTTP methods, GET, POST, PUT, DELETE.

Sample Invoke URL task

response=invokeUrl                    
[
*url: <url>
*type: <GET/PUT/POST/DELETE>
parameters: <parameters>        
headers: <headers>             
connection: <connection name>  
files: <file object>            
]; 
//All mandatory parameters are marked with an *

 

A list of parameters is passed when the invoke URL task is executed. They are explained in this table. 

ParametersDescriptionRequisite
urlThe resource URL from the third party service used to perform various operations.Mandatory
typeHTTP Methods: GET | PUT | POST | DELETEMandatory
parametersTo send additional params of the form data type in the request URL. Optional
headersHeaders are used to specify the request header parameters.Optional
connectionThe name of the connection to be used.Optional
filesThe file object.Optional

How to use the invoke URL task 

Let us consider an integration between Cliq and Twitter, wherein you'll be able to tweet right from Cliq. For this integration to work, start by creating a connection with Twitter.

  1. Create the connection by choosing Twitter from the pre-registered service. 
  2. Give a Connection Name and configure the Use Credentials of Login User option according to your requirement. If the option is enabled, it will work with every user's authentication and in case the option is not enabled, the connection will use the admin (connection owner) authentication.
  3. Upon creating the connection, an invoke URL task will be generated. 
  4. Now, create a /tweet command in Cliq.
  5. The invoke URL deluge script should be used in the command execution code to let you post tweets from Cliq. 

The twitter resource URL that lets you post/update tweets is given below. Refer Twitter API References for more information.


https://api.twitter.com/1.1/statuses/update.json

 

Take a look at the sample invoke URL deluge script for connecting to twitter. The following deluge script, when executed will tweet your message directly from Cliq. 


response=invokeUrl
[
url: "https://api.twitter.com/1.1/statuses/update.json?status=" + tweetMessage
type: POST
connection: //Enter your connection name
];

 

The params and their description are given below

  • url: Provide the post tweets/updates twitter API
  • type: The HTTP method for this request is POST
  • connection: Give the connection name. Use credentials of login user (checkbox): Enabling this option will ask permission from the user to access their twitter account; which means — the connection will work with the user's authentication. In case this checkbox is disabled, the connection will work with the connection owner (creator) authentication. 

Note:

First time authentication —The first time the /tweet command is triggered, the invoke URL task is executed and the user is prompted to provide access to post on their behalf and on giving access, the message is directly posted to the user's twitter handle. 

/tweet Command

Let us now put the invoke URL task to use in a command's execution code. The /tweet command can be used to post tweets directly from Cliq. The tweet to be posted is given as arguments during command execution. Refer the command execution handler to understand more. 



result = Map();
//User passes the tweet as arguments along with the command
tweet = arguments;

response = invokeurl
[
	url :"https://api.twitter.com/1.1/statuses/update.json?status=" + tweet
	type :POST
	connection: // Give your connection name
];
info response;

//Get the user's twitter screen name handle name and the tweet's unique ID

user_name = response.get("user").get("screen_name");
info user_name;
id = response.get("id_str");

// Frame the command's execution response

result = {"text":"Your tweet has been posted successfully! Here is the link to [view it](https://twitter.com/" + user_name + "/status/" + id + ")","card":{"title":"Tweeted!","thumbnail":"","theme":"modern-inline"}};

// Return the response to the user

return result;

 

Take a look at the GIF below to understand how the /tweet command is executed to post tweets directly from Cliq. 

/tweet command execution

Apart from the mandatory parameters, there are a few additional parameters that can be used in the invoke URL task. 

How to use the headers parameter in the invoke URL task 

Headers in REST

HTTP Headers are an important part of an API request and the corresponding response. They represent the metadata associated with the API request and response for the following

  • API request and Response body
  • Authorization Requests
  • Response Caching 
  • Response Cookies

Some of the most common headers that needs to be passed with an API request are:

  • Authorization: Authentication credentials for the resource being requested
  • Content-Type: Indicates the media type of the resource

Message Action - Upload files to Google Drive

Take for example, a message action to upload files shared in Cliq directly to your Google Drive account. For this integration to work, create an integration with Google Drive. The google drive resource URI for uploading files is given below. Refer Drive API references for more information

​
https://www.googleapis.com/upload/drive/v3/files

 

A sample invoke URL deluge script for the Google Drive connection is shown below.

​
response = invokeUrl [
    url : "https://www.googleapis.com/upload/drive/v3/files"
    type : POST
    headers : gDriveHeaders
    files : gDriveFiles
    connection : // Give your connection name
];

 

The task parameters and their description are:

  • url: Give the google drive API to send attachments/ upload files.
  • type: Specify the HTTP method - POST
  • connection: Give the connection name. This connection has the use credentials of login user (user access value) set as true. When this code is executed, the user will be prompted to give access and perform integration with their own credentials.
  • headers: Specify the request headers to be passed. headers is of the data type MAP. 
  • files: The files object of the data type LIST is used to store the list of files.  

Uploading a file in Cliq to Google Drive

Add a file shared in chat directly to your GDrive account through the upload file message action. 



message = Map();
file = attachments.get(0);
params = Map();
params.put("name",file);
comments = Map();
comments.put("stringPart","true");
comments.put("paramName","metadata");
comments.put("content",params.toString());
comments.put("contentType","application/json");
comments.put("encodingType","UTF-8");
fileList = List();
fileList.add(comments);
fileList.add(file);
driveHeaders = Map();
driveHeaders.put("Content-Type","multipart/related");
response = invokeurl
[
	url :"https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart"
	type :POST
	headers:driveHeaders
	files:fileList
	connection: //Give your connection name
];
info response;
fileDetails = invokeurl
[
	url :"https://www.googleapis.com/drive/v3/files/" + encodeUrl(response.get("id")) + "?fields=name,id,webViewLink&restrictToMyDrive=true"
	type :GET
	connection: //Give your connection name
];
button = List();
if(!fileDetails.get("webViewLink").isNull())
{
	button.add({"label":"View","action":{"type":"open.url","data":{"web":fileDetails.get("webViewLink")}},"type":"+"});
}
message = {"text":"The file [" + response.get("name") + "]("+fileDetails.get("webViewLink")+") has been uploaded to your Google Drive. :thumbsup:"};
return message;

How to use the files parameter in the invoke URL task 

As an example let us again consider a message action - to upload files shared in chat directly to your Zoho Docs. The Zoho Docs resource URL to upload files is shown below. Refer Zoho Docs upload file API for more details about the query string parameters required


https://apidocs.zoho.com/files/v1/upload

 

To create a connection with Zoho Docs, follow the below given steps:

  1. Choose Zoho under the pick your service section in the Connections page
  2. Give your connection name and under scopes — select ZohoPC/docsapi 
  3. Click on Create and Connect to create the connection with Zoho Docs

A sample invoke URL deluge script for the Zoho Docs connection with the file upload API is shown below.

​
response = invokeurl
[
	url :"https://apidocs.zoho.com/files/v1/upload"
	type :POST
	files: fileslist
	connection: //Give your connection name
];
  • url: Give the Zoho Docs api to send attachments/ upload files.
  • type: Specify the HTTP method - POST
  • connection: Give the connection name. This connection has the use credentials of login user (user access value) set as true. When this code is executed, the user will be prompted to give access and perform integration with their own credentials. headers: Specify the request headers to be passed. 
  • files : The files object of the data type LIST is used to store the list of files.  

Uploading a file in Cliq to Zoho Docs

Add a file shared in chat directly to your Zoho Docs account through the Upload to ZDocs message action.


output = Map();
docsparams = Map();
att = attachments.get(0);
docsparams.put("stringPart","true");
docsparams.put("paramName","filename");
docsparams.put("content","" + att);
fileslist = List();
fileslist.add(docsparams);
att.setParamName("content");
fileslist.add(att);
response = invokeurl
[
	url :"https://apidocs.zoho.com/files/v1/upload"
	type :POST
	files:fileslist
	connection: //Give your connection name
];
info response;
result = response.get("response").toList().get(2).toList();
info result;
docid = result.toMap().get("result").toList().get(1).toMap().get("uploaddocid");
output.put("text","Uploaded to your ZOHO Docs! (y) [View in Docs](https://docs.zoho.com/file/" + docid + ")");
return output;

Using the parameters attribute in the invoke URL task

The parameters attribute of the datatype MAP can be used in the invoke URL task when an API requires you to send additional data in the request body. Let us take an example of a weekly scheduler that brings the list of major open issues in a project. The resource URL to get the list of issues from a project is given below. Refer Zoho Projects API guide for more details. 


https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/

 

The first step would be to create a connection with Zoho Projects and generate the invoke URL task. The steps to create a connection with Zoho Projects is given below

  1. Choose Zoho under the pick your service section in the Connections page
  2. Give your connection name and under scopes — select ZohoProjects/projectsapi
  3. Click on Create and Connect to create the connection with Zoho Docs

A sample invoke URL deluge script for the Zoho Projects connection with the Get all issues API is shown below.


getissues = invokeurl
[
	url :"https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/"
	type :GET
	parameters: paramsMap
	connection: //Give your connection name
];

 

The params and their description are given below

  • url: Provide the get all issues/bugs API
  • type: The HTTP method for this request is GET
  • connection: Give the connection name. Use credentials of login user (checkbox): Enabling this option will ask permission from the user to access their twitter account; which means — the connection will work with the user's authentication. In case this checkbox is disabled, the connection will work with the connection owner (creator) authentication. 
  • parameters : A map containing all the request parameters. 

Note:

In cases where the API does not accept form encoded input, the data has to be sent as JSON in the request body. You can use the .toString() function to stringify the parameters. 

The issues scheduler scipt is shown below. This scheduler will be triggered every week to pull the list of recently filed open issues with severity marked as Major and post it in a channel. 


paramsMap = Map();
paramsMap.put("statustype","open");
paramsMap.put("severity",{"Provide the severity ID"});
paramsMap.put("index",0);
paramsMap.put("range","5");
paramsMap.put("sort_order","ascending");
getissues = invokeurl
[
	url :"https://projectsapi.zoho.com/restapi/portal/[PORTAL ID]/projects/[PROJECT ID]/bugs/"
	type :GET
	parameters:paramsMap
	connection: //Give your connection name
];
info getissues;
bugs = getissues.toMap().get("bugs");
info bugs.size();
rows = List();
for each  bug in bugs
{
	row = Map();
	row.put("Issue Title",bug.get("title"));
	row.put("Issue ID",bug.get("bug_number"));
	row.put("Severity",bug.get("severity").toMap().get("type"));
	rows.add(row);
}
message = {"text":"List of Major issues pending this week.","card":{"theme":"modern-inline","title":"Issue List:"},"bot":{"name":"Team Bot","image":""},"slides":{{"type":"table","title":"","data":{"headers":{"Issue Title","Issue ID","Severity"},"rows":rows}}}};
info zoho.cliq.postToChannel(channel_unqiue_name,message);

 

Related Articles:

Connections: How to integrate Cliq with third party applications?

Learn how to connect external applications to Cliq using Connections

Share this post : FacebookTwitter

Still can't find what you're looking for?

Write to us: support@zohocliq.com