Tell the agent what your page already knows, keep it current as the page changes, and open the widget from your own buttons.
The agent always knows which page the visitor is on. Context lets you add what the page knows and the agent cannot see: the plan they are on, the order they are looking at, what is in the cart.
Context is a hint for the agent, not a place for secrets, and it is never proof of identity. Do not pass anything you would not want visible in the browser, and do not expect the agent to treat it as verified.
Pass context at load
data-context takes URL-encoded JSON:
<script
src="https://www.hey.support/api/chat/embed.js"
data-chatbot-id="YOUR_ID"
data-context="%7B%22plan%22%3A%22growth%22%2C%22order_id%22%3A%221234%22%7D"
defer
></script>The decoded value there is {"plan":"growth","order_id":"1234"}. Keep it flat and small; the agent reads it as plain facts.
Update context after load
For context that changes without a page reload, such as a cart that updates as the visitor shops, post a message to your own window:
window.postMessage(
{
type: 'HS_SET_CONTEXT',
payload: { cart_total: 4200, cart_item_count: 3 },
},
'*',
);The widget merges each payload into the visitor's context. This is the same bridge the Shopify and WordPress plugins use, so the agent always has current page context.
Open the widget from your page
A "Chat with us" button of your own can open the panel, optionally with a drafted message:
window.postMessage({ type: 'HS_OPEN', seed: 'I have a question about my order' }, '*');The seed fills the composer; the visitor still presses send. There is deliberately no way for the host page to send a message as the visitor.