Messages - Update Message

Service:: AI Foundry

API Version:: v1

Modifies an existing message on an existing thread.

POST {endpoint}/threads/{threadId}/messages/{messageId}?api-version=v1

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	Project endpoint in the form of: https://<aiservices-id>.services.ai.azure.com/api/projects/<project-name>
messageId	path	True	string	Identifier of the message.
threadId	path	True	string	Identifier of the thread.
api-version	query	True	string minLength: 1	The API version to use for this operation.

Request Body

Name	Type	Description
metadata		A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length.

Responses

Name	Type	Description
200 OK	ThreadMessage	A representation of the modified message.
Other Status Codes	AgentV1Error	An unexpected error response.

Security

OAuth2Auth

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Scopes

Name	Description
https://ai.azure.com/.default

Examples

Messages_UpdateMessage_MaximumSet

Messages_UpdateMessage_MinimumSet

Messages_UpdateMessage_MaximumSet

Sample request

HTTP

POST {endpoint}/threads/dzuaiknevqgujlszsrlahnkey/messages/pdrblplrpbbqlfdzqkzetimdnp?api-version=v1

{
  "metadata": {
    "key5562": "scicrngscqkj"
  }
}

Sample response

Status code:: 200

{
  "id": "ohzuqfhaw",
  "object": "thread.message",
  "created_at": 11,
  "thread_id": "hcxrpklwbljjfhkywtctg",
  "status": "in_progress",
  "incomplete_details": {
    "reason": "content_filter"
  },
  "completed_at": 8,
  "incomplete_at": 18,
  "role": "user",
  "content": [
    {
      "type": "MessageContent"
    }
  ],
  "assistant_id": "zpujvcgjicl",
  "run_id": "uwsiihbsvcwwncfprmwjzzixsd",
  "attachments": [
    {
      "file_id": "xidx",
      "data_source": {
        "uri": "jtookuzhwojyylbips",
        "type": "uri_asset"
      },
      "tools": [
        null
      ]
    }
  ],
  "metadata": {
    "key9075": "lsmd"
  }
}

Messages_UpdateMessage_MinimumSet

Sample request

HTTP

POST {endpoint}/threads/pzscwqvceoci/messages/esgniifhilkuohasxszxrusn?api-version=v1

{}

Sample response

Status code:: 200

{
  "id": "ohzuqfhaw",
  "object": "thread.message",
  "created_at": 11,
  "thread_id": "hcxrpklwbljjfhkywtctg",
  "status": "in_progress",
  "incomplete_details": {
    "reason": "content_filter"
  },
  "completed_at": 8,
  "incomplete_at": 18,
  "role": "user",
  "content": [
    {
      "type": "MessageContent"
    }
  ],
  "assistant_id": "zpujvcgjicl",
  "run_id": "uwsiihbsvcwwncfprmwjzzixsd",
  "attachments": [
    {
      "tools": [
        null
      ]
    }
  ],
  "metadata": {}
}

Definitions

Name	Description
AgentErrorDetail	Describes the error information returned by the agents API.
AgentV1Error	Error payload returned by the agents API.
MessageAttachment	This describes to which tools a file has been attached.
MessageImageFileContent	A representation of image file content in a thread message.
MessageImageFileDetails	An image reference, as represented in thread message content.
MessageIncompleteDetails	Information providing additional detail about a message entering an incomplete status.
MessageIncompleteDetailsReason	A set of reasons describing why a message is marked as incomplete.
MessageRole	The possible values for roles attributed to messages in a thread.
MessageStatus	The possible execution status values for a thread message.
MessageTextContent	A representation of a textual item of thread message content.
MessageTextDetails	The text and associated annotations for a single item of agent thread message content.
MessageTextFileCitationAnnotation	A citation within the message that points to a specific quote from a specific File associated with the agent or the message. Generated when the agent uses the 'file_search' tool to search files.
MessageTextFileCitationDetails	A representation of a file-based text citation, as used in a file-based annotation of text thread message content.
MessageTextFilePathAnnotation	A citation within the message that points to a file located at a specific path.
MessageTextFilePathDetails	An encapsulation of an image file ID, as used by message image content.
MessageTextUrlCitationAnnotation	A citation within the message that points to a specific URL associated with the message. Generated when the agent uses tools such as 'bing_grounding' to search the Internet.
MessageTextUrlCitationDetails	A representation of a URL citation, as used in text thread message content.
ThreadMessage	A single, existing message within an agent thread.
VectorStoreDataSource	The structure, containing Azure asset URI path and the asset type of the file used as a data source for the enterprise file search.
VectorStoreDataSourceAssetType	Type of vector storage asset. Asset type may be a uri_asset, in this case it should contain asset URI ID, in the case of id_asset it should contain the data ID.

AgentErrorDetail

Object

Describes the error information returned by the agents API.

Name	Type	Description
code	string	Machine-readable error code.
message	string	Human-readable description of the error.
param	string	Name of the parameter that caused the error, if applicable.
type	string	Error type identifier (e.g. `invalid_request_error`).

AgentV1Error

Object

Error payload returned by the agents API.

Name	Type	Description
error	AgentErrorDetail	Represents the error.

MessageAttachment

Object

This describes to which tools a file has been attached.

Name	Type	Description
data_source	VectorStoreDataSource	Azure asset ID.
file_id	string	The ID of the file to attach to the message.
tools	MessageAttachmentToolDefinition[]	The tools to add to this file.

MessageImageFileContent

Object

A representation of image file content in a thread message.

Name	Type	Description
image_file	MessageImageFileDetails	The image file for this thread message content item.
type	string: image_file	The object type.

MessageImageFileDetails

Object

An image reference, as represented in thread message content.

Name	Type	Description
file_id	string	The ID for the file associated with this image.

MessageIncompleteDetails

Object

Information providing additional detail about a message entering an incomplete status.

Name	Type	Description
reason	MessageIncompleteDetailsReason	The provided reason describing why the message was marked as incomplete.

MessageIncompleteDetailsReason

Enumeration

A set of reasons describing why a message is marked as incomplete.

Value	Description
content_filter	The run generating the message was terminated due to content filter flagging.
max_tokens	The run generating the message exhausted available tokens before completion.
run_cancelled	The run generating the message was cancelled before completion.
run_failed	The run generating the message failed.
run_expired	The run generating the message expired.

MessageRole

Enumeration

The possible values for roles attributed to messages in a thread.

Value	Description
user	The role representing the end-user.
assistant	The role representing the agent.

MessageStatus

Enumeration

The possible execution status values for a thread message.

Value	Description
in_progress	A run is currently creating this message.
incomplete	This message is incomplete. See incomplete_details for more information.
completed	This message was successfully completed by a run.

MessageTextContent

Object

A representation of a textual item of thread message content.

Name	Type	Description
text	MessageTextDetails	The text and associated annotations for this thread message content item.
type	string: text	The object type.

MessageTextDetails

Object

The text and associated annotations for a single item of agent thread message content.

Name	Type	Description
annotations	MessageTextAnnotation[]: MessageTextFileCitationAnnotation[] MessageTextFilePathAnnotation[] MessageTextUrlCitationAnnotation[]	A list of annotations associated with this text.
value	string	The text data.

MessageTextFileCitationAnnotation

Object

A citation within the message that points to a specific quote from a specific File associated with the agent or the message. Generated when the agent uses the 'file_search' tool to search files.

Name	Type	Description
end_index	integer (int32)	The last text index associated with this text annotation.
file_citation	MessageTextFileCitationDetails	A citation within the message that points to a specific quote from a specific file. Generated when the agent uses the "file_search" tool to search files.
start_index	integer (int32)	The first text index associated with this text annotation.
text	string	The textual content associated with this text annotation item.
type	string: file_citation	The object type.

MessageTextFileCitationDetails

Object

A representation of a file-based text citation, as used in a file-based annotation of text thread message content.

Name	Type	Description
file_id	string	The ID of the file associated with this citation.
quote	string	The specific quote cited in the associated file.

MessageTextFilePathAnnotation

Object

A citation within the message that points to a file located at a specific path.

Name	Type	Description
end_index	integer (int32)	The last text index associated with this text annotation.
file_path	MessageTextFilePathDetails	A URL for the file that's generated when the agent used the code_interpreter tool to generate a file.
start_index	integer (int32)	The first text index associated with this text annotation.
text	string	The textual content associated with this text annotation item.
type	string: file_path	The object type.

MessageTextFilePathDetails

Object

An encapsulation of an image file ID, as used by message image content.

Name	Type	Description
file_id	string	The ID of the specific file that the citation is from.

MessageTextUrlCitationAnnotation

Object

A citation within the message that points to a specific URL associated with the message. Generated when the agent uses tools such as 'bing_grounding' to search the Internet.

Name	Type	Description
end_index	integer (int32)	The last text index associated with this text annotation.
start_index	integer (int32)	The first text index associated with this text annotation.
text	string	The textual content associated with this text annotation item.
type	string: url_citation	The object type.
url_citation	MessageTextUrlCitationDetails	The details of the URL citation.

MessageTextUrlCitationDetails

Object

A representation of a URL citation, as used in text thread message content.

Name	Type	Description
title	string	The title of the URL.
url	string	The URL associated with this citation.

ThreadMessage

Object

A single, existing message within an agent thread.

Name	Type	Description
assistant_id	string	If applicable, the ID of the agent that authored this message.
attachments	MessageAttachment[]	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	MessageContent[]: MessageImageFileContent[] MessageTextContent[]	The list of content items associated with the agent thread message.
created_at	integer (unixtime)	The Unix timestamp, in seconds, representing when this object was created.
id	string	The identifier, which can be referenced in API endpoints.
incomplete_at	integer (unixtime)	The Unix timestamp (in seconds) for when the message was marked as incomplete.
incomplete_details	MessageIncompleteDetails	On an incomplete message, details about why the message is incomplete.
metadata	object	A set of up to 16 key/value pairs that can be attached to an object, used for storing additional information about that object in a structured format. Keys may be up to 64 characters in length and values may be up to 512 characters in length.
object	enum: thread.message	The object type, which is always 'thread.message'.
role	MessageRole	The role associated with the agent thread message.
run_id	string	If applicable, the ID of the run associated with the authoring of this message.
status	MessageStatus	The status of the message.
thread_id	string	The ID of the thread that this message belongs to.

VectorStoreDataSource

Object

The structure, containing Azure asset URI path and the asset type of the file used as a data source for the enterprise file search.

Name	Type	Description
type	VectorStoreDataSourceAssetType	The asset type
uri	string	Asset URI.

VectorStoreDataSourceAssetType

Enumeration

Type of vector storage asset. Asset type may be a uri_asset, in this case it should contain asset URI ID, in the case of id_asset it should contain the data ID.

Value	Description
uri_asset	Azure URI
id_asset	The data ID

Share via

Messages - Update Message

URI Parameters

Request Body

Responses

Security

OAuth2Auth

Scopes

Examples

Messages_UpdateMessage_MaximumSet

Sample request

Sample response

Messages_UpdateMessage_MinimumSet

Sample request

Sample response

Definitions

AgentErrorDetail

AgentV1Error

MessageAttachment

MessageImageFileContent

MessageImageFileDetails

MessageIncompleteDetails

MessageIncompleteDetailsReason

MessageRole

MessageStatus

MessageTextContent

MessageTextDetails

MessageTextFileCitationAnnotation

MessageTextFileCitationDetails

MessageTextFilePathAnnotation

MessageTextFilePathDetails

MessageTextUrlCitationAnnotation

MessageTextUrlCitationDetails

ThreadMessage

VectorStoreDataSource

VectorStoreDataSourceAssetType