iTop Extensions

Ticket creation feature (Chat integration with Intercom)


Get Intercom account

Note: This step is only necessary once, if you already did it, skip this step.

Go to Intercom, create an account.

Create your own iTop integration within Intercom app store

Note: This step is only necessary if you want support agents to create iTop tickets from their Intercom dashboard. If you just want them to chat with end-users without creating tickets, skip this step.


  1. Prepare iTop access permissions
  2. Create new app
  3. Retrieve client secret
  4. Retrieve access token
  5. Configure endpoints URLs
  6. Fill module configuration

1. Prepare iTop access permissions

[In iTop] First, you need to create a token-based user in your iTop that will be used by Intercom to access iTop and manipulate tickets.

  • Create a new Token based user
  • In the Remote application field, type something that will identify the user as the one being used by the Intercom app, for example intercom_sync_app.
    (Only alphanumerical, - and _ characters can be used)
  • Add it the Administrator profile. (This is mandatory for iTop to allow the creation of log entries on behalf of other persons)
  • Once created, copy the token displayed on top of the page, it will be used in the following steps and referred to as ITOP_USER_TOKEN.
    In the screenshot below, the token is a59ff45c340[…]eb355, don't copy the auth_token= part.
As this is using the “Token based user” authentication system, mind to add rest-token as the first allowed_login_modes in the configuration file.

For example:
'allowed_login_types' => 'rest-token|form|external|basic',

2. Create new app

In order to create tickets in iTop directly from the Intercom dashboard, you need to create what is called an “Intercom app” which will discuss with your iTop instance.

[In Intercom] Go to the Intercom Developer Hub

[In Intercom] Then go to “Your apps” and create a “new app”. Name it “iTop” and make sure to choose “Internal integration”.

3. Retrieve client secret

[In Intercom]] Now that the app is created you need to configure it so it can discuss with iTop. Go to the “Basic information” section and copy the Client secret, will use it later (eg. “zyxwvuts-987654-321654-abcde-fghi” in the screenshot below)

4. Retrieve access token

[In Intercom] Then go to the “Authentication” section

  • Copy the Access token, will use it later (eg. “abCdEFgHiJKLmnOpQRsTUvWyZ012346579=” in the screenshot below)
  • Enable the following permissions and don't forget to save
    • Read conversations for obvious reason
    • Write conversations to enable the app to add auto-generated messages in the conversation

5. Configure endpoints URLs

[In Intercom] Now to the “Canvas Kit” section.

  • Open the “For teammates”
  • Check “Inbox” which is the support agents GUI
  • Fill the following parameters but mind to change ITOP_APP_ROOT_URL and ITOP_USER_TOKEN with your own iTop app root URL and token
    • Initialize flow webhook URL
    • Submit flow webhook URL

[In Intercom] Now to the “Webhooks” section.

  • Fill the request endpoint URL parameter but mind to change ITOP_APP_ROOT_URL and ITOP_USER_TOKEN with your own iTop app root URL and token
  • Enable the following “Webhook topics”
    • conversation.admin.replied
    • conversation.admin.noted
    • conversation.user.replied

6. Fill module configuration

[In iTop] Now that the app is created, you have to configure iTop so it allows it to interact with it. In the iTop configuration file, fill the module settings as follow, using one of the methods described below:

  • workspaces An array of Intercom workspaces and their options. Having multiple workspaces is only necessary is you want different Intercom teams to answer to specific user subsets.
    Keys of the array must be the Intercom workspace IDs, values must be an array of the following parameters:
    • scope An OQL query to define which iTop users will have access to the chat widget.
  • sync_app.client_secret Intercom app client secret retrieved earlier
  • sync_app.access_token Intercom app access token retrieved earlier

There are 2 ways to configure the module settings:

  • Through the iTop configuration file: Will only
  • Through the XML datamodel via the ITSM Designer or an extension

Method 1: Configuration through the iTop configuration file


  • Can be done easily as you just need to edit the configuration in your iTop instance


  • Only applies to that particular iTop instance. If you are running several iTop frontals or environments, you will need to duplicate the configuration on each instances you want the chat to be enabled.

Simply put the following in the configuration file and fill it with your own settings:

'combodo-intercom-integration' => array (
        'workspaces' => array (
          'PUT_YOUR_WORKSPACE_ID_HERE' => array ( // Replace "PUT_YOUR_WORKSPACE_ID_HERE" with the workspace ID retrieve in the previous step ("abcdefg" in the example)
            'scope' => 'SELECT Organization',
        'sync_app.client_secret' => 'PUT_YOUR_APP_CLIENT_SECRET_HERE',
        'sync_app.access_token' => 'PUT_YOUR_APP_ACCESS_TOKEN_HERE',

Method 2: Configuration through the XML datamodel


  • Configuration will apply to all instances using this datamodel:
    • If done in the ITSM Designer: All instances of the concerned license
    • If done in an extension: All instances using the extension
  • Can still be overloaded locally with method #1


  • When using the ITSM Designer: Need Combodo's assistance to configure the module parameters
  • When using an extension: Need to be familiar with iTop extension development

Use the following XML as a bootstrap:

<?xml version="1.0" encoding="UTF-8"?>
<itop_design xmlns:xsi="" version="1.7">
                <parameters id="combodo-intercom-integration" _delta="define">
                        <!-- Replace "PUT_YOUR_WORKSPACE_ID_HERE" with the workspace ID retrieve in the previous step ("abcdefg" in the example) -->
                                <PUT_YOUR_WORKSPACE_ID_HERE type="hash">
                                        <scope><![CDATA[SELECT Organization]]></scope>
                        <!-- Used to authenticate incoming requests -->
                        <!-- Used to authenticate outgoing requests -->
extensions/combodo-intercom-integration/ticket-creation-configuration.txt · Last modified: 2022/11/21 09:52 (external edit)
Back to top
Contact us