n8n-nodes-openai-chatkit

Custom n8n node for interacting with the OpenAI ChatKit (Agent Builder) beta without having to wire every HTTP call manually.

Features

• Create session – request a short-lived client_secret for an Agent Builder workflow and keep it stored in the node state.
• Refresh session – rotate the stored client_secret before it expires.
• Send message – deliver user text (plus optional system prompt, metadata, and thread id) to the workflow and receive the full ChatKit response.
• Manual session override – provide an existing session_id/client_secret pair directly when you do not want to use the stored state.

The node talks straight to the OpenAI API using the ChatKit beta header, so all you need is an API key with access to the feature preview.

Installation

npm install n8n-nodes-openai-chatkit

During local development you can build the project with:

npm install
npm run build

Copy the generated dist folder to your n8n custom nodes directory (usually ~/.n8n/custom/) and restart n8n.

Credentials

Create credentials of type OpenAI ChatKit API with the following fields:

• API Key – required. Must have access to the ChatKit beta.
• Base URL – optional. Defaults to https://api.openai.com. Override only when routing through a compatible proxy.
• Organization / Project – optional. Forwarded as OpenAI-Organization / OpenAI-Project headers when provided.

Node usage

1. Session → Create

   • Provide the Agent Builder workflowId and (optionally) a userId, metadata JSON, or extra session options JSON.
   • The response stores session.id, client_secret, and expires_at in the node state and returns the masked values.

2. Message → Send

   • Supply the text in Message Text and map any incoming data from previous nodes.
   • By default the stored session is reused. Switch Session Source to Provide Manually if you want to paste a session id and client secret instead.
   • Optional fields: workflow override, thread id, role, system prompt, message metadata, and timeout.

3. Session → Refresh (optional)

   • Requests a new client_secret for the stored session and updates the node state.

4. Session → End (Local)

   • Clears the stored session information so the next run can start fresh.

API calls performed

The node issues the following REST requests against the configured base URL:

• POST /v1/chatkit/sessions
• POST /v1/chatkit/sessions/{session_id}/refresh
• POST /v1/chatkit/sessions/{session_id}/messages

If an account still serves the earlier /v1/chat/sessions routes, the node automatically retries against those paths so you do not have to adjust any settings. Each request includes the OpenAI-Beta: chatkit_beta=v1 header required for the ChatKit preview.

Looking for end-to-end samples? The openai-chatkit-starter-app and openai-chatkit-advanced-samples repositories demonstrate how the workflows respond to these APIs.

Publishing

The repository ships a GitHub Actions workflow (.github/workflows/release.yml) that publishes the package to npm whenever a v*.*.* tag is pushed. The workflow runs npm ci, npm run build, and npm publish --provenance using the configured NPM_TOKEN secret.

License

MIT