Portal Deep Linking
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://
- Web Client:
- 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]
ddportal:// protocol with the operating system automatically.Any links starting with this protocol will be forwarded to the application.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 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 linkaction(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 engineersclose: Prompt the user to close the ticketapprove: Prompt the user to approve the ticketdecline: Prompt the user to decline approval for the ticketauto_approve: Automatically approve the ticket, no reason is givenauto_decline: Automatically decline approval for the ticket, no reason is givenreopen: Prompt the user to reopen the ticketflag: Prompt the user to flag the ticketfasttrack: Prompt the user to FastTrack the ticketforms: 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 toopen.open: Show open ticketsclosed: Show closed ticketsapproval: 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
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"e_id={quote_id}
Parameters:
quote_id(required): The id of the quote.=
Examples:
name=quote"e_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 contactauth_password(required): The DeskDirector password of the contactauth_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 contactauth_token(required): The DeskDirector Passwordless Token generated for the contactauth_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)
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 APIauth_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
