Botium Connector for ChatGPT (OpenAI Responses API)

This is a Botium connector for testing your ChatGPT-based chatbots using the OpenAI Responses API.

Read the Botium in a Nutshell articles first for best results.

How it works

Botium connects to the OpenAI Responses API and relays user messages to a specified ChatGPT model. It maintains a minimal conversation state and returns the assistant reply into Botium.

Works with:

• Botium CLI
• Botium Bindings
• Botium Box

Requirements

• Node.js and npm
• An OpenAI API key with access to the chosen model

Install

Using Botium CLI:

npm install -g botium-cli
npm install botium-connector-chatgpt --save-dev
botium-cli init
botium-cli run

Using Botium Bindings:

npm install --save-dev botium-bindings botium-connector-chatgpt
botium-bindings init mocha
npm install && npm run mocha

Configuration

Create botium.json:

{
  "botium": {
    "Capabilities": {
      "CONTAINERMODE": "chatgpt",
      "CHATGPT_API_KEY": "your-api-key",
      "CHATGPT_MODEL": "gpt-4o-mini",
      "CHATGPT_PROMPT": "You are a helpful assistant."
    }
  }
}

Then run the emulator to validate your config:

botium-cli emulator

Supported Capabilities

• CONTAINERMODE: set to chatgpt to activate this connector
• CHATGPT_API_KEY (required): OpenAI API key
• CHATGPT_MODEL (required): model name, e.g. gpt-4o-mini
• CHATGPT_PROMPT: optional system prompt
• CHATGPT_TEMPERATURE: number
• CHATGPT_MAX_TOKENS: number, mapped to max_output_tokens
• CHATGPT_REASONING_EFFORT: string, passed as reasoning.effort
• CHATGPT_FILE_SEND_MODE: base64 or upload (attachments handling)
• CHATGPT_TOOLS: comma-separated OpenAI tool types
• CHATGPT_INCLUDE: comma-separated include options for Responses API
• CHATGPT_RESPOND_AS_BOTIUM_JSON: boolean, return Botium-style JSON (see below)

Botium-style JSON output (cards, buttons, media, intent)

If CHATGPT_RESPOND_AS_BOTIUM_JSON is enabled, the connector requests a strict JSON Schema response from the OpenAI Responses API and maps the result into the Botium message.

Minimum fields:

• messageText (string, required)

Optional fields:

• buttons (array of objects: text, payload?)
• media (array of objects: mediaUri, mimeType?, altText?)
• cards (array of objects: title, subtitle?, imageUri?, buttons?)
• intent (string)

Example BotiumScript prompt:

#me
Reply as Botium JSON with messageText "Hello", and intent "greeting".

#bot