Portal Deep Linking

Chris Updated by Chris

This article discusses our new Deep Linking system which requires Portal V2 to be turned on for your clients. To read about the legacy URL linking for Portal V1, click here.

What is Deep Linking?

Deep links allow you to provide users with a direct link to a certain part of the application such as a learning article or a specific ticket.

They can support various actions as well, depending on the page linked to. As an example, you can deep link directly to a ticket and automatically have a chat session open with your engineers.

Deep links can be created for both the Web Client and the Desktop Clients (Windows & macOS).

However, the biggest advantage of deep links is that they will remain valid even between different versions of the Portal, which isn't always the case with the URL in your browsers address bar. That URL might take you back to the same ticket today, but it might not work if there is a significant change to how the app operates internally.

Desktop Clients vs. Web Client

Deep links can look a little bit different depending on where they are intended to be used. Lets take a look.

As an example, we will be linking to a specific ticket with a Ticket ID of 123456

https://[your-subdomain].deskdirector.com/portal/deeplink?name=ticket&ticket_id=123456

There are a few things to note:

  • The beginning of the deep link is different for the two cases:
    • Web Client: https://[your-subdomain].deskdirector.com/portal/deeplink?
    • Desktop Client: ddportal://
  • The end of the deep link is exactly the same for the two cases. We call this piece the command:
    • name=ticket&ticket_id=123456

Thus the general format of a deep link is

https://[your-subdomain].deskdirector.com/portal/deeplink?[command]
When the Desktop Client is installed onto a machine, it registers the ddportal:// protocol with the operating system automatically.Any links starting with this protocol will be forwarded to the application.

In general, each type of deep link has at least one required parameter, it's name . Other parameters may exist to give more control over the link behavior.

Linking to a specific ticket

Command format:

name=ticket&ticket_id={ticket_id}&action={action}

Parameters:

  • ticket_id (required): The id of the ticket to link
  • action (optional): An optional action to perform on the ticket page, can be one of the following:
    • chat: Open a new ticket chat session with your engineers
    • close: Prompt the user to close the ticket
    • approve: Prompt the user to approve the ticket
    • decline: Prompt the user to decline approval for the ticket
    • auto_approve: Automatically approve the ticket, no reason is given
    • auto_decline: Automatically decline approval for the ticket, no reason is given
    • reopen: Prompt the user to reopen the ticket
    • flag: Prompt the user to flag the ticket
    • fasttrack: Prompt the user to FastTrack the ticket
    • forms: Prompt the user to fill out any inline forms that have been attached to the ticket

Examples:

name=ticket&ticket_id=123456name=ticket&ticket_id=123456&action=close

ConnectWise Service Email Template Snippet

<a href="https://[your-subdomain].deskdirector.com/portal/deeplink?name=ticket&ticket_id=[srnumber]">Open in DeskDirector</a>
Autotask Notification Template Snippet

<a href="https://[your-subdomain].deskdirector.com/portal/deeplink?name=ticket&ticket_id=[Ticket: ID]">Open in DeskDirector</a>
Linking to the Ticket List

Command format:

name=ticket_list&state={state}

Parameters:

  • state (optional): The state of the tickets displayed. Defaults to open.
    • open: Show open tickets
    • closed: Show closed tickets
    • approval: Show approval tickets

Examples:

name=ticket_list

name=ticket_list&state=approval

Linking to Support Options (Where the Create Ticket & Pre-Ticket Chat options are displayed)

Command format:name=support_options

Examples:

name=support_options

Linking directly to Pre-Ticket Chat (Chat to a Technician)

Command format:name=pre_ticket_chat

Examples:

name=pre_ticket_chat

Linking to the list of Request Type / Form Categories

Command format:name=request_types

Example:

name=request_types

Linking to a specific Request Type / Form
New Request Support UI is required for this deep link.

Command format:name=request_type&type_id={type_id}

Parameters:

  • type_id(required): The id of the request type. Currently this is only found inside the browser URL when viewing a request type in your Admin Console.

Examples:

name=request_type&type_id=77

Linking to Notifications

Command format:name=notifications

Examples:

name=notifications

Linking to a Content Page (e.g. Learning center page)

Command format:

name=content_page&page_id={page_id}

Parameters:

  • page_id (required): The id of the page.

Examples:

name=content_page&page_id=5b658ce9-7014-4e4e-995d-2934bf1f10c3

Linking to the Invoices list

Command format:

name=invoices

Examples:

name=invoices

Linking to an Invoice

Command format:

name=invoice&invoice_id={invoice_id}

Parameters:

  • invoice_id (required): The id of the invoice.

Examples:

name=invoice&invoice_id=I239394

Linking to the Quotes list

Command format:

name=quotes

Examples:

name=quotes

Linking to a Quote

Example command:

name=quote&quote_id={quote_id}

Parameters:

  • quote_id (required): The id of the quote.=

Examples:

name=quote&quote_id=QABV829

Linking to a menu item

This requires the new menu system to be enabled.

Example command:

name=menu_item&menu_id={menu_id}

Parameters:

  • menu_id (required): the id of the menu item. You can obtain this from the url when navigating to a menu item inside the admin console.

Examples:

name=menu_item&menu_id=111

Automatic Authentication

These extra parameters can be applied to any deep link, or even used just on their own, to log the user in.

Password Authentication

Parameters

  • auth_username (required): The email address of the contact
  • auth_password (required): The DeskDirector password of the contact
  • auth_remember_me (optional): Determines whether or not the user remains logged in after they close their browser/app. Defaults to true.

Examples:

name=ticket&ticket_id=123456&auth_username=bob@company.com&auth_password=mypassword123

auth_username=bob@company.com&auth_password=mypassword123

Passwordless Token Authentication

Parameters:

  • auth_username (required): The email address of the contact
  • auth_token (required): The DeskDirector Passwordless Token generated for the contact
  • auth_remember_me (optional): Determines whether or not the user remains logged in after they close their browser/app. Defaults to true.

Examples:

name=ticket&ticket_id=123456&auth_username=bob@company.com&auth_token=123456&auth_remember_me=false
auth_username=bob@company.com&auth_password=mypassword123
Access Token Authentication

Access Token authentication is replacement to Global magic token. It is more secure. The advantage compare to global magic token is time lock and user lock.

It is introduced in server release 18.99.1

  • Token cannot be modified to access different user
  • Token only available for maximum of 24 hours. (Depends on expires time it used to create the token)
Access Token suffer similar drawback as Global magic token when regarding to email CC, FW, BCC.
If the login link with access token been forward, CC or BCC to other user, they can login on behalf of main receiver.
We recommend use with cautious. DeskDirector do not take responsibility when login link been shared among different user.

Access Token can be created through following API.

// contact-id: Contact numeric identifier
// expiresIn: Expires in seconds. Minimum is 3600 (1hr) and maximum is 3600 * 24 (24hr).
https://[your-subdomain].deskdirector.com/api/v2/user/contact/[contact-id]/userkey?expiresIn=36000

Authorization of API can be admin cookie or API Key.

The response of above API call, you should get access token inside.

{
  "userKey": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...{very long token}",
  "expires_in": 3600,
  "expires_on": 1572846902
}

Once you have this user key (access token). You can pass in through portal deep link.

  • access_token(required): The DeskDirector Access Token created through API
  • auth_remember_me (optional): Determines whether or not the user remains logged in after they close their browser/app. Defaults to true
https://[your-subdomain].deskdirector.com/portal/deeplink?access_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ...&auth_remember_me=true

How did we do?

Subscribing to Chat Webhooks

Webhook Example with Zapier

Contact