How do I pass a user identity from ChatKit JS widget to an Agent workflow?

API
1

I’m using the ChatKit JS widget on my own site and connecting it to an Agent workflow built in the OpenAI Builder. The chat UI works fine (token exchange, history, etc.), but I can’t figure out the right way to let the agent know who the user is.

Specifically, I want the workflow to have access to a userId for:

  • tool/MCP calls (e.g. fetching user-specific data)

  • or internal context (scoping behavior per user)

Here’s my current setup:

  • Frontend calls my API /api/chatkit/start → creates a ChatKit session via POST https://api.openai.com/v1/chatkit/sessions

  • I send user: "<my-user-id>" in that payload before returning the client_secret to the widget.

That all works. But inside the Agent Builder, I can’t see any way to access that user value.
Questions:

  1. Does user from the ChatKit session become available in the workflow (like session.user or context.user)?

  2. If not, what’s the best practice for passing identity into the workflow?

    • via a metadata or instructions field when creating the session?

    • via an HTTP or MCP tool that fetches it from my backend on the first turn?

  3. Is there any built-in way to template headers or variables (like {{session.user}}) in tool calls?

I just want a clean, supported way for an agent hosted by OpenAI to know which user is chatting through my own frontend.

2

i think i’m asking something similar as the below post, looking forward to using it!

** i can’t include links, it fails when I go to save the reply, however the title of the post is this:

Access session user within the agent builder UI

t/access-session-user-within-the-agent-builder-ui/1362274