> ## Documentation Index > Fetch the complete documentation index at: https://botpress-pb-update-api.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # getOrCreateMessage > Retrieves the [Message](#schema_message) object for given discriminating tags. If the message does not exist, it will be created. If the message already exists, its tags and payload will be updated with the provided values if they are defined. ## OpenAPI ````yaml /runtime-openapi.json post /v1/chat/messages/get-or-create openapi: 3.0.0 info: title: Botpress Runtime API description: API for Botpress Runtime version: 1.112.0 servers: - url: https://api.botpress.cloud security: - BearerAuth: [] tags: - name: documented - name: experimental paths: /v1/chat/messages/get-or-create: post: tags: - Endpoints description: >- Retrieves the [Message](#schema_message) object for given discriminating tags. If the message does not exist, it will be created. If the message already exists, its tags and payload will be updated with the provided values if they are defined. operationId: getOrCreateMessage parameters: - name: x-bp-authenticated-principal in: header description: Authenticated principal. Injected by the authentication middleware. required: true schema: type: string - name: x-bot-id in: header description: Bot id required: true schema: type: string - name: x-integration-id in: header description: Integration id required: false schema: type: string - name: x-integration-alias in: header description: Integration alias required: false schema: type: string - name: x-real-ip in: header description: Caller's IP address. Injected by the edge proxy. required: false schema: type: string requestBody: $ref: '#/components/requestBodies/getOrCreateMessageBody' responses: '200': $ref: '#/components/responses/getOrCreateMessageResponse' default: $ref: '#/components/responses/getOrCreateMessageResponse' components: requestBodies: getOrCreateMessageBody: description: Message data content: application/json: schema: type: object properties: payload: type: object additionalProperties: true description: >- Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location userId: type: string minLength: 28 maxLength: 36 description: ID of the [User](#schema_user) conversationId: type: string minLength: 28 maxLength: 36 description: ID of the [Conversation](#schema_conversation) type: type: string maxLength: 200 description: >- Type of the [Message](#schema_message) represents the resource type that the message is related to tags: type: object additionalProperties: type: string maxLength: 500 nullable: true description: Tags for the message. Set to null or empty string to remove. schedule: type: object properties: dateTime: type: string maxLength: 28 minLength: 24 description: >- When the [Message](#schema_message) will be sent, in the ISO 8601 format delay: type: number description: >- Delay in milliseconds before sending the [Message](#schema_message) description: >- Schedule the Message to be sent at a specific time. Either dateTime or delay must be provided. additionalProperties: false origin: type: string enum: - synthetic discriminateByTags: type: array items: type: string maxLength: 500 description: >- Optional list of tag names to use for strict matching when looking up existing messages. If provided, all specified tags must match exactly for a message to be considered a match. For example, with an existing message whose tags are {"foo": "a", "bar": "b", baz: "c"}: Without this parameter, ALL tags must match exactly. With ["bar","baz"], all listed tags must match their values, and other tags are not considered. required: - userId - conversationId - type - tags title: getOrCreateMessageBody additionalProperties: false responses: getOrCreateMessageResponse: description: >- Returns a [Message](#schema_message) object if a valid identifier was provided. Returns an [Error](#errors) otherwise content: application/json: schema: type: object properties: message: $ref: '#/components/schemas/Message' meta: type: object properties: created: type: boolean required: - created additionalProperties: false required: - message - meta title: getOrCreateMessageResponse additionalProperties: false schemas: Message: type: object properties: id: type: string minLength: 28 maxLength: 36 description: Id of the [Message](#schema_message) createdAt: type: string format: date-time description: Creation date of the [Message](#schema_message) in ISO 8601 format updatedAt: type: string format: date-time description: Update date of the [Message](#schema_message) in ISO 8601 format type: type: string maxLength: 200 description: >- Type of the [Message](#schema_message) represents the resource type that the message is related to payload: type: object additionalProperties: true description: >- Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location direction: type: string enum: - incoming - outgoing description: Direction of the message (`incoming` or `outgoing`). userId: type: string minLength: 28 maxLength: 36 description: ID of the [User](#schema_user) conversationId: type: string minLength: 28 maxLength: 36 description: ID of the [Conversation](#schema_conversation) tags: type: object additionalProperties: type: string description: >- Set of [Tags](/docs/developers/concepts/tags) that you can attach to a [Conversation](#schema_conversation). The set of [Tags](/docs/developers/concepts/tags) available on a [Conversation](#schema_conversation) is restricted by the list of [Tags](/docs/developers/concepts/tags) defined previously by the [Bot](#schema_bot). Individual keys can be unset by posting an empty value to them. origin: type: string enum: - synthetic description: Origin of the message (`synthetic`). required: - id - createdAt - updatedAt - type - payload - direction - userId - conversationId - tags description: >- The Message object represents a message in a [Conversation](#schema_conversation) for a specific [User](#schema_user). additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer ````