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.
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.
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.
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.
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.
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.
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
Returns
This method returns a connectedAccountId (string).
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
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
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
Returns
This method returns an array of connected_accounts.
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.
constparams= { 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
Returns
This method returns a result object with the filled-in arguments.
{"channel":"random","text":"hello world from the other side"}
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.
constparams= { 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
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:
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:
// 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": [] } }}
// 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" }}
// 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')`"
]}
// 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
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" ] }}