<!-- BusyBot node reference — https://busybot.net/tools/openai-chat/ -->

> Node: OpenAI Chat (`openai_chat`) · Action · v1
> Category: AI · Credentials: OpenAI (`openai`)
> Updated: 2026-08-16

# OpenAI Chat

> Chat with OpenAI models using the Responses API.

## Overview

OpenAI Chat uses the Responses API (POST /responses) to generate text completions from OpenAI language models. Supports configurable model selection, system prompts, temperature, top-p, frequency/presence penalties, and max output tokens. Each input item receives a separate completion. The response text is placed in a configurable field name in the output JSON, along with model and usage metadata.

**Category:** AI  
**Tool Name:** `openai_chat`  
**Version:** 1

**Appearance:** Icon: `openai` | Color: `#10a37f`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool requires **OpenAI** credentials.
See the [Credentials Guide](https://busybot.net/credentials/openai/) for setup instructions.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Model | `options` | No | (current default) | The OpenAI model to use for chat completion. Always uses the latest version (auto-updated). |
| | | | | Options: the OpenAI chat models available to your workspace — pick one from the dropdown. |
| System Prompt | `string` | No | `You are a helpful assistant.` | System instructions that set the behavior and persona of the model. Defaults to a generic helpful-assistant prompt — override per workflow as needed. Supports expressions. |
| User Message | `string` | Yes | — | The user message or prompt to send. If empty, falls back to item.json.message or item.json.prompt. Supports expressions. |
| Attachment File ID | `string` | No | — | Optional OpenAI file ID (file-...) returned by openai_file_upload. When provided, the file is referenced by ID and attached as a content block on the user message — no re-upload, no binary input needed. Falls back to item.json.attachmentFileId if empty. Supports expressions like {{ $json.fileId }} from an upstream openai_file_upload node. |
| Attachment Type | `options` | No | `document` | How the model should interpret the attached file. Only used when Attachment File ID is set. |
| | | | | Options: `document` (PDF / text / code / CSV / structured file), `image` (jpg / png / gif / webp) |
| Options | `collection` | No | `{}` | Optional model-tuning settings — add only the fields you need. |
| — Temperature | `number` | No | `1` | Sampling temperature (0-2). Lower values make output more focused and deterministic. |
| — Max Output Tokens | `number` | No | `4096` | Maximum number of tokens the model can generate in the response. |
| — Top P | `number` | No | `1` | Nucleus sampling: only consider tokens with top_p cumulative probability (0-1). |
| — Frequency Penalty | `number` | No | `0` | Penalize tokens based on how frequently they appear in the text so far (-2 to 2). |
| — Presence Penalty | `number` | No | `0` | Penalize tokens based on whether they have appeared in the text so far (-2 to 2). |
| — Response Field Name | `string` | No | `response` | Field name in the output JSON where the response text will be placed. |
| Include Input | `boolean` | No | `false` | Whether to include the original input item fields in the output alongside the response. |
| Max Concurrency | `number` | No | `10` | Maximum number of items to process concurrently. |

## Output Data

One output item per input item. The reply text lands on the field named by **Response Field Name** (`response` by default), with `model` and `usage` beside it. The rest of the input item JSON is dropped unless **Include Input** is on; binary data on the input item is forwarded unchanged.

```json
{
  "response": "The generated reply text",
  "model": "the model that produced the reply",
  "usage": { "input_tokens": 128, "output_tokens": 256 }
}
```

- `usage` is the token accounting returned by the API for that call.
- Turning on **Include Input** merges the original item fields into the same object, so make sure your response field name does not collide with an incoming field.

Reference the result downstream by expression, e.g. `{{ $json.response }}`.

## Usage Examples

- Send a prompt to an OpenAI model and get a text response
- Summarize text using OpenAI with a system prompt
- Translate content with a low temperature for consistent output
- Generate product descriptions from input data
- Ask a question for each row in a dataset

## Example Configuration

Ask a question with the default model and system prompt:

```json
{
  "type": "openai_chat",
  "parameters": {
    "userMessage": "Explain what a Bloom filter is in two sentences."
  }
}
```

Classify each item deterministically and keep the original fields:

```json
{
  "type": "openai_chat",
  "parameters": {
    "systemPrompt": "Classify the sentiment of the text as POSITIVE, NEGATIVE, or NEUTRAL. Reply with one word only.",
    "userMessage": "{{ $json.review }}",
    "includeInput": true,
    "maxConcurrency": 20,
    "options": {
      "temperature": 0,
      "maxOutputTokens": 8,
      "responseFieldName": "sentiment"
    }
  }
}
```

Ask about a file uploaded by an upstream **OpenAI File Upload** node:

```json
{
  "type": "openai_chat",
  "parameters": {
    "userMessage": "Summarize the key terms in this contract.",
    "attachmentFileId": "{{ $json.fileId }}",
    "attachmentType": "document",
    "options": {
      "temperature": 0.2,
      "responseFieldName": "contractSummary"
    }
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

OpenAI Chat sends each input item to an OpenAI language model via the Responses API and returns a generated text completion. Use it when your workflow requires text generation, summarization, classification, or reasoning tasks powered by configurable OpenAI models. Each output item contains the completion text in a configurable field name, along with the model identifier and token usage metadata.