messages

Creates, updates, deletes, gets or lists a messages resource.

Overview

Name	messages
Type	Resource
Id	openai.assistants.messages

Fields

The following fields are returned by SELECT queries:

get

Name	Datatype	Description
id	string	The identifier, which can be referenced in API endpoints.
assistant_id	string	If applicable, the ID of the assistant that authored this message.
run_id	string	The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.
thread_id	string	The thread ID that this message belongs to.
attachments	array	A list of files attached to the message, and the tools they were added to.
completed_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was completed.
content	array	The content of the message in array of text and/or images.
created_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was created.
incomplete_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was marked as incomplete.
incomplete_details	object	On an incomplete message, details about why the message is incomplete.
metadata	object	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. (x-oaiTypeLabel: map)
object	string	The object type, which is always thread.message. (thread.message)
role	string	The entity that produced the message. One of user or assistant. (user, assistant)
status	string	The status of the message, which can be either in_progress, incomplete, or completed. (in_progress, incomplete, completed)

list

Name	Datatype	Description
id	string	The identifier, which can be referenced in API endpoints.
assistant_id	string	If applicable, the ID of the assistant that authored this message.
run_id	string	The ID of the run associated with the creation of this message. Value is null when messages are created manually using the create message or create thread endpoints.
thread_id	string	The thread ID that this message belongs to.
attachments	array	A list of files attached to the message, and the tools they were added to.
completed_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was completed.
content	array	The content of the message in array of text and/or images.
created_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was created.
incomplete_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was marked as incomplete.
incomplete_details	object	On an incomplete message, details about why the message is incomplete.
metadata	object	Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. (x-oaiTypeLabel: map)
object	string	The object type, which is always thread.message. (thread.message)
role	string	The entity that produced the message. One of user or assistant. (user, assistant)
status	string	The status of the message, which can be either in_progress, incomplete, or completed. (in_progress, incomplete, completed)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	thread_id, message_id	openai-organization, openai-project
list	select	thread_id	limit, order, after, before, run_id, openai-organization, openai-project
create	insert	thread_id, role, content	openai-organization, openai-project
update	update	thread_id, message_id	openai-organization, openai-project
delete	delete	thread_id, message_id	openai-organization, openai-project

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
message_id	string	The ID of the message to delete.
thread_id	string	The ID of the thread to which this message belongs.
after	string	A cursor for use in pagination. after is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list.
before	string	A cursor for use in pagination. before is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list.
limit	integer	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. Automatically applied from a SQL LIMIT clause - SELECT ... LIMIT 10 sends limit=10 on the wire. Setting it explicitly in a WHERE clause is not required.
openai-organization	string	Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as openai_organization.
openai-project	string	Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as openai_project.
order	string	Sort order by the created_at timestamp of the objects. asc for ascending order and desc for descending order.
run_id	string	Filter messages by the run ID that generated them.

SELECT examples

get

OK

SELECT
id,
assistant_id,
run_id,
thread_id,
attachments,
completed_at,
content,
created_at,
incomplete_at,
incomplete_details,
metadata,
object,
role,
status
FROM openai.assistants.messages
WHERE thread_id = '{{ thread_id }}' -- required
AND message_id = '{{ message_id }}' -- required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

list

OK

SELECT
id,
assistant_id,
run_id,
thread_id,
attachments,
completed_at,
content,
created_at,
incomplete_at,
incomplete_details,
metadata,
object,
role,
status
FROM openai.assistants.messages
WHERE thread_id = '{{ thread_id }}' -- required
AND "order" = '{{ order }}'
AND after = '{{ after }}'
AND before = '{{ before }}'
AND run_id = '{{ run_id }}'
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;

INSERT examples

create

No description available.

INSERT INTO openai.assistants.messages (
role,
content,
attachments,
metadata,
thread_id,
"openai-organization",
"openai-project"
)
SELECT 
'{{ role }}' /* required */,
'{{ content }}' /* required */,
'{{ attachments }}',
'{{ metadata }}',
'{{ thread_id }}',
'{{ openai-organization }}',
'{{ openai-project }}'
RETURNING
id,
assistant_id,
run_id,
thread_id,
attachments,
completed_at,
content,
created_at,
incomplete_at,
incomplete_details,
metadata,
object,
role,
status
;

Manifest

# Description fields are for documentation purposes
- name: messages
props:
  - name: thread_id
    value: "{{ thread_id }}"
    description: Required parameter for the messages resource.
  - name: role
    value: "{{ role }}"
    description: |
      The role of the entity that is creating the message. Allowed values include:
      - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages.
      - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation.
    valid_values: ['user', 'assistant']
  - name: content
    value: "{{ content }}"
    description: |
      The text contents of the message.
  - name: attachments
    description: |
      A list of files attached to the message, and the tools they should be added to.
    value:
      - file_id: "{{ file_id }}"
        tools: "{{ tools }}"
  - name: metadata
    value: "{{ metadata }}"
    description: |
      Set of 16 key-value pairs that can be attached to an object. This can be
      useful for storing additional information about the object in a structured
      format, and querying for objects via API or the dashboard.
      Keys are strings with a maximum length of 64 characters. Values are strings
      with a maximum length of 512 characters.
  - name: openai-organization
    value: "{{ openai-organization }}"
    description: Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as `openai_organization`.
    description: Optionally scope the request to a specific organization (overrides the default associated with the API key). Addressable in SQL as `openai_organization`.
  - name: openai-project
    value: "{{ openai-project }}"
    description: Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as `openai_project`.
    description: Optionally scope the request to a specific project (overrides the default associated with the API key). Addressable in SQL as `openai_project`.

UPDATE examples

update

No description available.

UPDATE openai.assistants.messages
SET 
metadata = '{{ metadata }}'
WHERE 
thread_id = '{{ thread_id }}' --required
AND message_id = '{{ message_id }}' --required
AND "openai-organization" = '{{ openai-organization}}'
AND "openai-project" = '{{ openai-project}}'
RETURNING
id,
assistant_id,
run_id,
thread_id,
attachments,
completed_at,
content,
created_at,
incomplete_at,
incomplete_details,
metadata,
object,
role,
status;

DELETE examples

delete

No description available.

DELETE FROM openai.assistants.messages
WHERE thread_id = '{{ thread_id }}' --required
AND message_id = '{{ message_id }}' --required
AND "openai-organization" = '{{ openai-organization }}'
AND "openai-project" = '{{ openai-project }}'
;