URL-Encoded Messages

The Sophosic Platform supports initiating conversations directly through URL parameters, enabling seamless integration with shortcuts, action buttons, and third-party applications.

Interactive URL Builder

Generated URL

Enter your username, SOP name, and message to generate a shareable URL

Your URL will appear with a QR code and copy button

Supported Parameters

Message Parameters

Multiple parameter names are supported for flexibility:

message - Primary parameter for message content
msg - Short form for mobile use
m - Ultra-short form for constrained environments
query - Alternative for search-like queries
q - Short form of query

Chat Mode Parameters

Configure AI behavior and capabilities:

reasoning / think / mode - Reasoning effort level (minimal, low, medium, high)
web / websearch - Enable web search capabilities (true, false, 1, 0, yes, no)

Usage Examples

Basic Message


https://sophosic.ai/?message=Hello%20Sophia

Short Form Message


https://sophosic.ai/?m=What%27s%20the%20weather%20like%20today%3F

Complex Query with Punctuation


https://sophosic.ai/?query=Help%20me%20with%20%22project%20management%22

Message with Deep Reasoning (Think Longer Mode)


https://sophosic.ai/?message=Analyze%20this%20business%20strategy&reasoning=high

Web-Enabled Query


https://sophosic.ai/?message=What%27s%20the%20latest%20news%20about%20AI&web=true

Combined Mode Configuration


https://sophosic.ai/?m=Research%20sustainable%20energy%20solutions&reasoning=high&web=yes

Mobile Deep Linking


sophosic://chat?msg=Schedule%20a%20meeting%20for%20tomorrow&think=high

Integration Examples

iOS Shortcut


// In iOS Shortcuts app
// 1. Add "Ask for Input" action
// 2. Add "Text" action with this URL format:
const userMessage = 'Ask Sophia about my calendar';
const encodedMessage = encodeURIComponent(userMessage);
// Add deep reasoning for complex queries
const url = `https://sophosic.ai/?message=${encodedMessage}&reasoning=high`;
// 3. Add "Open URLs" action

Action Button (macOS/iOS)


# Terminal/Script action
MESSAGE="What are my tasks for today?"
ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$MESSAGE'))")
# Include web search for current information
open "https://sophosic.ai/?m=$ENCODED&web=true"

JavaScript Integration


function openChatWithMessage(message, options = {}) {
  const encodedMessage = encodeURIComponent(message);
  let url = `https://sophosic.ai/?message=${encodedMessage}`;
 
  // Add mode parameters
  if (options.reasoning) {
    url += `&reasoning=${options.reasoning}`;
  }
  if (options.webEnabled !== undefined) {
    url += `&web=${options.webEnabled}`;
  }
 
  window.open(url, '_blank');
}
 
// Usage examples
openChatWithMessage('Help me write a professional email');
openChatWithMessage('Research the latest AI trends', {
  reasoning: 'high',
  webEnabled: true,
});
openChatWithMessage('Quick question about JavaScript', { reasoning: 'low' });

Python Integration


# Python example for automation workflows
import urllib.parse
 
def create_sophia_url(message, reasoning_level='medium', web_enabled=False):
    encoded_message = urllib.parse.quote(message)
    url = f"https://sophosic.ai/?message={encoded_message}"
 
    if reasoning_level:
        url += f"&reasoning={reasoning_level}"
 
    if web_enabled:
        url += "&web=true"
 
    return url
 
# Usage
url = create_sophia_url(
    "Analyze market trends for renewable energy",
    reasoning_level='high',
    web_enabled=True
)

SOP Runner Integration

URL-encoded messages work seamlessly with SOP (Sophosic Operating Protocol) runners, enabling automated workflows and shareable conversational entry points.

SOP URL Format


https://sophosic.ai/sop/{slug}?message={encoded_message}&reasoning={level}&web={true|false}

Use Cases

1. Customer Support Bot


# Direct to billing help
https://sophosic.ai/sop/customer-support?message=Billing%20question&reasoning=medium
 
# Technical support with web search
https://sophosic.ai/sop/customer-support?message=API%20error%20500&web=true

2. Research Assistant


# Automated research task
https://sophosic.ai/sop/research-assistant?message=Summarize%20AI%20trends%202025&reasoning=high&web=true

3. Shared Workflows


# QR code on product → SOP runner
https://sophosic.ai/sop/product-onboarding?message=Setup%20device%20X1000

Visitor Tracking

SOP runners automatically track visitor sessions for analytics:

Visitor ID passed via X-Visitor-ID header (optional)
URL message becomes first message in visitor conversation
Same security and validation as regular chat

API Endpoint

POST /api/sops/{slug}/chat/message

Inherits all URL-encoded message capabilities via URLDecodingExtractor decorator pattern.

Features

Comprehensive URL Decoding - Handles multiple encoding layers, HTML entities, and special characters
Chat Mode Configuration - Control reasoning effort and web search capabilities via URL parameters
Flexible Parameter Names - Multiple aliases for both messages and modes (e.g., m, message, reasoning, think)
Security Validation - Prevents malicious content while preserving legitimate messages
Length Limits - Messages are capped at 2000 characters with truncation warnings
Error Handling - Graceful fallbacks for malformed URLs or encoding issues
Multi-Language Support - Properly handles Unicode, emoji, and international characters
Text Encoding Optimized - Handles special characters and encoding edge cases
Reasoning Levels - Four-tier reasoning system (minimal, low, medium, high) for different use cases
Web Search Integration - Enable real-time web search capabilities for current information

Technical Details

The URL message system automatically:

Extracts messages from supported query parameters in priority order
Parses chat mode configuration from URL parameters (reasoning, web, etc.)
Decodes multiple layers of URL encoding (handles double/triple encoding)
Validates content for security and length requirements
Sanitizes HTML entities and normalizes whitespace
Applies mode configuration to the AI request (reasoning effort, web search)
Initiates the chat conversation automatically with specified modes
Cleans the URL parameters after processing for clean URLs

Mode Parameter Processing

Reasoning Effort: Maps various input formats (high, max, think, longer) to standard levels
Web Search: Accepts multiple boolean formats (true, 1, yes, on, enabled)
Parameter Aliases: Supports multiple names for flexibility (reasoning/think/mode, web/websearch)
Default Behavior: Missing mode parameters use system defaults

Messages and modes are processed client-side for immediate responsiveness, with comprehensive error handling and user feedback through toast notifications.

Backend Parameter Mapping

The platform uses a flexible parameter naming system to support both frontend JavaScript conventions (camelCase) and backend Python conventions (snake_case):

Frontend sends: webEnabled, reasoningEffort (camelCase)
Backend accepts: Both webEnabled/web_enabled and reasoningEffort/reasoning_effort via Pydantic field aliases
Parameter extraction: apps/backend/src/framework/utils/web_enabled.py handles automatic detection and normalization
Validation: Pydantic models in apps/backend/src/api/routes/ai/ai_sdk/models.py provide type safety and automatic conversion

Example Parameter Flow


URL: ?message=test&web=true
  ↓
Frontend: urlMessageResult.modeConfig.webEnabled = true
  ↓
API Request: { "messages": [...], "webEnabled": true }
  ↓
Backend: Pydantic converts to web_enabled field
  ↓
Tool Loading: Web search tools enabled

This dual-convention support ensures compatibility between different parts of the stack without requiring explicit conversion code.

Configuration Reference

Environment Variables

Backend configuration is managed in apps/backend/src/core/config.py:

Variable	Default	Description
`ENABLE_MESSAGE_URL_DECODING`	`true`	Enable/disable URL decoding feature
`MESSAGE_URL_DECODE_MAX_ITERATIONS`	`5`	Maximum iterations for multi-layer decoding
`MESSAGE_MAX_LENGTH`	`2000`	Maximum message length (characters)
`MESSAGE_VALIDATION_STRICT`	`true`	Strict mode: reject malicious content vs sanitize

Security Settings

Strict Mode (MESSAGE_VALIDATION_STRICT=true):

Enabled: Rejects entire message if malicious patterns detected
Disabled: Sanitizes and logs warnings, allows modified message through

Recommended Settings:

Production: STRICT=true (default) - Maximum security
Development: STRICT=false - Easier debugging with warning logs

Performance Impact

Decode Overhead: < 5ms per message
Cache: Results not cached (dynamic content)
Throughput: No measurable impact on concurrent requests

Troubleshooting

Common Issues

Plus Signs Not Preserved

Problem: “C++” becomes “C ” (spaces)

Cause: Your URL encoder is using form encoding (+ for spaces) AND percent encoding (%20)

Solution: Use ONLY percent encoding:


# ✅ CORRECT
import urllib.parse
message = urllib.parse.quote("C++")  # → "C%2B%2B"
 
# ❌ WRONG
message = "C++".replace(" ", "+")  # → "C++" (interpreted as "C  ")

Heuristic: Platform only converts +→space if BOTH + and %XX patterns are present in the same message.

Message Truncated

Warning: ⚠️ Message truncated to 2000 characters

Cause: Message exceeds MESSAGE_MAX_LENGTH limit

Solution:

Split long messages into multiple requests
Increase limit via environment variable (not recommended for security)
Use file attachments for large content

XSS Blocked

Error: ❌ Malicious content detected in message

Cause: Message contains <script>, javascript:, or other XSS patterns

Solution: This is working as intended - do not try to bypass. Use plain text or markdown instead of HTML.

Double Decoding Issues

Problem: %2520 becomes %20 instead of (space)

Cause: Message was double-encoded

Solution: Platform automatically handles up to 5 layers of encoding. If still failing, check your encoding pipeline for duplicate encoding steps.

Debug Tips

Check Raw URL: Use browser developer tools → Network tab → Copy request URL
Test with curl: curl "http://localhost:8000/api/chat?message=Test%20message" -v
Review Logs: Backend logs show decoded message at DEBUG level
Run Tests: cd apps/backend && pnpm test tests/test_url_decoding_utils.py -v

FAQ

Q: Do URL messages work for authenticated users? A: Yes, same as anonymous users. Authentication is handled separately.

Q: Can I use URL messages with file attachments? A: URL parameter provides initial message only. Attachments require separate upload via chat interface.

Q: Is there rate limiting on URL messages? A: Standard rate limits apply (same as regular chat messages).

Q: Can I pre-configure reasoning effort for a session? A: Yes via URL parameters, but it only applies to the first message. Subsequent messages use session preferences.