Intercom

1. Overview

Intercom is a leading customer communications platform that helps businesses connect with customers through various channels like live chat, email, and messages to enhance customer support, engagement, and sales conversion.

With GoInsight's Intercom node, you can automate customer data management and seamlessly integrate it into your business processes. You can manage the full lifecycle of core resources in Intercom, such as companies, leads, and users, including:

• Company Management: Automate the creation, updating, and retrieval of single or bulk company information.
• Lead Management: Capture, create, update, find, and delete leads within your workflows.
• User Management: Synchronize user data, including creating, updating, finding, and deleting user records, as well as associating users with companies.

2. Prerequisites

• Before using this node, you need to have a valid Intercom account.
• You need sufficient permissions to create and manage apps in your Intercom workspace to generate an API Access Token.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credential Configuration Guide.

4. Supported Operations

This node primarily operates on three core resources within Intercom: Companies, Leads, and Users. The table below summarizes all supported operations.

Summary

Operation Details

Create a Company

Creates a new company in Intercom, requiring a company ID, name, and other optional parameters.

Input Parameters:

• CompanyId: A unique identifier for the company in your system.
• Name: The name of the company to be created.

Options:

• RemoteCreatedAt: Timestamp (in seconds) of when the company was remotely created.
• CustomAttributes: A JSON object string containing custom attributes for the company.

Output:

• Id (string): The ID assigned to the newly created company by Intercom.
• Type (string): The resource type (should be "company").
• CompanyId (string): The company ID provided in the request.
• Name (string): The name of the created company.
• RemoteCreatedAt (number): The remote creation timestamp that was provided or assigned.
• CustomAttributes (string): A JSON string representing the company's custom attributes.
• CreatedAt (number): The timestamp (in seconds) when the company was created in Intercom.
• UpdatedAt (number): The timestamp (in seconds) when the company was last updated in Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): Empty on success, otherwise contains an error description.

Get a Company

Retrieves information for a single company from Intercom based on its ID.

Input Parameters:

• CompanyId: The ID of the Intercom company to retrieve.

Output:

• Company (object): A JSON dictionary of the company object returned by the Intercom API.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error description (if any); otherwise, an empty string.

Get Many Companies

Retrieves all companies from Intercom and returns the list as a JSON string.

Options:

• PerPage: The number of companies to retrieve per page.

Output:

• Companies (string): A JSON string of the list of company objects retrieved from Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise empty.

Update a Company

Updates the attributes of an existing Intercom company by its ID.

Input Parameters:

• CompanyId: The ID of the company to update.
• CompanyData: A JSON string containing the company fields and values to be updated.

Output:

• CompanyUpdated (bool): Indicates whether the company was successfully updated.
• UpdatedCompany (string): A JSON string of the updated company object returned by Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error description (if applicable), empty on success.

List Users of a Company

Lists all users belonging to an Intercom company via the specified company ID.

Input Parameters:

• CompanyId: The ID of the Intercom company whose users are to be listed.

Output:

• Users (object-array): A JSON string of the list of user objects returned by Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for invalid parameter, 500 for exception, 200 for success).
• ErrorMessage (string): An error message if any error occurred, otherwise empty.

Create a Lead

Creates a new lead in Intercom, requiring its identifiers and attributes.

Options:

• UserId: A unique identifier for the lead. Optional if Email is provided.
• Email: The email address of the new lead. Optional if UserId is provided.
• Name: The name of the lead.
• CustomAttributes: A JSON-formatted string containing additional custom attributes.

Output:

• LeadId (string): The unique identifier of the created lead.
• Lead (object): A JSON-formatted string of the full lead object returned by Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): Any error message that occurred during the request; an empty string on success.

Get a Lead

Retrieves the details of a specific lead in Intercom by its ID.

Input Parameters:

• LeadId: The ID of the lead to retrieve from Intercom.

Output:

• Lead (object): A JSON string representation of the lead details retrieved from Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error description upon operation failure or invalid parameters.

Get Many Leads

Gets a list of leads from Intercom, with pagination support to retrieve all available leads.

Options:

• PerPage: The number of leads to retrieve per page.
• StartingAfter: The cursor for pagination; an empty string for the first page.

Output:

• Results (object-array): A JSON string list of lead objects.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise empty.

Update a Lead

Updates the attributes of an existing Intercom lead.

Input Parameters:

• ContactId: The unique identifier of the Intercom lead to update.

Options:

• Name: The name of the lead.
• Email: The email address of the lead.
• CustomAttributes: A JSON string of key-value pairs for custom attributes.
• Tags: A JSON string of tag names to be assigned.

Output:

• Updated (bool): Indicates whether the update was successful.
• Result (object): A JSON string of the response data from the Intercom API.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message in case of any error.

Delete a Lead

Deletes an Intercom lead by its unique lead ID. This action cannot be undone.

Input Parameters:

• LeadId: The unique identifier of the Intercom lead to delete.

Output:

• Deleted (bool): Indicates whether the lead was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise an empty string.

Create a User

Creates a new user in Intercom with the provided details.

Options:

• UserId: A client-specified unique user identifier; one of UserId or Email must be provided.
• Email: The user's email address; one of Email or UserId must be provided.
• Name: The user's display name.
• Phone: The user's phone number.
• CustomAttributes: A JSON string of custom attributes.
• Companies: A JSON string of an array of company objects.

Output:

• User (object): A JSON string of the created user object returned by Intercom.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message upon operation failure; otherwise, an empty string.

Get a User

Retrieves an Intercom user by their ID.

Input Parameters:

• UserId: The ID of the user to retrieve from Intercom.

Output:

• Results (object): A JSON string of the user details returned by the Intercom API.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise an empty string.

Get Many Users

Retrieves all users from Intercom in a paginated way.

Output:

• Results (object-array): A JSON string list of Intercom user objects.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise an empty string.

Update a User

Updates an existing Intercom user by the specified user ID and provided attributes.

Input Parameters:

• UserId: The unique Intercom user ID to be updated.

Options:

• UpdateData: A JSON-formatted string containing the user fields to be updated. If passed as a list or dictionary, it will be automatically converted to JSON.

Output:

• UpdatedUser (object): The updated user object from Intercom, serialized as a JSON string.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message (if any), otherwise an empty string.

Delete a User

Deletes a user in Intercom by their user ID.

Input Parameters:

• UserId: The ID of the user to delete. Supports a list or dictionary (provided as a JSON string).

Output:

• Deleted (bool): Indicates whether the user was successfully deleted.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exception).
• ErrorMessage (string): An error message on operation failure; empty on success.

5. Example Usage

This section will guide you through creating a simple workflow to automatically create a new company record in your Intercom account.

Workflow Overview

A simple workflow might consist of three nodes: Start -> Intercom: Create a Company -> Answer. When the workflow is triggered, it will create a new company in Intercom.

Step-by-Step Guide

1. Add Tool Node:
   • On the workflow canvas, click the “+” sign to add a new node.
   • In the pop-up panel, select the “Tools” tab.
   • In the tool list, find and select Intercom.
   • In the list of supported operations for Intercom, click to select Create a Company, which will add a corresponding node to the canvas.
2. Configure Node:
   • Click on the newly added Create a Company node, and its configuration panel will expand on the right.
   • Credential Configuration: At the top of the panel, find the credential field. Click the dropdown menu and select your pre-configured Intercom credential.
   • Parameter Entry: Fill in the required parameters to create a company.
   • CompanyId: Enter a unique company ID from your system. This ID is used to prevent duplicate creations. For example, you can enter CLIENT-12345.
   • Name: Enter the name of the new company. For example, you can enter New Client Inc..
   • CustomAttributes (Optional): If you want to add custom information, you can enter a JSON string. For example: {"plan": "premium", "signup_source": "workflow"}.
3. Run and Validate:
   • Once all required parameters are correctly filled in, the error prompt in the top right corner of the workflow canvas will disappear.
   • Click the “Run” button in the top right corner of the canvas to execute the workflow.
   • After a successful execution, you can click the log icon in the top right corner to view the detailed input and output of the node. In the output, you should see the Intercom ID and other details of the newly created company. You can also log into your Intercom account to confirm that the company has been successfully created.

Final Workflow Display

After completing the steps above, your entire workflow is configured. Clicking “Run” will successfully create a new company record in your Intercom, automating the process of customer data entry.

6. FAQs

Q: What is the difference between a "User" and a "Lead" in Intercom?

A: These are two core concepts used to distinguish different types of contacts:

• Lead: Typically an anonymous visitor or contact who has not yet become a paying user of your product or service. They may have only provided an email address or had a preliminary interaction.
• User: Usually a recognized customer who has logged in or signed up for your product. Their data is richer, and they are the target of your core services.

Q: My request failed with a 401 or 403 error. Why is that?

A: Such errors are usually related to credentials or permissions. Please check the following:

• Correct Credentials: Confirm that the Intercom credentials (Access Token) you configured in GoInsight are valid and have not expired.
• Permission Scopes: Ensure that the Access Token you generated includes the necessary permissions to perform the required actions. For example, to create a company, your token needs permission to write company data.

Q: When creating a user, do I have to provide both UserId and Email?

A: No. According to the Intercom API requirements, you must provide at least one of UserId or Email to uniquely identify a user. If both are provided, Intercom will associate them with the same user record.

7. Official Documentation

For a more in-depth understanding of all the features and details of the Intercom API, please consult the official documentation:

Intercom Official API Reference