Deep-Linking

Overview

Deeplinking into Unique Chat allows users to seamlessly access specific chat spaces and execute predefined prompts directly from your application. This integration enhances user experience by providing direct and contextually relevant access to conversations or functionalities within the chat app.

Who is it for

This guide is designed for:

• Developers: Integrating Unique Chat into their applications.
• Administrators: Managing chat spaces and user access.
• Organizations: Looking to streamline workflows and improve communication efficiency.

Benefits

• Streamlined Access: Users can directly access specific chat spaces without navigating through the app.
• Enhanced Productivity: Execute predefined prompts to automate tasks or retrieve information.
• Seamless Authentication: Handles login flows automatically, ensuring a smooth user experience.
• Customizable: Tailor the deeplink URLs to fit your organization's needs.

Use Cases

1. Direct Space Access: Redirect users to a specific chat space for focused discussions.
2. Automated Prompts: Execute commands like "Check system status" or "View latest reports" upon opening the chat.
3. Post-Login Redirection: Ensure users land on the intended chat space even if they need to log in first.
4. Mobile Integration: Enable deeplinks to work seamlessly on mobile applications.

Step-by-Step Guide

Multitenant Region URLs

Use the correct tenant based on your deployment region:

Gateway & Chat APIs

• 🇪🇺 Europe: <https://gateway.unique.app>
• 🇺🇸 US: <https://gateway.us.unique.app>

Identity (OAuth / Login)

• 🇪🇺 Europe: <https://id.unique.app>
• 🇺🇸 US: <https://id.us.unique.app>

Customized App Name

Each customer has a unique, customized app name as part of the base URL:

https://<your_app_name>.unique.app/

• <your_app_name>: The customized application name assigned to your organization (e.g., next).

URL Path and Parameters

To deeplink into a specific space and execute a prompt, use the following URL structure:

https://<your_app_name>.unique.app/chat/space/<space_id>?prompt=<prompt>

Components

• Base URL: https://<your_app_name>.unique.app/
• Path: /chat/space/<space_id>
  • <space_id>: The unique identifier of the chat space (e.g., assistant_xt656gn52wp97rtk4opo5i3n).
• Query Parameter: ?prompt=<prompt>
  • <prompt>: The prompt or command to execute in the chat window, URL-encoded.

Notes

• The space_id typically starts with assistant_ followed by an alphanumeric string.
• The prompt parameter is optional. If omitted, the chat app will open the specified space without executing any prompt.

Handling Authentication

When users are not logged in to [Chat App], the deeplink will still work seamlessly after authentication:

1. User Clicks Deeplink: The user clicks the deeplink URL from your application.
2. Authentication Check: The chat app checks if the user is authenticated.
   • Authenticated: Proceeds to the specified space and executes the prompt.
   • Not Authenticated: Redirects the user to the login page.
3. Post-Login Redirect: After successful login, the user is redirected back to the original deeplink URL with all parameters preserved.

Note: You do not need to manage tokens or session data; the chat app handles the authentication flow internally.

Implementation Steps

1. Obtain Your App Name: Confirm your customized app name provided by [Chat App] (e.g., next).
2. Identify the Target Space:
   • Obtain the space_id for the desired chat space.
   • This can be retrieved from your chat app administrator or support team.
3. Define the Prompt (Optional):
   • Create the prompt parameter value for any prompt you wish to execute.
   • Ensure the prompt is URL-encoded to handle special characters.
4. Construct the Deeplink URL:
   • Combine the base URL, path, and query parameters as per the structure outlined above.
5. Integrate into Your Application:
   • Embed the constructed URL in your application's interface where users can click or be redirected.

Examples

Example 1: Open a Specific Space

Objective: Direct users to a chat space with the ID assistant_abc123xyz.

Customized App Name: next

Deeplink URL:

https://next.unique.app/chat/space/assistant_abc123xyz

Example 2: Open a Space and Execute a Prompt

Objective: Open the space assistant_def456uvw and execute the prompt "Check system status".

Customized App Name: next

Prompt: "Check system status"

URL-Encoded Prompt: Check%20system%20status

Deeplink URL:

https://next.unique.app/chat/space/assistant_def456uvw?prompt=Check%20system%20status

Example 3: User Not Logged In

When a non-authenticated user clicks the deeplink: Deeplink URL:

https://next.unique.app/chat/space/assistant_ghi789rst?prompt=View%20latest%20reports

Flow:

1. User is redirected to the login page.
2. Upon successful login, the user is taken directly to assistant_ghi789rst space.
3. The prompt "View latest reports" is executed automatically.

Tips & Tricks

• URL Encoding: Always URL-encode the prompt parameter to handle spaces and special characters.
  • Use the standard encoding for modern browsers as the prompt.
• Parameter Validation: Verify that the space_id and prompt are correct and properly formatted.
• Avoid Sensitive Data in URLs: Do not include confidential information in the URL parameters.
• User Communication: Inform users that they might need to log in to access the chat app.
• Contact your [Chat App] administrator or support team to obtain the space_id for the desired chat space.

Limitations

• Invalid space_id: If the space_id is incorrect, the chat app will display an error or redirect to a default space.
• Character Limit: While there is no strict limit, keep URLs under 2000 characters for browser compatibility.
• Mobile Support: Ensure the mobile application supports opening web URLs for deeplinks to function.