Portal Deep Linking

Deep Linking Overview

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.

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 browser's 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. Let's 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]

Supported Deep Links

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 behaviour.

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 Service Type / Form

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

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 deeplink 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 that was 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

Introduced in Server Release 18.99.1, Access Token authentication is a replacement to Global magic token:

• The token cannot be modified to access a different user
• The token is only available for a maximum of 24 hours. (Depends on the expiry time set for the token during creation)

Access tokens can be created via the following API endpoint:

// 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

Authorisation to the API can be either via an admin cookie or an API Key.

In the response to the above API call, you should get an 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 the portal deep link.

• access_token(required): The DeskDirector Access Token created through the 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