Implementation:Openai Openai python Chat Completion Message Param

Knowledge Sources	openai-python OpenAI Chat API Reference
Domains	NLP, Prompt_Engineering
Last Updated	2026-02-15 00:00 GMT

Overview

Concrete typed message format for constructing Chat Completions conversations provided by the OpenAI Python SDK.

Description

ChatCompletionMessageParam is a TypedDict union type representing the allowed message formats for the Chat Completions API. It is a discriminated union of role-specific message types: ChatCompletionSystemMessageParam, ChatCompletionUserMessageParam, ChatCompletionAssistantMessageParam, ChatCompletionToolMessageParam, ChatCompletionFunctionMessageParam, and ChatCompletionDeveloperMessageParam. Each sub-type defines which fields are valid for that role.

Usage

Use these types when constructing the messages parameter for chat.completions.create(). While plain dictionaries work, using the typed variants provides IDE autocompletion and type checking.

Code Reference

Source Location

• Repository: openai-python
• File: src/openai/types/chat/chat_completion_message_param.py
• Lines: L1-30

Signature

ChatCompletionMessageParam = Union[
    ChatCompletionSystemMessageParam,
    ChatCompletionUserMessageParam,
    ChatCompletionAssistantMessageParam,
    ChatCompletionToolMessageParam,
    ChatCompletionFunctionMessageParam,
    ChatCompletionDeveloperMessageParam,
]

# Key sub-types (TypedDicts):
class ChatCompletionSystemMessageParam(TypedDict, total=False):
    content: Required[Union[str, Iterable[ChatCompletionContentPartTextParam]]]
    role: Required[Literal["system"]]
    name: str

class ChatCompletionUserMessageParam(TypedDict, total=False):
    content: Required[Union[str, Iterable[ChatCompletionContentPartParam]]]
    role: Required[Literal["user"]]
    name: str

class ChatCompletionAssistantMessageParam(TypedDict, total=False):
    role: Required[Literal["assistant"]]
    content: Optional[Union[str, Iterable[ChatCompletionContentPartTextParam]]]
    tool_calls: Iterable[ChatCompletionMessageToolCallParam]
    name: str

class ChatCompletionToolMessageParam(TypedDict, total=False):
    content: Required[Union[str, Iterable[ChatCompletionContentPartTextParam]]]
    role: Required[Literal["tool"]]
    tool_call_id: Required[str]

Import

from openai.types.chat import ChatCompletionMessageParam
from openai.types.chat import (
    ChatCompletionSystemMessageParam,
    ChatCompletionUserMessageParam,
    ChatCompletionAssistantMessageParam,
    ChatCompletionToolMessageParam,
)

I/O Contract

Inputs

Name	Type	Required	Description
role	Literal["system", "user", "assistant", "tool", "developer"]	Yes	Message role determining allowed fields
content	list[ContentPart]	Yes (most roles)	Message text or multipart content array
name	str	No	Optional participant name for multi-agent scenarios
tool_calls	list[ToolCallParam]	No	Tool calls (assistant role only)
tool_call_id	str	Yes (tool role)	ID linking tool result to the originating tool call

Outputs

Name	Type	Description
message dict	ChatCompletionMessageParam	Typed dictionary ready for the messages parameter

Usage Examples

Basic Conversation

from openai import OpenAI

client = OpenAI()

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is the capital of France?"},
]

response = client.chat.completions.create(
    model="gpt-4o",
    messages=messages,
)

Multi-turn with Tool Results

messages = [
    {"role": "system", "content": "You can use tools to answer questions."},
    {"role": "user", "content": "What's the weather in Paris?"},
    {
        "role": "assistant",
        "content": None,
        "tool_calls": [
            {
                "id": "call_abc123",
                "type": "function",
                "function": {"name": "get_weather", "arguments": '{"city": "Paris"}'},
            }
        ],
    },
    {
        "role": "tool",
        "tool_call_id": "call_abc123",
        "content": '{"temperature": 18, "condition": "sunny"}',
    },
]

Related Pages

Implements Principle

• Principle:Openai_Openai_python_Chat_Message_Construction