How To Get Started

How to get started

Glossary

The following is a glossary list, with descriptions, that will be used in the rest of this section.

Activation Script: The piece of code that you will write to make a Lead App available in the Lead App Store for all the LeadDesk clients. For instance, if there is a Lead App called “Counting Leads”, and you need to make it available in the Lead App Store, you have to write an activation script. That script will be added by LeadDesk to a list where it will be called when activation is requested by the client.
Activation API: The API that your activation script send requests to in order to activate the Lead App for a specific client. For example, if there is a Lead App called “Counting Leads” in the Lead App Store, and a LeadDesk client wants to activate it, the activation script from above will send a request to the Activation API in order to activate the Lead App for that client.

Activation

It is as easy as sending an activation request to our “Activation API”. The API accepts JSON only, and what needs to be sent is specified in the following sections.

For quick examples, you can find some in PHP.

The Endpoint

The request of the activation should be sent as a POST request to the following endpoint: https://pygration.leaddesk.com/leadapps_proxy/api/activate/

The following will show the data that the activation API needs to activate the Lead App.

Data To Send To The Activation API

The activation script should send the API key, the activation type, and the configurations object.

Getting The API Key

The API key will be passed along as a get param in the URL alongside with others. Here is the list of all the params that are passed to the activation script: action, client_id, and API_key.

?action=activate&client_id=CLIENT_ID&API_key=API_KEY

The API key should be assigned to api_key which is part of the JSON object that is being sent to the activation endpoint.

For example:

<span class="token string">"api_key"</span><span class="token punctuation">:</span> <span class="token string">"hf73ks0vc0sl7asdbvxmf8sd0gfn"</span>

Activation Type

The activation type is one of the following three values: page, app_function, page_block. It basically telling the API how to activate the application. This is chosen by the developer according to the needs.

For example:

<span class="token string">"activation_type"</span><span class="token punctuation">:</span> <span class="token string">"app_function"</span>

Config

The config object is the last thing that need to be added to the activation JSON object. It contains all the data that is needed to activate the Lead App, and they differ according to the activation_type: page, page block, and app function.

The following section will discuss the activation configurations for each type.

What The Activation Script Should Return

The activation code that the developer is writing should return a JSON object with the following structure.

In case of success

<span class="token punctuation">{</span>
    <span class="token string">"success"</span><span class="token punctuation">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span>
    <span class="token string">"message"</span><span class="token punctuation">:</span> <span class="token string">"Custom message to be displayed to customer"</span>
<span class="token punctuation">}</span>

In case of failure

<span class="token punctuation">{</span>
    <span class="token string">"success"</span><span class="token punctuation">:</span> <span class="token boolean">false</span><span class="token punctuation">,</span>
    <span class="token string">"message"</span><span class="token punctuation">:</span> <span class="token string">"Custom message to be displayed to customer"</span>
<span class="token punctuation">}</span>

Redirect URL could be included as well (optional)

The redirect URL will redirect the to the specified value after activation.

<span class="token punctuation">{</span>
    <span class="token string">"success"</span><span class="token punctuation">:</span> <span class="token boolean">true</span><span class="token punctuation">,</span>
    <span class="token string">"message"</span><span class="token punctuation">:</span> <span class="token string">"Custom message to be displayed to customer"</span><span class="token punctuation">,</span>
    <span class="token string">"redirect"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com"</span>
<span class="token punctuation">}</span>

Activation Config Object

Each activation type has its own set of properties in the config object, so let’s display the list of all the possible properties with a small description.

height: the height of the iframe that loads the app in pixels.
width: the width of the iframe that loads the app in pixels.
name: the lead app name. The name is used to be displayed in the LeadDesk admin view. For example, when the “Calendar Meetings” lead app is activated as a “page”, it will appear with that name in the navigation.
location: where the lead app will be loaded, which differs depending on the activation type. For instance, when the “Calendar Meetings” lead app is activated as a “page” and the location was “dashboard”, it will appear with that name in the navigation under the dashboard page.
url: the app URL.
sandbox: the iframe sandbox attributes. Multiple values could be sent separated by space.
icon: this value can point directly to an URL holding the icon image.

Note: In all the activation types, name, location, and url are mandatory.

Page Activation

The “page” activation type will make the app accessible as a page under the secondary navigation bar. For instance, the “Meeting Calendar” is a lead app that if activated will appear under “Dashboard”.

To activate the lead app as page, besides the mandatory properties (name, location, and url), the config object accepts sandbox and height.

sandboxlocation‘s value must be one of the following: dashboard, statistics, campaigns, agents_mng, calling_list_management, product, b2b_mng, qatab, inbound, general_settings.
sandbox‘s value is of the following: allow-forms, allow-pointer-lock, allow-popups, allow-same-origin, allow-scripts, allow-top-navigation. Multiple values should be separated by a space.

Example:

<span class="token punctuation">{</span>
    <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
    <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"dashboard"</span><span class="token punctuation">,</span>
    <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
    <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
    <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">" https://www.example.com/my/lead/app"</span>
<span class="token punctuation">}</span>

And the whole JSON object could look something like the following.

<span class="token punctuation">{</span>
    <span class="token string">"api_key"</span><span class="token punctuation">:</span> <span class="token string">"hf73ks0vc0sl7asdbvxmf8sd0gfn"</span><span class="token punctuation">,</span>
    <span class="token string">"activation_type"</span><span class="token punctuation">:</span> <span class="token string">"page"</span><span class="token punctuation">,</span>
    <span class="token string">"config"</span><span class="token punctuation">:</span> <span class="token punctuation">{</span>
        <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
        <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"dashboard"</span><span class="token punctuation">,</span>
        <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
        <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
        <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">" https://www.example.com/my/lead/app"</span>
    <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

Page Block Activation

The “page_block” activation type will make the app displayed as a block. Usually, this type of activation is used to include some configuration that goes along with an app. For instance, there is an app in the LeadApp store called “Live performance report” which requires some configuration to work the way that the customer desire. That configuration is being added to as a “page_block”.

To activate the lead app as page block, besides the mandatory properties (name, location, and url), the config object accepts sandbox and height.

location‘s value must be one of the following: campaign-editor.
sandbox‘s value is of the following: allow-forms, allow-pointer-lock, allow-popups, allow-same-origin, allow-scripts, allow-top-navigation. Multiple values should be separated by a space.

Example:

<span class="token punctuation">{</span>
    <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">300</span><span class="token punctuation">,</span>
    <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"campaign-editor"</span><span class="token punctuation">,</span>
    <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
    <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
    <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app"</span>
<span class="token punctuation">}</span>

And the whole JSON object could look something like the following.

<span class="token punctuation">{</span>
    <span class="token string">"api_key"</span><span class="token punctuation">:</span> <span class="token string">"hf73ks0vc0sl7asdbvxmf8sd0gfn"</span><span class="token punctuation">,</span>
    <span class="token string">"activation_type"</span><span class="token punctuation">:</span> <span class="token string">"page_block"</span><span class="token punctuation">,</span>
    <span class="token string">"config"</span><span class="token punctuation">:</span> <span class="token punctuation">{</span>
        <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">300</span><span class="token punctuation">,</span>
        <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"campaign-editor"</span><span class="token punctuation">,</span>
        <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
        <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
        <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app"</span>
    <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

App Function Activation

The “app_function” activation type will make the app accessible as a stand alone app under the “contact lists” next to each list there.

For instance, “SmartData” is activated as an “app_function”, and the icon that represent it from the previous is.

Clicking that will launch the app in an external pop-up.

To activate the lead app as app function, besides the mandatory properties (name, location, and url), the config object accepts sandbox, height, width, and icon.

location‘s value must be one of the following: admin.contact-lists.toolbar, admin.campaign-list.toolbar.
sandbox‘s value is of the following: allow-forms, allow-pointer-lock, allow-popups, allow-same-origin, allow-scripts, allow-top-navigation. Multiple values should be separated by a space.

Example:

<span class="token punctuation">{</span>
    <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
    <span class="token string">"width"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
    <span class="token string">"icon"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app/icon.png"</span><span class="token punctuation">,</span>
    <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"admin.contact-lists.toolbar"</span><span class="token punctuation">,</span>
    <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
    <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
    <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app"</span>
<span class="token punctuation">}</span>

And the whole JSON object could look something like the following.

<span class="token punctuation">{</span>
    <span class="token string">"api_key"</span><span class="token punctuation">:</span> <span class="token string">"hf73ks0vc0sl7asdbvxmf8sd0gfn"</span><span class="token punctuation">,</span>
    <span class="token string">"activation_type"</span><span class="token punctuation">:</span> <span class="token string">"app_function"</span><span class="token punctuation">,</span>
    <span class="token string">"config"</span><span class="token punctuation">:</span> <span class="token punctuation">{</span>
        <span class="token string">"height"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
        <span class="token string">"width"</span><span class="token punctuation">:</span> <span class="token number">700</span><span class="token punctuation">,</span>
        <span class="token string">"icon"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app/icon.png"</span><span class="token punctuation">,</span>
        <span class="token string">"location"</span><span class="token punctuation">:</span> <span class="token string">"admin.contact-lists.toolbar"</span><span class="token punctuation">,</span>
        <span class="token string">"name"</span><span class="token punctuation">:</span> <span class="token string">"My Lead App Name"</span><span class="token punctuation">,</span>
        <span class="token string">"sandbox"</span><span class="token punctuation">:</span> <span class="token string">"allow-forms allow-popups"</span><span class="token punctuation">,</span>
        <span class="token string">"url"</span><span class="token punctuation">:</span> <span class="token string">"https://www.example.com/my/lead/app"</span>
    <span class="token punctuation">}</span>
<span class="token punctuation">}</span>

Examples

You can refer to the reference page if you want to check the responses of activation endpoint.Examples in PHP are available as well.