URL Parameters

Deep linking, embedding, and pre-configuring the user experience

The chat interface supports URL parameters for deep linking, embedding, and pre-configuring the user experience.

Layout & Display

Examples:

/?layout=embedded
/?theme=light
/?layout=embedded&theme=dark

Input & Autorun

Examples:

/?input=Show%20my%20orders
/?input=List%20invoices&autorun=true
/?layout=embedded&input=Help%20me&autorun=1

App Full-Screen

The app parameter accepts the app's slug (e.g., my-inventory-app). When set, the entire UI is replaced with the app's preview filling the viewport. This can be combined with instance, enterprise, and other parameters for full ERP context.

Examples:

/?app=my-inventory-app
/?app=my-inventory-app&instance=demo&enterprise=ACME
/?app=my-inventory-app&layout=embedded

Error Handling

Instance Selection

The parameter accepts:

• UIN (subdomain): e.g., mycompany
• Full Base URL: e.g., https://mycompany.my.erp.net
• Hostname without protocol: e.g., mycompany.my.erp.net

If the instance is found in the user's connections, it becomes the active connection. If not found, an error toast is displayed.

Examples:

/?instance=mycompany
/?instance=https://mycompany.my.erp.net
/?instance=demo.my.erp.net

Enterprise Context

Matching Logic

• GUID: Exact match (case-insensitive)
• Name: Contains match (case-insensitive)

The enterprise context is applied after the instance connection is established. If a match is found, the context is set and the UI updates accordingly.

Examples:

/?enterprise=My%20Company%20Ltd
/?enterprise=8F42B1C3-5D9E-4A7B-B2E1-9C3F4D5A6E7B
/?enterprise=ACME&enterpriseLocation=Warehouse%201
/?instance=demo&enterprise=Partner%20Corp

Agent Preselection

Resolution order (case-insensitive, first match wins)

1. System agent key — e.g. erp_advisor, business_specialist, sales_executive, erp_manager, partner, app_builder, agent_builder.
2. User-agent identifier — the short identifier defined on the user agent.
3. User-agent UUID — the agent's id.

Names are not matched.

Availability

The agent must be available to the signed-in user:

• System agent — must satisfy the user's account level and be supported in the current connection mode (unconnected / internal / client).
• User agent — must be owned by the user or shared with them.

If the value doesn't match anything the user can access, an error toast is shown and the selection falls back to ERP Advisor (erp_advisor). The same fallback applies when no agent parameter is provided.

Ignored when app=<slug> is set (full-screen app owns the UI) or when opening a specific conversation URL (/c/:id) — the conversation's own agent stays authoritative.

Examples:

/?agent=business_specialist
/?agent=app_builder
/?agent=sales_executive&instance=demo
/?agent=my-importer
/?agent=8f42b1c3-5d9e-4a7b-b2e1-9c3f4d5a6e7b
/?agent=my-importer&input=Import%20today%27s%20file&autorun=1

Combined Examples

Embedded Chat with Pre-filled Input

/?layout=embedded&input=What%20are%20my%20pending%20orders%3F

Full Setup with Autorun

/?instance=demo&enterprise=ACME&enterpriseLocation=Main%20Office&input=Show%20dashboard&autorun=true

Execution Order

Parameters are processed in the following order:

1. Parse all parameters on component mount
2. Instance selection executes first (waits for connections to load)
3. Enterprise context selection executes after instance is active (waits for tokens)
4. Agent preselection executes after instance settles and user agents load
5. App full-screen resolves slug to app and enters full-screen mode (waits for user apps to load)
6. Input prefill/autorun executes after context is set

Each step is protected by refs to ensure it only runs once per page load.

Error Handling