How to Configure Integration URLs

Last Updated -


Integration URLs are a feature that allow your Agents to access information quickly about customers using external websites. Through Integration URLs, any case or customer information can be passed through a URL to your back-end order management, customer profile, or sales web-based applications.

An Integration URL passes customer or case-specific data using parameters to other systems, and displays the results in a new window or a lightbox window within the case. For example, if you want to use this functionality to perform customer lookups in an external order system, using the customer's email address (or another identifier) you can add a special URL that looks up the data in this external order system.

Integration URLs are built on top of liquid templates, the templating language we use in Liquid templates give you additional flexibility in your template design by allowing you to parse variables, compare data with operators, and create custom HTML.

Integration URLs in Next Gen’s Next Gen Agent Desktop has a different layout than the Classic Agent Desktop. As a result, the three options for where to open an Integration URL (“Open Location” property) work differently in Next Gen.  In Next Gen, all three options will only open the link in a new browser tab or window. 

Create an Integration URL

  1. Go to Admin > Cases >Integration URLs.
  1. Click the + Add New Integration URL.


  • Name: This displays to Agents in the Integration URL interface.
  • URL​: The URL of the system to pass data to. You are likely to want to pass some of the URL variables as parameters to your system. The available parameters are split between the case and customer object.

The parameters for the customer are:

Full Name {{}}
First Name {{customer.first_name}}
Last Name {{customer.last_name}}
Email {{}}
Company {{}}
Title {{customer.title}}
Background Info {{customer.about}}

The parameters for the case are:

ID {{}}
Subject {{case.subject}}
Case Closed Date/Time {{case.closed_at}}
Case Opened Date/Time {{case.opened_at}}

In addition, custom fields in either the customer or case objects can easily be referenced with:

  • {{customer.custom_sample}} where sample is the identifier given to the specific field in the customer object
  • {{case.custom_sample}} where sample is the identifier given to the specific field in the case object


As an example, you may pass in the customer's name and the date that the case was opened into a custom order system to look up all of the data for that customer prior to when the case was opened. The URL may look like:

The Description field will be available to agents in the Integration URL interface. Select the desired Open Location. You can choose from the following options:

  • On top of case - opens the URL in a lightbox on top of the case.
  • New browser window - opens the URL in a new browser window, leaving the agent session intact.
  • In case pane - opens the URL inline in the agent's case interface.

This allows the agent to work on and view the Integration URL alongside the agent interface. For the best experience, the recommended width of the embedded page should be 400 pixels.

eCommerce Examples

eCommerce is a great use case for Integration URLs. Here are some examples:

Note: To use the examples below, make sure to substitute in your specific shop name in place of "desk-com-test" in each example





iFrame Integration URLs: iFrame and Canvas

Two new options have been added to the “Open Location” options list.   Both of these new options only apply to Next Gen Agent and are directly related to the new Case Layouts feature in Next Gen.  The “Canvas iFrame” option is only available on Desk instances at the Pro and Business Plus levels.

When an integration URL’s Open Location is set to either the ‘Standard iFrame’ or the ‘Canvas iFrame’ setting,  it will not appear in the list of integration URLs in either Classic (“Info Links”) or Next Gen Agent (link icon).  Instead, it will appear as an “Integrations” component in the Next Gen Case Layout drag & drop editor.  When dragged onto a case layout, an iFrame is added to to the layout which loads the integration URL.  You can read more about Next Gen Case Layouts in this support article.

Standard and Canvas iFrame integration URLs can be dynamic and include variables from the Liquid object model just like any other integration URL.

  • All accounts can have unlimited Standard iFrame integration URLs. 
  • Pro plan accounts can have one Canvas iFrame integration URL. 
  • Business Plus accounts can have unlimited Canvas iFrame integation URLs.

If you aren’t sure what Canvas is, you can learn more about it in this developer document. In short, it is a development platform that enables customization of the Next Gen Agent Desktop.  When a Canvas iFrame is put on a Case Layout, the page in the iFrame is able to talk to via Javascript.

Standard iFrames, in contrast, are static windows into other pages (the integration URL) with no communication between and the page rendered in the iFrame. Now let's create a Canvas iFrame.

Create a Canvas iFrame

  1. Go to Admin > Cases >Integration URLs.
  2. Select + Integration URL.

  1. In the Edit Integration URL window, add the 'Name' and 'Description' of the Integration URL.
  2. Under 'Open Location,' create an integration URL that opens as a 'Canvas iFrame.' The integration URL is the address of the app you have developed and are hosting somewhere. It will be applied at the SRC of the Canvas iFrame.
  3. Enable the URL via the toggle bar.
  4. Click 'Update.'

Note: The 'Shared key' is a randomly generated authentication string that communicates with the third party vendor. System administrators can reset this at their discretion.

  1. To assign permissions, go to: Admin>Cases>Next Gen Case Layouts.
  2. Once the integration URL is created, it will show up as an Integration component in the Next Gen Case Layout drag & drop editor. Simply drag it from the right column over onto the Case Layout and drop it where you would like it to display. 

  1. Once the Canvas iFrame is added to the Case Layout, assign the Case Layout to Users or Groups.
  2. The assigned Users or Groups can now see the Canvas iFrame (e.g., Location) in a ticket.

Pro Tips

Here is some helpful advice for developing and implementing your Canvas solutions.

Create a Test and Development Case Layout

As you or your developers are developing the application that will be hosted somewhere and run inside the Canvas iFrame, you will most likely want to test it and see how it’s working before rolling it out to all of your agents.

Create a new Case Layout that you will only assign to yourself, the developers and a few trusted testers, and put the in-progress Canvas iFrame on that Case Layout. This way you can control the rollout of the functionality, but still see it in action.

You can even go a step further and have your account executive set you up with a development sandbox environment. Doing the development on a Case Layout inside the sandbox is safer because none of your production data will be at risk during the development of the application.

Use the Context Payload in the Signed Post Request

When you create the Canvas iFrame integration URL, the URL itself can have dynamic variables added via the Liquid object model that Desk provides - this is the same for all Integration URLs. You are welcome to use those.

However, the signed post request we send when requesting your application URL has a payload of context information (in encoded JSON format) that includes all of the information available via Liquid and more. Instead of adding variables to your URL, just decode the payload in the POST Request Header and use the information we are already sending you.

More information about the payload and Canvas can be found in the Canvas Developer’s Guide.

GET STARTED FOR FREE, the industry leading customer service application for fast growing companies.

Free Trial