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

Entity Context

Both parameters must be supplied together. Operator loads the record from the connected instance and tells the agent its type, its id and its readable name, so the user can say "summarise this" or "who bought it last month" without naming the record.

The record stays part of the context for the whole session.

Examples:

/?entityType=General.Products.Products&entityId=8F42B1C3-5D9E-4A7B-B2E1-9C3F4D5A6E7B
/?instance=demo&entityType=Crm.Sales.SalesOrders&entityId=8F42B1C3-5D9E-4A7B-B2E1-9C3F4D5A6E7B
/?instance=demo&entityType=Crm.Sales.SalesOrders&entityId=8F42B1C3-...&input=Summarise%20this&autorun=1

If the record cannot be read (wrong id, unknown entity type, or no read rights), a warning is shown and the agent still receives the entity type and id — only the readable name is missing.

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 the mode-aware default: Business Specialist in internal mode, Sales Executive in client mode, and ERP Advisor when no instance is connected. 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

Update Mode

Applied on page load. Ignored when opening an existing conversation URL (/c/:id) — the conversation's own stored mode stays authoritative.

Examples:

/?updateMode=read-write
/?agent=business_specialist&updateMode=read-write

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. Entity context is loaded after the instance settles (waits for tokens)
5. Agent preselection executes after instance settles and user agents load
6. App full-screen resolves slug to app and enters full-screen mode (waits for user apps to load)
7. 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