JS SDK Reference

This reference documents every object and method available in Integry’s browser-side JavaScript library, Integry.js.

Setting Up

Including Integry.js

To use the Integry JS SDK, you need to include it in your project. You can install it via npm:

npm install @integry/sdk

Or include it via a script tag:

<script src="https://unpkg.com/@integry/sdk/dist/umd/index.umd.js"></script>

Authentication

The Integry JS SDK requires an App-Key and a hash of App-Secret and User-ID to authenticate calls.

You can view and copy your App-Key and App-Secret from the Integry app.

User-ID is a unique string identifier for a user in your app. Function Calls and Integrations are associated to a user ID.

If your app has workspaces/accounts and you want integrations to be shared across all users in a workspace/account, use the workspace/account ID as the user ID.

Calculating the hash

Calculate the hash server-side using HMAC SHA256.

JS

const crypto = require("crypto");

const userId = "";
const appSecret = "";

const hash = crypto
.createHmac("sha256", appSecret)
.update(userId)
.digest("hex");

Python

import hmac
import hashlib

app_secret = b"<app_secret>"
user_id = b"<user_id>"

hash = hmac.new(app_secret, user_id, hashlib.sha256).hexdigest()

PHP

<?php

$appSecret = '<APP_SECRET>';
$userId = '<USER_ID>';
$hash = hash_hmac('sha256', $userId, $appSecret);

Initializing IntegryJS()

Call IntegryJS(authentication) with theApp-Key, computed hash and User-ID to create an instance of the Integry object.

const userId = "USER_ID"; // Your user's ID
const appKey = "YOUR_INTEGRY_APP_KEY";
const hash = "YOUR_GENERATED_HASH";

const integry = new IntegryJS({
    appKey,
    hash,
    user: {
        userId: userId,
    },
});

Emits event

This method emits a ready event if the access credentials are valid.

Listening to Events

Some SDK methods emit events (eg. ready, app-connected) that you can leverage to manipulate the user journey.

Subscribe to an event

Call eventEmitter.on('<event_name>') method​.

integry.eventEmitter.on('app-connected', (data) => {
    //do something here
});

Events emitted by the SDK are scoped to the instance on which the eventEmitter object is configured. There is no possibility of naming collision with global events, or even with the same event subscribed on multiple SDK instances.

Unsubscribe from an event

Call eventEmitter.unsub('<event_name>') method.

integry.eventEmitter.on('app-disconnected', (data) => {
    //do something here
});

Error Handling

All methods in the Integry JS SDK return Promises. It is recommended to always include .catch() to handle errors gracefully. Here is an example:

integry.connectApp("slack").then((connectedAccountId) => {
  console.log("Connected to Slack with account ID:", connectedAccountId);
}).catch((error) => {
  console.error("An error occurred:", error);
});

Apps

Integry supports many apps like Slack, Hubspot, or Jira.

Show apps

showApps(apps, renderMode, containerID)

Renders a marketplace-style listing of apps. You can show all apps or specific apps.

If you want to directly connect an app from your own marketplace, use connect(appName).

integry.showApps(
  ["slack", "mailchimp"],
  IntegryJS.MarketplaceRenderModes.INLINE,
  "marketplace-container"
).then(() => {
  console.log("Marketplace rendered in-line with specific apps.");
}).catch((error) => {
  console.error("Error rendering filtered marketplace:", error);
});

Method parameters

Name	Type	Description	Required
apps	string[]	A list of specific apps to show. Defaults to [] to show all apps.	false
renderMode	string	Specifies the mode in which the marketplace will be rendered. Allowed values: IntegryJS.MarketplaceRenderModes.MODAL, IntegryJS.MarketplaceRenderModes.INLINE. Defaults to modal if not specified.	false
containerId	string	The ID of the HTML container in which the marketplace content will be rendered.	true if renderMode=IntegryJS.MarketplaceRenderModes.INLINE

Emits events

app-connected

Fired when the user successfully connects an app. It includes the app details along with an array of connected_accounts sorted by modified_at in descending order.

{
    "id": 410,
    "name": "pipedrive",
    "title": "Pipedrive",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
    "docs_url": "",
    "connected_accounts": [
        {
            "id": 247714,
            "display_name": "663----------8b1",
            "modified_at": "2024-11-10T23:28:58Z"
        }
    ]
}

app-disconnected

Fired when the user disconnects an app. It includes the app details along with an array of remaining connected_accounts(if any) sorted by modified_at in descending order.

{
    "id": 410,
    "name": "pipedrive",
    "title": "Pipedrive",
    "icon_url": "https://storage.googleapis.com/app-services-prod--bucket/public/c07f082e-33d2-499f-b67a-d98722ab367b.png",
    "docs_url": "",
    "connected_accounts": []
}

Connect an app

connectApp(appName)

Invokes a UI flow to prompt the user to authenticate with the specified app. After the user connects, Integry verifies that it can access their account. It also refreshes the token, if needed.

Use this to connect apps if you are not using showApps() .

integry.connectApp("slack").then((connectedAccountId) => {
  console.log("Connected to Slack with account ID:", connectedAccountId);
}).catch((error) => {
  console.error("Failed to connect to Slack:", error);
});

Method parameters

Name	Type	Description	Example	Required
appName	string	The name of the app you want the user to connect.	slack	true

Returns

This method returns a connectedAccountId (string).

If you use connectApp()to enable your users to connect multiple accounts for an app, you will need to use this ID when you disconnectApp(), showFunctionUI() and invokeFunction().

Disconnect an app

disconnectApp(appName, connectedAccountId)

Disconnects the user's connected account for an app.

integry.disconnectApp("slack").then(() => {
  console.log("Successfully disconnected from Slack");
}).catch((error) => {
  console.error("Failed to disconnect from Slack:", error);
});

Method parameters

Name	Type	Description	Example	Required
appName	string	The name of the app to disconnect.	slack	true
connectedAccountId	string	The ID of the connected account to delete.	1234	true if the user has multiple connected accounts of this app

Returns

This method returns a Promise which resolves if the account is disconnected.

Check if app is connected

isAppConnected(appName)

Checks if the user has connected the specified app.

integry.isAppConnected("slack").then((result) => {
  if(result) {
    console.log("User has connected Slack.");
  } else {
    console.log("User has not connected Slack.");
  }
  
}).catch((error) => {
  console.error("Failed to determine auth status:", error);
});

Method parameters

Name	Type	Description	Example	Required
appName	string	The name of the app.	slack	true

Returns

This method returns a boolean result. It will be true if the user has one (or more) connected account(s) with this app.

If your users have connected multiple accounts, use getConnectedAccounts() to get their IDs.

Get connected accounts of an app

getConnectedAccounts(appName)

Returns a user's connected accounts for an app.

Method parameters

Name	Type	Description	Example	Required
appName	string	The name of the app.	slack	true

Returns

This method returns an array of connected_accounts.

{
    "connected_accounts": [
        {
            "id": 247714,
            "display_name": "663----------8b1",
            "modified_at": "2024-11-10T23:28:58Z"
        }
    ]
}

Functions

Show the function UI

showFunctionUI(functionName, params, connectedAccountId)

Renders the UI for a specific function. This method shows the user a pre-filled form based on the provided action ID and parameters, allowing them to review and confirm the action before executing it.

const params = {
  channel: "general",
  message: "Hello, team!"
};

integry.showFunctionUI("slack-post-message", params, "abc123").then((result) => {
  console.log("Function parameters filled-in by the user:", result);
}).catch((error) => {
  console.error("Failed to load function UI:", error);
});

Method parameters

Name	Type	Description	Example	Required
functionName	string	The name of the function to render.	slack-post-message	true
params	object	An object containing the function parameters.	{"limit":5}	true
connectedAccountId	string	The connected account to use for executing the action. Only use if the user has connected multiple accounts.	12456	false

Returns

This method returns a result object with the filled-in arguments.

{
        "channel":"random",
        "text":"hello world from the other side"
}

Use it as params to invokeFunction().

Call a function

invokeFunction(functionName, params, connectedAccountId)

Invokes the specified function of an app with the provided parameters. Integry will automatically include your user's authentication credentials when making the onwards API call.

Integry will execute the function if the user has already connected their account for the function app, and all required parameters (if any) are provided in params. These function calls will show in the Function Calls log in the Integry app.

Integry will not execute the function if the user has not connected an account, or the parameters passed are invalid. These function calls will not show in the Function Calls log.

const params = {
  channel: "random",
  message: "hello world from the other side"
};
integry.invokeFunction("slack-post-message", params).then((result) => {
  console.log("Received response from Slack:", result);
}).catch((error) => {
  console.error("Failed to invoke function:", error);
});

Method parameters

Name	Type	Description	Example	Required
functionName	string	The name of the function to execute	slack-post-message	true
params	object	An object containing the function parameters.	{"limit":5}	true
connectedAccountId	string	The connected account to use for executing the action. Only use if the user has connected multiple accounts.	43654	false

Sample params object for pipedrive-add-a-person function call:

{
    "name": "Sample contact"
}

The functions which fetch data from an app will often return pages of data and allow you to fetch further data by making subsequent calls. These functions use cursor-based pagination via the next_page parameter that is returned in the result (if there are more pages).

Sample params object for pipedrive-get-all-persons function call with next_page:

{
    "limit": 5,
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

Returns

If Integry executes the function, this method returns a result object with following keys:

• network_code: HTTP response status code of the onwards API call made by Integry.

• output: HTTP response body of the onwards API call made by Integry.

• next_page: The cursor for the next page. It will only be present in responses of functions that support paginated calls. If there are no more pages, it will be empty.

If Integry does not execute the function, this method returns a result object with following keys:

• error: Summary of the error.

• error_details[]: Detailed errors for individual fields (if applicable).

Sample responses for pipedrive-add-a-person and pipedrive-get-all-persons:

Result 1

// Function name: pipedrive-add-a-person
// Outcome: Person was created
{
    "network_code": "200",
    "output": {
        "success": true,
        "data": {
            "id": 27,
            "name": "Sample contact",
            "first_name": "Sample",
            "last_name": "contact",
            "add_time": "2024-11-11T17:18:18Z",
            "update_time": null,
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [],
            "emails": []
        }
    }
}

Result 2

// Function name: pipedrive-add-a-person
// Outcome: Validation error
{
    "network_code": "400",
    "output": {
        "success": false,
        "error": "Validation failed: owner_id: User not found or not accessible.",
        "code": "ERR_SCHEMA_VALIDATION_FAILED"
    }
}

Result 3 (with next_page)

// Function name: pipedrive-get-all-persons
// Outcome: Data was fetched with a next_page cursor.
{
    "network_code": "200",
    "output": [
        {
            "id": 1,
            "name": "[Sample] Phyllis Yang",
            "first_name": "[Sample] Phyllis",
            "last_name": "Yang",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-11T00:52:38Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [
                14
            ],
            "org_id": 5,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "240-707-3884",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "[e-mail]",
                    "primary": true
                }
            ]
        },
        {
            "id": 2,
            "name": "[Sample] Tony Turner",
            "first_name": "[Sample] Tony",
            "last_name": "Turner",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 1,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "218-348-8528",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "[e-mail]",
                    "primary": true
                }
            ]
        },
        {
            "id": 3,
            "name": "[Sample] Gloria Quinn",
            "first_name": "[Sample] Gloria",
            "last_name": "Quinn",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 2,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "862-252-9773",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "[e-mail]",
                    "primary": true
                }
            ]
        },
        {
            "id": 4,
            "name": "[Sample] Benjamin Leon",
            "first_name": "[Sample] Benjamin",
            "last_name": "Leon",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": null,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "785-202-7824",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "[e-mail]",
                    "primary": true
                }
            ]
        },
        {
            "id": 5,
            "name": "[Sample] Otto Miller",
            "first_name": "[Sample] Otto",
            "last_name": "Miller",
            "add_time": "2024-11-10T23:28:58Z",
            "update_time": "2024-11-10T23:29:05Z",
            "visible_to": 3,
            "custom_fields": null,
            "owner_id": 22469411,
            "label_ids": [],
            "org_id": 3,
            "is_deleted": false,
            "picture_id": null,
            "phones": [
                {
                    "label": "",
                    "value": "601-906-7534",
                    "primary": true
                }
            ],
            "emails": [
                {
                    "label": "work",
                    "value": "[e-mail]",
                    "primary": true
                }
            ]
        }
    ],
    "next_page": "eyJmaWVsZCI6ImlkIiwiZmllbGRWYWx1ZSI6Niwic29ydERpcmVjdGlvbiI6ImFzYyIsImlkIjo2fQ"
}

Error 1

// Function name: pipedrive-add-a-person
// Outcome: Error -- app was not connected
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": [
        "User has not connected their Pipedrive account. To connect an account, please call following SDK method: `connect('pipedrive')`"
    ]
}

Error 2

// Function name: pipedrive-add-a-person
// Outcome: Error -- required parameter was missing
{
    "error": "Could not call the function due to invalid input. Please see `error_details` for further information.",
    "error_details": {
        "name": "This parameter is required and must not be null or empty"
    }
}

In rare cases where Integry is unable to determine if there are more pages, it will respond with a next_page cursor. Your subsequent call will return an empty output[] and next_page cursor since there are no more pages.

Get a function

getFunction(functionName)

Gets the signature for a specific function to understand the parameters.

integry.getFunction("slack-post-message").then((result) => {
  console.log("Function signature:", result);
}).catch((error) => {
  console.error("Failed to get function signature:", error);
});

Method parameters

Name	Type	Description	Example	Required
functionName	string	The name of the function to execute	slack-post-message	true

Returns

This method returns a result object with the function's signature.

{
    "name": "slack-post-message",
    "description": "Post a message in a channel",
    "parameters": {
        "type": "object",
        "properties": {
            "text": {
                "type": "string",
                "description": "The content of the message."
            },
            "channel": {
                "type": "string",
                "description": "The channel to send the message in. Call `slack-list-conversations` to get the available values."
            },
            "as_user": {
                "type": "boolean",
                "description": "(Legacy) Pass true to post the message as the authed user instead of as a bot. Defaults to false. Can only be used by classic apps."
            },
            "attachments": {
                "type": "string",
                "description": "A JSON-based array of structured attachments, presented as a URL-encoded string."
            },
            "blocks": {
                "type": "array",
                "description": "A JSON-based array of structured blocks, presented as a URL-encoded string.",
                "items": {
                    "type": "string"
                }
            },
            "icon_emoji": {
                "type": "string",
                "description": "Emoji to use as the icon for this message. Overrides icon_url."
            },
            "icon_url": {
                "type": "string",
                "description": "URL to an image to use as the icon for this message."
            },
            "link_names": {
                "type": "boolean",
                "description": "Find and link user groups. No longer supports linking individual users; use syntax shown in Mentioning Users instead."
            },
            "metadata": {
                "type": "string",
                "description": "JSON object with event_type and event_payload fields, presented as a URL-encoded string. Metadata you post to Slack is accessible to any app or user who is a member of that workspace."
            },
            "mrkdwn": {
                "type": "boolean",
                "description": "Disable Slack markup parsing by setting to false. Enabled by default."
            },
            "parse": {
                "type": "string",
                "description": "Change how messages are treated."
            },
            "reply_broadcast": {
                "type": "boolean",
                "description": "Used in conjunction with thread_ts and indicates whether reply should be made visible to everyone in the channel or conversation. Defaults to false."
            },
            "thread_ts": {
                "type": "string",
                "description": "Provide another message's ts value to make this message a reply. Avoid using a reply's ts value; use its parent instead."
            },
            "unfurl_links": {
                "type": "boolean",
                "description": "Pass true to enable unfurling of primarily text-based content."
            },
            "unfurl_media": {
                "type": "boolean",
                "description": "Pass false to disable unfurling of media content."
            },
            "username": {
                "type": "string",
                "description": "Set your bot's user name."
            }
        },
        "required": [
            "text",
            "channel"
        ]
    }
}