In the beginning of 2021, TOPdesk and Insocial created a standard API solution, that could be implemented for SX surveys. In Q4 of 2022, a new and more flexible solution has been developed by Pascal Janssens (Partner Manager) from TOPdesk.
Whereas the API was limited for one survey in the 'service' module of TOPdesk, the new solution offers more flexibility. With the new solution, a (temporary) admin user can initiate action sequences in both the 'service' as well as the 'change' modules of TOPdesk. Compared to the API, the new solutions is more flexible in terms of:
• Number of surveys: instead of a limit of one survey, it is possible to connect multiple surveys to the same TOPdesk module. Therefore more teams and/or business units are able to use the same connection between TOPdesk and Insocial.
• Custom survey rules: instead of a standard survey process, the new solution allows one survey to be triggered based on different action sequences. That means that the same survey can be send or blocked based on metadata or events. For example:
- If metadata is 'operator group A' then send out the survey. If metadata is 'operator group B' then do not send out the survey.
- If 'event X' then send out the survey. If 'event Y' then do not send out the survey.
• Metadata: instead of a standard set of 19 metadata fields, it is possible to add other metadata fields that are being registered by the client in their TOPdesk module.
Sounds good doesn't it? But how to get started?
We added a manual below.
------------------------------------------------------------------------------------------------------------------
Implementation manual: Insocial – TOPdesk Integration
The integration between Insocial and TOPdesk works as follows:
When an incident or change is closed[1] within TOPdesk, the caller will be invited to participate in an Insocial Survey. The caller will receive the invitation by e-mail.
[1] It is possible to use a different event. For example, when a specific status is chosen.
Preperation
Before the integration can be setup you need to have an Insocial account, an E-mail template and a survey set up.
Preparation Gather data from Insocial
- Insocial Token
- SurveyID
- CustomerID
- E-mail Template Name
- Sender Name of the e-mail containing the survey
- Sender E-mail address of the e-mail containing the survey
- Subject of the e-mail containing the survey
Your contact person at Insocial will provide you with this information.
From TOPdesk you will need the following data:
- TOPdesk URL
- Login name API User
- Application Password
TOPdesk URL: For example: https://COMPANY-NAME.topdesk.net
Login name of the API user: Create a TOPdesk operator account. Name it API_InSocial. Give it the following permissions:
Make sure to also check the filters of the users so that is will be able to see relevant cards. Write down the login name.
Application password: Login with the API user you have created. Click on the top right corner on the settings icon 
, click my settings. In the settings window, on the bottom right, click Add.
In the new window, name it InSocial and set an expiration date[2].
[2] After this expiration date the password will not be valid anymore. The integration will not work with an invalid password, this means you will have to create a new password and configure it into the integration. You can choose to set expiration date to 2099 so that you do not have to reconfigure it again.
You will now see the application password. Make sure you save it in a password manager.
Call Management: Set up the Action Sequences in order to invite callers to the InSocial survey
• Login to TOPdesk. Go to Modules, Action Management, New, Action sequence
• Choose ‘Call Management – First line call’
N.B. in some TOPdesk instances, call management is renamed to Incident management or something else.
• Click ‘Create new action sequence’.
• Click ‘Import’ and choose to overwrite this action sequence
• Import the attached file: Incident InSocial - Survey Request V****.
• Make sure the action sequence is ‘Active’ and applied in both ‘Self-Service Portal’ and ‘Operator Section’.
• Fill in the variables from the data you have gathered (see preparations):
-
- add_error_message: Fill in YES of you want to add an action in case connection to InSocial has failed. Fill in NO if you do not want this message.
- Add_succeeded_message: Fill in YES of you want to add an action in case connection to InSocial has succeeded. Fill in NO if you do not want this message.
- error_message_text: Enter the message you would like to receive when connection has failed (for example ‘Insocial connection has failed’).
- succeeded_message_text: Enter the message you would like to receive when connection has succeeded (for example ‘Insocial Survey initiated’).
- Message_text_visible: YES if message should be visible to the caller, NO if the message should be invisible to the caller.
• Save the Action Sequence
Trigger Event
You can trigger this action on Event of your own choosing. We recommend to trigger it when an incident is closed. For this scenario you need to do the following steps:
• Go to Modules, Action Management, New, Event
• Choose ‘Call Management – First lin call’
N.B. in some TOPdesk instances, call management is renamed to Incident management or something else.
• Name the event (for example ‘Closed’).
• Apply ‘Edit Specifications’.
• Choose ‘Event occurs with any edit’
• Field ‘Closed’
• New value ‘True’
You can edit the event to your choosing. For example you can add a condition that only calls with specific categories, or callers from specific branches should trigger the action.
• Link the Event to the Action Sequence. Click the edit button next to ‘Linked actions’. Choose the Action Sequence ‘Incident InSocial - Survey Request’ 
• Save the Event.
Note: if you also want to trigger the Insocial Survey when closing second line calls, please redo all of the steps above (creating the action sequence and the event) but choose second line calls upon creating the action and event .
Additionally you choose to add more events to the action sequences. For example New Incidents with status closed. This way the Survey is also triggered by incidents that are closed immediately.
Congratulations, the integration between TOPdesk Call Management and Insocial is completed!