Building Extensions

What are extensions?

Extensions are bundles of practicable code integrations, containing commands, bots, message actions, functions, schedulers and databases combined together to suit your client or user requirements. Extensions created by you are listed under the My Extensions section. The extensions installed from Zoho Marketplace are listed under the Installed Extensions section.   

How to build an extension?  

Building an extension isn't as daunting as it sounds. Follow the steps below to create an extension:

• First, create the commands, bots, message actions, functions, schedulers and databases that you would like to bundle together as an extension. These components are the building blocks of your Extension. Refer to internal tools for more information on how to create them. Once you have all the above-mentioned components ready, you can make your Extension.
• Click your display picture, select Bots & Tools and click on Extensions.
• Click Create Extension and give your Extension a name, description, and image based on the use case and select the commands, bots, message actions, image and select the commands, widgets, functions, schedulers and databases which you would wish to bundle into the Extension.
• The components of the Extension are categorised individually, and you can use the search bar in the right corner to select/deselect while bundling. You can view all components or collapse them all for easy navigation. Check the 'Sort selected only' checkbox to list only the ones that have been selected for bundling as an extension.
• A maximum of 4 integration components, such as commands, message actions, schedulers, one bot, one widget, 20 functions, and six databases, can be added together as an extension.
• Links can be configured for an Extension by adding specific domains under the Link handlers section.
• Once you have selected the components to be included, select the Create button to get the first version of your Extension ready.  Simultaneously, a sandbox version of your Extension will be installed along with the extension components (internal tools).
• The sandbox version of your Extension should be used for developing extension upgrades and publishing them.
• This Extension will be listed under the My Extensions section. You can either publish or edit it further.  

Here's how you can create an extension 

Sandbox Version

A sandbox extension is just a production replica of your extension. The extensions created and listed under the My Extensions sections are the sandbox versions. This allows you to test the extension for issues before proceeding to publish in the marketplace. Once an extension is created, all the components bundled in the extension will also have a sandbox version created and listed under their respective sections. To publish an upgrade to your extension, you will have to edit the code present in the component's sandbox version. 

For example, the Asana extension can have a @Asana bot and an /asana command. Upon creating the extension, sandbox versions of the @Asana bot and /asana command are created. Any changes in the bot or command's functionality will have to be made in this sandbox version of the command and bot and can be pushed live as an upgrade. 

Extension Connectors

Extension connectors are basically components that play a major role in authenticating and integrating your extension with the third party service. 

App Key

The App key is a unique identifier for your extension and is mandatory for authentication. This key has to be sent as a request parameter with the param name appkey for all endpoints. Each extension is provided with two app keys, the Sandbox App key and the Marketplace App key by default. App keys are like a token for your extensions and must be used in all API endpoints.  The sandbox app key can be used while testing the extension in the sandbox environment. You can also generate a new set of App keys by clicking the Generate option. A maximum of only 3 App Keys can be generated at any given point of time. 

Incoming Webhook Endpoint

The extension's incoming webhook endpoints can be used to register the extension with a third party application to receive custom callbacks. The incoming webhook endpoint should also be authenticated with the extension's app key and the zapi key. Callbacks to this endpoint can be handled in the extension's incoming webhook handler, wherein you can decide to direct the response to a channel or bot added in the extension. The extension incoming webhook endpoint syntax is given below

//Sample Extension Incoming Webhook Endpoint
https://cliq.zoho.com/api/v2/applications/{app_id}/incoming?appkey={app_key}

Extension Handlers

Each extension includes a predefined set of four handlers that enable developers to configure and customise various extension behaviours, such as installation, validation, uninstallation, and managing incoming webhooks settings. In addition, Link Handlers provide control over how links and domains associated with the extension are handled, such as unfurled link previews and actions related to these previews, for a richer user experience.

Editing an extension

Only extensions that you create can be edited. To edit an extension, hover over the extension name and click Edit.

Editing an extension before publishing:

Cliq permits you to change the extension description, image and even alter the components you would like to bundle. Just unchecking a previously added component will remove it from the extension bundle. 

Editing an extension after publishing:  

Once an extension is published, the extension name cannot be edited. Only the extension description, image, and the components can be edited. 

Deleting an extension

Delete an extension by clicking on the extension name. The extension preview page has the 'Delete' extension button at the bottom. Note that deleting will not delete the extension from the marketplace. After deleting an extension it cannot be retrieved back and cannot be edited in the marketplace after being deleted.