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