Passing Context via URL Parameters to Marketing Agents
Last updated: October 26, 2026
If you are linking people to a Docket agent's standalone page, you can carry what you already know about them in the link itself. Add ctx_ query parameters to the URL and the agent starts the conversation already knowing their name, company, or plan. No JavaScript required.
This works on the agent's own page, not on your website. If the widget is embedded on your marketing pages, use the AISeller JavaScript API instead.
Where do URL parameters work, and where do they not?
URL context is read by the agent page itself. That means it applies in two places:
The standalone page, the full page experience Docket hosts for the agent.
An iframe whose
srcis that standalone page.
It does not apply to your own website pages. The widget script embedded on your site does not read ctx_ parameters from the page it sits on. Adding ?ctx_company=Acme to your pricing page does nothing.
Iframes have one more constraint worth knowing early. The iframe loads on a Docket domain, so it cannot read the address bar of the page hosting it. Put the ctx_ parameters into the iframe's own src attribute, and build that src from your page's code.
What do you need before you start?
The fields configured on the agent under Dynamic Context Ingestion. See Setting Up Dynamic Context Ingestion.
The agent's standalone page URL.
A decision about which values are safe to put in a browser address bar.
How do you find the standalone page URL?
Sign in to app.docketai.com and open Marketing Agent Configuration.
Select your agent, then open the Deploy tab.
Find Standalone Page and select Copy URL.

How do you build the URL?
Prefix every context parameter with ctx_. Docket strips the prefix before handing the values to the agent, so ctx_company arrives as company and must match a variable named company.
https://your-standalone-agent.example/?ctx_name=Jordan&ctx_company=Northstar%20Labs&ctx_plan=EnterpriseThat link produces this context object:
{
name: "Jordan",
company: "Northstar Labs",
plan: "Enterprise"
}Only parameters starting with ctx_ are read. Campaign parameters such as utm_source and gclid are ignored by this path, so they are safe to keep in the same link.
How do you generate the link safely in code?
Use URL and URLSearchParams rather than joining strings. They encode spaces, ampersands and accented characters correctly.
const url = new URL("https://your-standalone-agent.example/");
url.searchParams.set("ctx_name", "Jordan");
url.searchParams.set("ctx_company", "Northstar Labs");
url.searchParams.set("ctx_plan", "Enterprise");
const standaloneUrl = url.toString();The same object builds an iframe source:
document.getElementById("agent-frame").src = url.toString();What are the limits on URL context?
Docket reads up to 50 ctx_ parameters, and the values together can total up to 8,000 characters.
Both limits stop the reader rather than skipping one field. When the count or the total length is passed, Docket stops reading at that point and every remaining ctx_ parameter is dropped. There is no error and nothing is written to the console, so a long value early in the link can quietly cost you every field after it.
Two habits avoid this. Put your most important parameters first, and keep long free text out of the URL entirely.
Rule | Behavior |
|---|---|
Value type | Every URL value arrives as a string, including numbers and |
Empty key | A bare |
Repeated key | The last occurrence wins, and each copy counts toward both limits. |
No parameters | Opening the page with no |
Because values arrive as strings, write the variable's Context for Agent description so the agent knows how to read them. For example, tell it that employees holds a headcount figure.
Which values should stay out of the URL?
A URL is visible. It is stored in browser history, forwarded in referrer headers, captured by analytics, written into server logs, and included in screenshots people paste into tickets.
Keep passwords, access tokens, payment details, health information and government identifiers out of ctx_ parameters. When a value should not be visible, call setContext() from your own page instead. Security Guidelines for Passing Visitor Context covers how to choose fields.
How do you check that it works?
Open the generated URL in a private browser window.
Start a conversation.
Ask the agent a question that should use one of your variables.
Confirm the agent uses the value the way the variable description tells it to.
Open the standalone URL again with no
ctx_parameters and confirm the earlier values are gone.
Frequently asked questions
Why is nothing reaching the agent from my URL?
Check three things in order: Dynamic Context Ingestion is turned on for the agent, every parameter carries the ctx_ prefix, and you are opening the agent's standalone page rather than a page on your own site.
Why do the first few fields work and the rest get ignored?
You have most likely passed the 8,000 character total or the 50 parameter count. Docket stops reading at that point, so everything after it is dropped. Shorten the long values and re-test.
Can I put ctx_ parameters on my own website pages?
No. The embedded widget does not read them from the host page. Use setContext() on your site, which is covered in Using the AISeller JavaScript API.
My agent is in an iframe. Can it read the parent page's URL?
No. The iframe runs on a different origin from your page, and browsers block it from reading the parent address bar. Write the ctx_ parameters into the iframe's src yourself.
Do utm_ parameters reach the agent?
Not through this path. Only the ctx_ prefix is read. If the agent needs a campaign value, configure a variable for it and pass it as ctx_ as well.
A value with a space or an ampersand arrives broken. Why?
It was not URL encoded. Build the link with URLSearchParams as shown above rather than joining strings by hand.