Skip to content

Puzzel

Our integration for Puzzel enables you to manage your customer satisfaction and work with P-GAP, without ever leaving your Puzzel platform. Below is a complete guide on how to implement the solution:

Showcase of Puzzel Puzzel showcase

Prerequisites

  • You should be able to access the Puzzel admin portal
  • You should be able to access app.nps.today
  • If you are intending on testing P-GAP, you should also have access to add a P-GAP period on app.nps.today
  • For the Call Flow set-up you additionally need:
    • Permission to create users in the Puzzel admin portal
    • Access to Services ➡ Editor in the Puzzel admin portal
    • A CFT user with scripting access, or a Puzzel partner/supplier who can make the changes for you

Admin set up

  1. Go to Puzzel admin portal

  2. Navigate to Widget Configuration

    1. Url should be "https://puzzel.nps.today" for production
    2. APIkey is your api key from app.nps.today

  3. Navigate to Tab Configuration and add a new tab

    1. Call it "nps.today", and click Save changes
    2. Click the newly created tab, and click Insert a widget
    3. Find "nps.today" and click Add widget and then Save changes

    4. Go to Tap Settings to set-up your tab

      1. Enable "Tab is always open" and set it to on
      2. Enable "Default opened in left tab-set" and set it to on
      3. In the Header section you can give you tab a name and change the color to make it fit your Puzzel UI.
      4. Click Confirm
        Tab Settings
      Default opened in left tab-set

      We recommend having the nps.today tab popping up on the left side of the screen as a new call pops up on the right side.
      In this way, you make sure the agent does not miss any calls because of the widget blocking the call tab.

    5. Click Save

  4. Navigate back to Tab Configuration

    • If the entire company should use the widget
      1. Click ☑️ at "nps.today" under Company/Inherit
      2. Set the value to on
    • If only a user group should use the widget
      1. Click ☑️ at "nps.today" under Selected User Group/Inherit
      2. Set the value to on
    • If only a user should use the widget (e.g. for testing)
      1. Select the User Group the user is in
      2. Click ☑️ at "nps.today" under Selected User/Inherit
      3. Set the value to on

  5. Navigate to Widget Administration and find your nps.today widget

    • Make sure that canGetAccessToken has a ☑️ in the Default Value and a ☑️ in Possible to set option from widget Checkmarks on canGetAccessToken
    • Click Update

  6. The widget should now pop up next time an agent logs in at agent.puzzel.com. 🎉

If you want to send out surveys when the call has ended, you need to make a link between your campaign(s) and queue(s) in Puzzel.

  1. Go to the Puzzel admin portal and find the queue keys needed, or go to developer.puzzel.com and call the endpoint to get a list of all your queues.
  2. Now go to the IVR section on app.nps.today, and click Add IVR, follow the guide to add the link.
  3. Confirm everything is working as planned by going to agent.puzzel.com and making a test call.

Adding P-GAP period

In order to test P-GAP period, the agent should be registered in app.nps.today. The first time the widget is used for sending out a survey, the agent will be created automatically.

  1. Navigate to the P-GAP section on app.nps.today
  2. Click Add training session and go through the guide, making sure the start and end date are set, so that today's date are included, and the correct campaign(s) are selected.
  3. Go to agent.puzzel.com and make a test call, to ensure that you get prompted with a P-GAP pop-up, when the call has ended.

By default, the call should be above 60 seconds in order to trigger a survey/P-GAP, this can be changed by contacting our support.

P-GAP for extra questions

This feature enables you to use P-GAP on your extra questions related to a campaign in nps.today.

You activate this feature in your campaign editor in nps.today and allows prompting of the question to the Puzzel agent.

FTR Campaign editor

Use case

A highly relevant use case for this feature is FTR (First Time Resolution). With FTR both the agent and the caller will be asked if the problem was solved to see if they have the same perception of the resolution.

Below you see how the agent will get promted by the question in Puzzel.
FTR Puzzel

Only works for single- and multi select

This feature is only available on extra question using single- and multi select. FTR Puzzel

Have the right licenses

This feature is only available if your subscription includes the P-GAP- and Puzzel module.

Hiding the Puzzel Widget

If you desire not to see the visuals of the widget you have the option to hide it. In the admin portal, do the following:

  1. Go to Widget Administration.
  2. In the NPS.Today Widget, click "Add widget property"
  3. Call it "hideWidget" with type "Boolean". We recommend having it set to false as default so that it's not toggled on after you have clicked Add widget propety.
  4. Once the propety is added, go to Widget Configuration and find the NPS.Today widget.
  5. Here you have the option to hide the widget. Set it at the appropiate level, fx. by Company.

Hiding widget showcase

Hiding widget showcase

Puzzel chat configuration

The widget also supports Puzzel chat, and can be used to send out surveys after a chat has ended.

Puzzel chat showcase

Support for Chat

The chat currently only supports phone numbers as input for the chat

If you want to use the chat, you need to add a variable to the chat, which will be used to identify the customer. The phone number is treated as a danish phone number if no country code is added.

First find the variable, go to the Chat Service Configurations in Puzzel, and find the variable name in the chat configuration used.

Variable in chat configuration

Go to Widget ➡ Widget Configuration, unfold the nps.today widget, in the field "chatVariable" you can add the variable name for the chat.

Variable in widget configuration

You cannot use system variables in the chat configuration

The reason for this is that the system variables are not available in our widget. Although you can use the following system variables in other contexts, they will not work within our widget: enteredFormName enteredChatId enteredFormIssue selectedQueueKey timeId2Map.

In this example the chat is setup to use the value from the variable phoneNumber, as a recipient for the survey. Read more about setting up sms delivery here

Call Flow set-up

The Call Flow set-up is what triggers a survey when a call ends. It is separate from the widget set-up above, and it uses a different credential.

Set-up Authenticates With
Widget The widget toward nps.today Your nps.today API key from app.nps.today
Call Flow The Call Flow toward Puzzel A dedicated Puzzel API user stored in puzzel_auth.xml

Both are needed for a fully enabled integration. Complete the two sections below before you add the script to the 'finally' section.

Create a Puzzel API user

The Call Flow needs Puzzel API credentials in order to look up the agent's email address and include it in the request toward nps.today. Create a dedicated user for this rather than reusing a personal account.

  1. Go to the Puzzel admin portal and navigate to Users ➡ Users
  2. Create a new user and set the following:
    1. First Name and Last Name: something recognisable, for example "NPS" and "Today"
    2. Username: a dedicated username, for example apiusernpstoday
    3. Password: a strong password. You need it again in the next section
    4. User Group: Admin
    5. User type: API
  3. Click Save User

Puzzel API user

Set User type to API

User type defaults to Person. Change it to API so the account is treated as an integration user rather than as an agent.

Create the auth file

puzzel_auth.xml holds the credentials for the API user you just created. The file lives in your own Puzzel tenant, which is why the include path in the next section uses the $(system_custkey) placeholder: it resolves to your own Puzzel customer key.

  1. In the Puzzel admin portal, go to Services ➡ Editor. This opens the Files and Folders Configurations page.
  2. Look for a folder named Integration. Most tenants do not have one, because it is only used for integrations like this one. If it is missing, click Add Folder and name it Integration
  3. Open the Integration folder and click Add File
  4. Name the file puzzel_auth.xml and set the resource type to Undefined XML

  5. Add the following, replacing the two values with the username and password of your API user:

    <content>
<assign variable="puzzelauth.username" value="Username goes here" restricted="true" />
<assign variable="puzzelauth.password" value="Password goes here" restricted="true" />
</content>

  6. Save the file

Finding the Editor in a Danish portal

The breadcrumb reads Forsiden ➡ Tjenester ➡ Editor. The Add Folder and Add File buttons sit underneath the folder list.

No Editor in the Services menu

The Editor page is not available to every administrator. If Services shows Audio, Time, KPI alarm, Queues, Call Flow, Content and Chat but no Editor, contact Puzzel Support or your Puzzel partner/supplier and ask them to help you create the folder and the puzzel_auth.xml file.

Spelling of the file name

The file is puzzel_auth.xml, spelled like Puzzel, and not puzzle_auth.xml. The include in the 'finally' script looks for that exact name in that exact folder.

Match the variable names exactly

The variable names are puzzelauth.username and puzzelauth.password, with no underscore in puzzelauth. A typo here does not produce an error. The request toward nps.today is simply sent without the agent's email address.

Keep restricted=\"true\"

Leave restricted="true" on both lines as shown, and treat the file as a credential store. If the API user's password is changed in the admin portal, remember to update the file as well.

Inbound calls

Create a 'control' variable
A ‘control’ variable is a mechanism to control whether a web request is sent toward nps.today

This means a request is sent only if the value of npstoday_enabled = true

This variable can be assigned value at various points in the Call Flow, giving you the ability to control which queues have it enabled.
Translations

If you want it enabled for all queues, just assign as the first module in the Call Flow.

NPS Enabled for all queues

Translations

If you, for example, want to only enable for a single queue, you assign it before the preferred queue instead.

NPS Enabled for a single queue

Translations


Changes to 'final' script

CFT user with scripting access

For making changes to the 'final' script you need to be a CFT user with scripting access.
If you are not able to make changes to the final script, please reach to your Puzzel partner/supplier for help.

Below script needs to be added to the ‘finally’ section of the Call Flow. 

<include expression="npstoday_enabled = true" src="/$(system_custkey)/Integration/puzzel_auth.xml"/>
<include expression="npstoday_enabled = true" src="/450893/Integration/NPSToday_CallEnded.xml"/>

Both lines are needed, and the order matters. The first line loads the credentials from the puzzel_auth.xml file in your own tenant, described above. The second line loads the request itself from tenant 450893, which is the nps.today tenant, so the logic stays maintained by us and does not have to be copied into yours.

There is no Integration folder in our tenant

That is expected in a tenant where this has not been set up before. The folder is not created by Puzzel or by nps.today, you create it yourself under Services ➡ Editor, as described in Create the auth file. The $(system_custkey) part of the path resolves to your own Puzzel customer key, so both the folder and the file have to exist in your tenant before the 'finally' script can do anything.

Steps to take if a new queue is created

If you have the NPS web request enabled globally, you do not need to do anything to include a new queue into this process. If you target individual queues via the npstoday_enabled variable, you only need to assign it to the new queue.

Outbound calls

To ensure nps.today surveys are triggered on outbound calls, the setup must be handled via Puzzel's Initial Script rather than the standard Call Flow Canvas. This requires a coordinated effort between your team and Puzzel Support.

What to do:

  • Create the API user and auth file first: The Initial Script relies on the same credentials as the inbound flow, so complete Create a Puzzel API user and Create the auth file before you raise the change request.
  • Request a Change: Contact Puzzel Support with a "Change Request" to enable nps.today surveys to trigger on outbound traffic.
  • Script Configuration: Instruct Puzzel to mirror the variables from your inbound flow into the Initial Script.
  • Provide Guidance: If needed, you can share the Call Flow set-up guide for inbound with Puzzel Support for better understanding of what needs to be done.
  • Link the IVR: Once the script is confirmed, you must configure the IVR for your outbound queue to point toward your nps.today campaign.
Change Request template

Dear Puzzel Support,

We would like to request a technical configuration change to our Puzzel environment to enable nps.today survey triggers for our outbound call traffic.

Currently, our nps.today integration is functional for inbound calls via the Call Flow Canvas. However, we understand that for outbound calls, the variables must be mirrored within the Initial Script to ensure the survey is triggered correctly upon call termination.

Request Details:
Objective: Trigger nps.today surveys on outbound calls in Puzzel.
Technical Requirement: Mirror the nps.today variables currently used in our "Inbound Call Flow Canvas" into our "Initial Script".
Reference: Please refer to the official nps.today Call Flow set-up guide for the specific scripting requirements.

Once these variables have been successfully added to the Initial Script, please let us know so that we can complete the final step of setting up the connection for our outbound queue to point toward our nps.today campaign.

Thank you for your assistance.

FAQ

Settings have not applied

Be sure to reload the Puzzel pages when making a change on app.nps.today. This is due to the settings getting synced when reloading the page.

Do I need both the nps.today API key and a Puzzel API user?

Yes, they do different jobs. The nps.today API key in Widget Configuration lets the widget talk to nps.today. The Puzzel API user in puzzel_auth.xml lets the Call Flow look up the agent's email address in Puzzel when a call ends. The widget set-up works without the API user, but no survey is triggered on call end. See Call Flow set-up.