Webchat Deep Link APIs
The Webchat Deep Link API allows you to generate personalized webchat URLs with pre-populated user attributes. This enables seamless user experiences by creating direct links to conversations with context already established, perfect for personalized marketing campaigns, support tickets, or authenticated user flows.
Generate Webchat Deep Link
Create personalized webchat URLs for one or more users with pre-populated attributes.
Endpoint: POST /public/api/generate-webchat-deep-link
Headers:
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/jsonRequest Body:
{
"scenario_id": "customer_support",
"dataset": [
{
"user_id": "user_12345",
"attributes": {
"name": "John Doe",
"email": "[email protected]",
"account_type": "premium",
"support_tier": "gold"
}
},
{
"user_id": "user_67890",
"attributes": {
"name": "Jane Smith",
"email": "[email protected]",
"account_type": "standard",
"support_tier": "silver"
}
}
]
}Request Parameters:
scenario_id(required, string) - The scenario ID for the webchat conversationdataset(required, array) - Array of user configurations (max limit configurable)user_id(optional, string) - Unique identifier for the user. If not provided, a UUID will be generated automaticallyattributes(required, object) - Key-value pairs of user attributes to pre-populate in the conversation context
Response:
[
{
"user_id": "user_12345",
"url": "https://short.url/abc123"
},
{
"user_id": "user_67890",
"url": "https://short.url/def456"
}
]Response Fields:
user_id(string) - The user identifier (provided or auto-generated)url(string) - The shortened deep link URL for this user
How It Works
When you generate a webchat deep link:
User Context Creation: The system creates a persistent user context with the provided user ID (or generates a new UUID)
Attribute Population: All provided attributes are added to the user's context
Scalar attributes (strings, numbers) are stored directly
Collection attributes (arrays) are processed appropriately
Composite collection attributes are not currently supported
Deep Link Generation: A fullpage webchat URL is created with:
The specified scenario ID
The user ID
The appropriate app key/access token for the scenario
URL Shortening: The deep link is shortened to create a user-friendly URL
Persistent Context: When a user clicks the link, their context is loaded with all pre-populated attributes, enabling personalized conversations from the first message
Supported Attribute Types
Scalar Attributes
Simple key-value pairs stored as strings or numbers:
{
"name": "John Doe",
"email": "[email protected]",
"account_id": "12345",
"vip_status": "true"
}Collection Attributes (Arrays)
Attributes that accept multiple values:
{
"interests": ["sports", "technology", "travel"],
"preferred_languages": ["en", "es"],
"product_ids": ["PROD-001", "PROD-002", "PROD-003"]
}Arrays can also be provided as comma-separated strings:
{
"interests": "sports,technology,travel"
}Unsupported Types
Composite collection attributes are currently not supported
Complex nested objects beyond simple arrays
Use Cases
Personalized Marketing Campaigns
Generate unique links for email campaigns with customer context:
{
"scenario_id": "sales_campaign",
"dataset": [
{
"user_id": "customer_001",
"attributes": {
"name": "Alice Johnson",
"email": "[email protected]",
"campaign_id": "SPRING2024",
"discount_code": "SAVE20",
"customer_segment": "high_value"
}
}
]
}Support Ticket Integration
Create pre-contextualized support conversations:
{
"scenario_id": "customer_support",
"dataset": [
{
"user_id": "ticket_12345",
"attributes": {
"name": "Bob Williams",
"email": "[email protected]",
"ticket_id": "TKT-12345",
"issue_type": "billing",
"priority": "high",
"account_number": "ACC-98765"
}
}
]
}Authenticated User Sessions
Seamlessly transition authenticated users to chat:
{
"scenario_id": "member_portal",
"dataset": [
{
"user_id": "auth_user_789",
"attributes": {
"name": "Carol Davis",
"email": "[email protected]",
"member_id": "MEM-789",
"subscription_tier": "platinum",
"preferences": ["email_notifications", "sms_alerts"]
}
}
]
}Bulk Link Generation
Generate links for multiple users in a single request:
{
"scenario_id": "onboarding",
"dataset": [
{
"attributes": {
"name": "User One",
"email": "[email protected]",
"cohort": "january_2024"
}
},
{
"attributes": {
"name": "User Two",
"email": "[email protected]",
"cohort": "january_2024"
}
},
{
"attributes": {
"name": "User Three",
"email": "[email protected]",
"cohort": "january_2024"
}
}
]
}Error Responses
404 Not Found - Fullpage Disabled
{
"message": "Fullpage webchat routes are not enabled."
}422 Unprocessable Entity - Validation Errors
{
"message": "The given data was invalid.",
"errors": {
"scenario_id": ["The scenario_id field is required."],
"dataset": ["The dataset field is required."],
"dataset.0.attributes": ["The attributes field is required."],
"dataset.1.user_id": ["User id must be a string"]
}
}422 Unprocessable Entity - Too Many Users
{
"message": "The given data was invalid.",
"errors": {
"dataset": ["Maximum number of users is 100"]
}
}422 Unprocessable Entity - Invalid Scenario
{
"message": "The given data was invalid.",
"errors": {
"scenario_id": ["The selected scenario does not exist."]
}
}401 Unauthorized
{
"message": "Unauthenticated."
}500 Internal Server Error
{
"error": "An error occurred while generating the deep link."
}Best Practices
Security Considerations
User ID Management:
Use unpredictable user IDs for security
Avoid exposing sensitive internal IDs
Consider using UUIDs (auto-generated if not provided)
Attribute Privacy:
Don't include sensitive data that shouldn't persist in user context
Be mindful of data retention and privacy regulations
Ensure attributes comply with your privacy policy
Rate Limiting:
Be aware of any rate limits on link generation
Cache generated links when possible
Batch user link generation when feasible
Performance Optimization
Bulk Generation:
Generate multiple user links in a single request
Respect the maximum users per request limit
Process large user sets in batches
Attribute Efficiency:
Only include necessary attributes
Keep attribute values concise
Avoid large array values when possible
Integration Tips
Link Expiration:
Consider implementing link expiration on your side
Track link usage for analytics
Regenerate links for expired campaigns
User Experience:
Test links before sending to users
Provide fallback URLs if links fail
Monitor link click-through rates
Attribute Naming:
Use consistent attribute naming conventions
Document required vs. optional attributes
Ensure attribute names match your scenario configuration
Example Usage
Python Example
import requests
import json
# Configuration
base_url = "https://your-workspace.cloud.opendialog.ai/public/api"
api_token = "YOUR_API_TOKEN"
headers = {
"Authorization": f"Bearer {api_token}",
"Content-Type": "application/json"
}
# Generate deep links
payload = {
"scenario_id": "customer_support",
"dataset": [
{
"user_id": "user_12345",
"attributes": {
"name": "John Doe",
"email": "[email protected]",
"support_tier": "premium"
}
},
{
"attributes": { # user_id will be auto-generated
"name": "Jane Smith",
"email": "[email protected]",
"support_tier": "standard"
}
}
]
}
response = requests.post(
f"{base_url}/generate-webchat-deep-link",
headers=headers,
json=payload
)
if response.status_code == 200:
links = response.json()
for link in links:
print(f"User {link['user_id']}: {link['url']}")
else:
print(f"Error: {response.status_code}")
print(response.json())cURL Example
curl -X POST \
https://your-workspace.cloud.opendialog.ai/public/api/generate-webchat-deep-link \
-H 'Authorization: Bearer YOUR_API_TOKEN' \
-H 'Content-Type: application/json' \
-d '{
"scenario_id": "customer_support",
"dataset": [
{
"user_id": "user_12345",
"attributes": {
"name": "John Doe",
"email": "[email protected]",
"product_interest": "enterprise_plan"
}
}
]
}'JavaScript Example
const generateDeepLinks = async () => {
const baseUrl = 'https://your-workspace.cloud.opendialog.ai/public/api';
const apiToken = 'YOUR_API_TOKEN';
const payload = {
scenario_id: 'customer_support',
dataset: [
{
user_id: 'user_12345',
attributes: {
name: 'John Doe',
email: '[email protected]',
account_type: 'premium'
}
}
]
};
try {
const response = await fetch(`${baseUrl}/generate-webchat-deep-link`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiToken}`,
'Content-Type': 'application/json'
},
body: JSON.stringify(payload)
});
if (response.ok) {
const links = await response.json();
links.forEach(link => {
console.log(`User ${link.user_id}: ${link.url}`);
});
} else {
console.error('Error:', response.status);
}
} catch (error) {
console.error('Request failed:', error);
}
};
generateDeepLinks();Integration Workflow
A typical integration workflow might look like:
Prepare User Data: Gather user information from your CRM, database, or application
Build Request: Format the data according to the API specification
Generate Links: Call the API to generate personalized deep links
Store Links: Save the generated URLs with user records
Distribute Links: Send links via email, SMS, or display in your application
Monitor Usage: Track link clicks and conversation starts
Analyze Results: Review conversation outcomes and user engagement
This creates a seamless bridge between your existing systems and OpenDialog's conversational capabilities, enabling personalized, context-aware user experiences at scale.
Last updated