How to Deeplink into Unique Chat from Your Application

Welcome to the guide on integrating deeplinks to Unique Chat from your application. This document will help you understand how to construct URLs that allow users to seamlessly access specific spaces and execute prompts within the chat app, enhancing their overall experience.

Table of Contents

Introduction

Integrating deeplinks to [Chat App] from your internal services allows users to:

• Access Specific Spaces: Automatically select a chat space upon opening the app.

• Execute Specific Prompts: Run predefined commands or messages in the chat window.

This integration streamlines the user experience by providing direct and contextually relevant access to conversations or functionalities within the chat app.

Deeplink URL Structure

Customized App Name

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

• <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:

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:

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:

Example 3: User Not Logged In

When a non-authenticated user clicks the deeplink:

Deeplink URL:

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.

Best Practices

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

Frequently Asked Questions

Q1: How do I find my space_id?

A: Contact your [Chat App] administrator or support team to obtain the space_id for the desired chat space.

Q2: What happens if the space_id is invalid?

A: The chat app will display an error message or redirect the user to a default space.

Q3: Can we use this deeplink mechanism for mobile applications?

A: Yes, as long as the mobile application supports opening web URLs.

Q4: Is there a character limit for the prompt parameter?

A: While there is no strict limit, it's advisable to keep URLs under 2000 characters for maximum browser compatibility.