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
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" } ]

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	NUMERIC	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.

• 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.

Output parameters

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)

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

[
    {
        "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

{
  "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

• 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.