# OPENAICHAT ## Overview The **OPENAICHAT** workflow application lets you interact with an OpenAI chat model. ## How it works * The application allows you to interact with OpenAI completion models. * Application logs are available. These can be specified by setting the value of the `OpenAIChatLogLevel` parameter in the `web.config` file to `0` to deactivate logs, `1` for error logs, `2` for information logs, or `3` for debug logs; the default value is `0`. ## Required parameters

Parameter	Type	Direction	Description
`MODEL`	TEXT	IN	ID of the model to use You can find available models at the following link: https://platform.openai.com/docs/models/; the endpoint used by default is `/v1/chat/completions`.

You can use either of the following configurations: with system/user messages, with a message number, or with a JSON message array. ### With system/user messages

Parameter	Type	Direction	Description
`SYSTEM_MESSAGE`	TEXT	IN	The system message content
`USER_MESSAGE`	TEXT	IN	The user message content

### With a message number

Parameter	Type	Direction	Description
`MESSAGE_ROLEx`	TEXT	IN	The type of the message, where `x` corresponds to the message number; the value should be `assistant`, `system`, or `user`
`MESSAGE_CONTENTx`	TEXT	IN	The user message content, where `x` corresponds to the message number

### With a JSON message array

Parameter Type Direction Description

Parameter	Type	Direction	Description
`MESSAGE_JSON`	TEXT	IN	The JSON array message object; the structure should match the following: `[ { "role": "assistant/system/user", "content": "First message content" }, { "role": "assistant/system/user", "content": "Second message content" } ]`

MESSAGE_JSON

TEXT

The JSON array message object; the structure should match the following:

[
    {
        "role": "assistant/system/user",
        "content": "First message content"
    },
    {
        "role": "assistant/system/user",
        "content": "Second message content"
    }
]

## Optional parameters

Parameters	Type	Direction	Description
`API_KEY`	TEXT	IN	OpenAI API key By default, this value comes from the `OpenAIApiKey` parameter in the `web.config` file.
`URL`	TEXT	IN	API endpoint; this value comes from the `OpenAIChatApiUrl` parameter in the `web.config` file, if it's been defined
`TEMPERATURE`	NUMERIC	IN	Sampling temperature, between `0` and `1` Default value: `1` Higher values (e.g. `0.8`) will make the output more random, while lower values (e.g. `0.2`) will make it more focused and deterministic.
`TOP_P`	NUMERIC	IN	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with `top_p` probability mass Default value: `1` 📌 Example: A value of `0.1` means only the tokens comprising the top 10% probability mass are considered.
`FREQUENCY_PENALTY`	NUMERIC	IN	Number between `-2.0` and `2.0` Default value: `0` Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
`MAX_TOKENS`	NUMERIC	IN	Maximum number of tokens that can be generated in the chat completion Default value: `256` ✏️ Note: For reasoning models (o1, o3, GPT-5 series), use `MAX_COMPLETION_TOKENS` instead. If both `MAX_TOKENS` and `MAX_COMPLETION_TOKENS` are specified, `MAX_COMPLETION_TOKENS` takes precedence.
`MAX_COMPLETION_TOKENS`	NUMERIC	IN	Maximum number of tokens to generate in the completion This parameter is required for reasoning models (o1, o3, GPT-5 series) and takes precedence over `MAX_TOKENS` when both are specified. For reasoning models, this value includes both reasoning tokens and visible completion tokens.
`REASONING_EFFORT`	TEXT	IN	Controls the effort level for reasoning models; only applicable to reasoning models (o1, o3, GPT-5 series). Values: `low`, `medium`, or `high` ⚠️ Important: Do not use this parameter with non-reasoning models (e.g. GPT-4o, GPT-4-turbo) as this will cause an API error.
`PRESENCE_PENALTY`	NUMERIC	IN	Number between `-2.0` and `2.0` Default value: `0` Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics
`RESPONSE_FORMAT`	TEXT	IN	Format of the response: `json_object`, `text`, or `json_schema` When the value is `json_object`, the system prompt should contain the JSON keyword. When the value is `json_schema`, the expected schema must be provided in the `RESPONSE_FORMAT_JSON_SCHEMA` parameter.
`RESPONSE_FORMAT_JSON_SCHEMA`	TEXT	IN	The JSON schema that will be used by the model to respond. See the `RESPONSE_FORMAT_JSON_SCHEMA` section below for an example.
`APP_RESPONSE_IGNORE_ERROR`	TEXT	IN	Specifies (`Y` or `N`) if error should be ignored Default value: `N` ✏️ Note: In case of error, if the parameter has `Y` as its value, the error will be ignored and defined OUT parameters (`APP_RESPONSE_STATUS` or `APP_RESPONSE_CONTENT`) will be mapped. Otherwise, an exception will be thrown.
`TOOLS`	TEXT	IN	List of tools available to the model, formatted in JSON and compliant with OpenAI's format: https://platform.openai.com/docs/api-reference/chat/create#chat-create-tools See the `TOOLS` section below for an example.
`TOOL_CHOICE_REQUIRED`	TEXT	IN	Specifies whether the model must necessarily choose a tool Values: `Y` or `N` (default).
`PARALLEL_TOOL`	TEXT	IN	Specifies whether the model can choose multiple tools. Values: `Y` (default) or `N`.
`MESSAGE_HISTORY`	TEXT	INOUT	The message history in JSON format The reference structure follows OpenAI's documentation for the `messages` object: https://platform.openai.com/docs/api-reference/chat/create#chat-create-messages
`SELECTED_TOOLS`	TEXT	OUT	The list of selected tool names, separated by commas
`SELECTED_TOOLS_PARAM`	TEXT	OUT	A JSON array representing the list of selected tools along with their parameters See the `SELECTED_TOOLS_PARAMS` section below for an example output.
`SELECTED_TOOLS_COUNT`	TEXT	OUT	The number of selected tools
`RESULT`	TEXT	OUT	Chat result call
`RESULT_CONTENT`	TEXT	OUT	Content of the assistant message
`RESULT_TOTAL_TOKENS`	NUMERIC	OUT	Total of tokens used for generation
`RESULT_COMPLETION_TOKENS`	NUMERIC	OUT	Total of tokens used for generation
`RESULT_PROMPT_TOKENS`	NUMERIC	OUT	Total of token used for the prompt
`RESULT_REASONING_TOKENS`	NUMERIC	OUT	Number of tokens used for internal reasoning by reasoning models (o1, o3, GPT-5 series) These tokens are not visible in the response but count toward usage and billing. Returns `0` for non-reasoning models.
`RESULT_CACHED_TOKENS`	NUMERIC	OUT	Number of prompt tokens that were served from cache Cached tokens are billed at a reduced rate. This is useful for understanding cost optimization from prompt caching.
`APP_RESPONSE_STATUS`	TEXT	OUT	Response status code
`APP_RESPONSE_CONTENT`	TEXT	OUT	Response payload or error message

## Reasoning models OpenAI offers reasoning models (o1, o3, GPT-5 series) that use internal reasoning before generating a response. These models have specific parameter requirements: ### Parameters

Parameter	Description
`MAX_COMPLETION_TOKENS`	Required for reasoning models. Specifies the maximum tokens for the completion, including both reasoning tokens and visible output tokens
`REASONING_EFFORT`	Optional. Controls the depth of reasoning: `low`, `medium`, or `high`. Higher values use more reasoning tokens but may produce better results.

{% hint style="warning" %} * **Use `MAX_COMPLETION_TOKENS` instead of `MAX_TOKENS`** for reasoning models. The `MAX_TOKENS` parameter is deprecated for these models. * **Do not use `REASONING_EFFORT` with non-reasoning models** (e.g., GPT-4o, GPT-4-turbo). These models don't support this parameter and the API will return an error. * **When using `REASONING_EFFORT`, always set `MAX_COMPLETION_TOKENS`**. If `REASONING_EFFORT` is specified without `MAX_COMPLETION_TOKENS`, no token limit is sent to the API (the API will use its default limits). This is intentional because reasoning models reject the `MAX_TOKENS` parameter. * **Reasoning tokens are not visible** in the response content but are included in the token usage count and billing. {% endhint %} ### Output parameters

Parameter Description

Parameter	Description
`RESULT_REASONING_TOKENS`	Number of tokens used for internal reasoning Only populated for reasoning models; returns `0` for other models.
`RESULT_CACHED_TOKENS`	Number of prompt tokens served from cache (applies to all models with prompt caching)

RESULT_REASONING_TOKENS

Number of tokens used for internal reasoning

Only populated for reasoning models; returns 0 for other models.

RESULT_CACHED_TOKENS Number of prompt tokens served from cache (applies to all models with prompt caching)

### Example of reasoning model use ``` MODEL = gpt-5-mini USER_MESSAGE = "Solve this math problem: If a train travels 120 km in 2 hours, what is its average speed?" MAX_COMPLETION_TOKENS = 500 REASONING_EFFORT = medium ``` #### Output ``` RESULT_CONTENT = "Average speed = distance ÷ time = 120 km ÷ 2 h = 60 km/h." RESULT_TOTAL_TOKENS = 124 RESULT_COMPLETION_TOKENS = 95 RESULT_PROMPT_TOKENS = 29 RESULT_REASONING_TOKENS = 64 RESULT_CACHED_TOKENS = 0 ``` ## JSON schema use case Using a JSON schema as a response format enforces the application to respond in a structured manner that aligns with the schema. You can directly extract the returned values to populate specific data; simply specify the name of the property to extract as the parameter name and set the target data in OUT. ## Examples ### `TOOLS`

[
    {
        "name": "GET_STOCK_INFORMATION",
        "description": "Get stock information about a product. If the product is not found, return an error. If the stock is less than 10, return a warning and a purchase order should be done.",      
        "parameters": {
            "type": "object",
            "properties": {
                "product_name": {
                    "type": "string",
                    "description": "The product name"
                },
                "serial_number": {
                    "type": "string",
                    "description": "The product serial number"
                }
            },
            "additionalProperties": false,
            "required": ["serial_number"]
        }
    },
    {
        "name": "PURCHASE_ORDER",
        "description": "Make a purchase order for a product.",    
        "parameters": {
            "type": "object",
            "properties": {
                "product_name": {
                    "type": "string",
                    "description": "The product name"
                },
                "serial_number": {
                    "type": "string",
                    "description": "The product serial number"
                },
                "quantity": {
                    "type": "number",
                    "description": "The quantity of the product to purchase"
                }
            },
            "additionalProperties": false,
            "required": ["serial_number", "quantity"]
        }
    }
]

### `SELECTED_TOOLS_PARAMS` ```json [ { "name": "GET_STOCK_INFORMATION", "id": "call_Vuc2Ga8jP7vUksxG9C0fwpY8", "parameters": { "product_name": "vis", "serial_number": "V45645" } }, { "name": "GET_STOCK_INFORMATION", "id": "call_nq3SCVUk0FjAHCeqOZGNXpC8", "parameters": { "product_name": "boulons", "serial_number": "b456" } } ] ``` ### `RESPONSE_FORMAT_JSON_SCHEMA` ```json { "name": "schema", "schema": { "$schema": "http://json-schema.org/draft-04/schema#", "type": "object", "properties": { "advice": { "type": "string" }, "next_action": { "type": "string", "enum": ["expert","sales","support","logistics",null] }, "confidence_level": { "type": "number" } }, "required": ["advice", "next_action","confidence_level"] } } ``` ## OpenAI-compatible providers The OPENAICHAT application can be used with OpenAI-compatible providers by specifying a custom API endpoint using the `URL` parameter or the `OpenAIChatApiUrl` setting in `web.config`. ### Compatible providers

Provider	Type
Azure OpenAI	Cloud
Ollama	Self-hosted
vLLM	Self-hosted
LocalAI	Self-hosted
LM Studio	Self-hosted
Together AI	Cloud
Groq	Cloud
Mistral AI	Cloud
OpenRouter	Cloud

{% hint style="warning" %} * Do not use `MAX_COMPLETION_TOKENS` and `REASONING_EFFORT` with non-OpenAI providers unless you know the provider supports these parameters. * Use `MAX_TOKENS` for token limits when using non-OpenAI providers. * Some providers may ignore unsupported parameters, while others may return an error. {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.workflowgen.com/admin/9.6/workflow-applications/openai/openaichat.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.