What the widget puts on your page
When the chat runtime starts it installs a small set of named functions on the page for you to call. There are eleven of them and they have been stable for years, which is why they still carry their original names.
Nine are setters: the visitor's name, their email, the department, the subject, the question, a block of custom data, a block of context data, a product name and a product key. Two open the chat.
They exist so that a page which already knows who it is talking to does not have to make the visitor type it again. If somebody is signed in to your site, your page knows their name and address; asking for it a second time in the pre-chat form is friction you introduced yourself.
The two open functions are the same function
There is an open call with two names, and both do the same thing. This is not a quirk to work around, just history: one name is older, both are kept so that pages written against either keep working.
The interesting part is what happens when you call it too early. If the widget has not finished starting, the open does not fail and does not throw. It records that an open was requested and performs it as soon as the widget is ready.
That makes it safe to wire the call to a button that a visitor might hit during page load. It also means the call returns false in that case, while returning true once the widget exists. It is the only one of these functions whose return value carries any information at all.
The setters do not care when you call them
Values you set are stored by the runtime and applied to the live chat instance whenever there is one. Set a name before the widget has started and the name is waiting for it; set one afterwards and it is applied immediately.
This removes the usual reason for a load-order dance. You do not need to wait for a ready event, poll for the widget, or delay your script. Call the setter at the point in your page where the value is actually known.
Later calls overwrite earlier ones. On a single-page application where the signed-in user can change without a page reload, calling the setters again after the change is the correct and sufficient fix.
A successful-looking call proves nothing
Every setter returns true. Always. It returns true for a value it stored, for an empty string, and for a name you misspelled in a way that means nothing will ever read it.
So the return value cannot be used to check that anything worked, and a console session that shows a row of trues is not evidence of a working integration. This trips up more people than any other part of the interface, because it looks like a result and behaves like a constant.
Verify on the receiving side instead. Start a chat and look at what the agent sees, or open a conversation record afterwards and confirm the values are attached to it. Values you set reach the same place the pre-chat form's answers reach, so the stored conversation record is the honest test.
What happens to a value that is not a string
These functions expect text and will convert whatever you give them. Numbers and booleans become their obvious string forms. Null and undefined become an empty string rather than the words null or undefined, which is the sensible behaviour and the one people assume is not happening.
An object or an array is converted to JSON. That is genuinely useful for the custom data and context data setters, where a structured payload is often what you have, and it is almost never what you want for a name or an email.
The practical rule: pass a string for anything a human will read, and let the conversion do its work only for the data blocks. An empty string is a legitimate value, so setting a field to null is how you deliberately clear it.
The name setter takes an optional second argument, a key that identifies the visitor to your own systems. None of the other setters take a second argument, and passing one to them does nothing.
When your own function wins instead
The runtime will not overwrite a function of the same name that your page defined first. If your code already has something called by one of these names when the widget starts, yours is left alone and the widget's version is never installed.
This is deliberate and it is the right default, because silently replacing a page's own function would be worse. It is also a genuinely confusing failure when it happens, because your calls succeed, return nothing unusual, and have no effect on the chat.
It bites most often on pages carrying an older integration, a tag manager template somebody wrote years ago, or a helper written to wrap these very functions and given the same name as the thing it wraps. If pre-filling silently does nothing, check whether something on the page defined these names before the widget loaded.
The runtime does replace its own earlier versions, so re-initialising the widget is not affected.
What to send, and what to keep to yourself
Send what removes typing: a name, an email address you already hold, the department implied by the page they are on, and a question stem when the context makes one obvious. Every field you fill is a field the visitor does not have to.
Do not send anything you would not put in an email to that visitor. These values travel from the page and are visible to anyone who can read your page source, so an internal account risk score or a plan-tier label you would not say out loud does not belong here.
Treat a pre-filled identity as a convenience rather than as proof of who somebody is. Anything on the page can be changed by whoever is holding the browser, so a chat widget is not a place to make an authorisation decision. Decide what is worth passing before you decide how, and the judgement side of that question is worth reading alongside the mechanics here.
What to measure
Measure the pre-chat form completion rate before and after you wire this up. That is the number pre-filling is supposed to move, and if it does not move you have either filled fields nobody was struggling with or filled nothing at all.
Then check how many conversations arrive with an email attached. A gap between the share of visitors your page can identify and the share of chats carrying an address usually means the setters are running on some pages and not others.
Watch for the silent failure specifically. Pick one page a week, start a real chat from it, and confirm the values arrive. It takes two minutes and it catches the collision above, which no error message will ever tell you about.