> ## 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. # getOrCreateConversation > Retrieves the [Conversation](#schema_conversation) object containing given tags. If the conversation does not exist, it will be created. Tags will be updated if they are set in the request body. ## OpenAPI ````yaml /runtime-openapi.json post /v1/chat/conversations/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/conversations/get-or-create: post: tags: - Endpoints description: >- Retrieves the [Conversation](#schema_conversation) object containing given tags. If the conversation does not exist, it will be created. Tags will be updated if they are set in the request body. operationId: getOrCreateConversation 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/getOrCreateConversationBody' responses: '200': $ref: '#/components/responses/getOrCreateConversationResponse' default: $ref: '#/components/responses/getOrCreateConversationResponse' components: requestBodies: getOrCreateConversationBody: description: Conversation data content: application/json: schema: type: object properties: channel: type: string maxLength: 200 description: Channel name tags: type: object additionalProperties: type: string maxLength: 500 nullable: true description: >- Tags for the [Conversation](#schema_conversation). Set to null or empty string to remove. integrationName: type: string maxLength: 200 description: >- [DEPRECATED] To create a conversation from within a bot, call an action of the integration instead. deprecated: true properties: type: object additionalProperties: type: string maxLength: 200 nullable: true description: >- **EXPERIMENTAL** - Optional shared properties. Set individual properties to null or empty string to remove them. discriminateByTags: type: array items: type: string maxLength: 500 description: >- Optional list of tag names to use for strict matching when looking up existing conversations. If provided, all specified tags must match exactly for a conversation to be considered a match. For example, with an existing conversation 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: - channel - tags title: getOrCreateConversationBody additionalProperties: false responses: getOrCreateConversationResponse: description: >- Returns a [Conversation](#schema_conversation) object if a valid identifier was provided. Returns [an error](#errors) otherwise content: application/json: schema: type: object properties: conversation: $ref: '#/components/schemas/Conversation' meta: type: object properties: created: type: boolean required: - created additionalProperties: false required: - conversation - meta title: getOrCreateConversationResponse additionalProperties: false schemas: Conversation: type: object properties: id: type: string minLength: 28 maxLength: 36 description: Id of the [Conversation](#schema_conversation) currentTaskId: type: string minLength: 28 maxLength: 36 deprecated: true description: Unused. This field will be removed in the future. createdAt: type: string format: date-time description: >- Creation date of the [Conversation](#schema_conversation) in ISO 8601 format updatedAt: type: string format: date-time description: >- Updating date of the [Conversation](#schema_conversation) in ISO 8601 format channel: type: string description: >- Name of the channel where the [Conversation](#schema_conversation) is happening integration: type: string description: >- Name of the integration that created 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. messageCount: type: number description: Number of messages in the conversation properties: type: object additionalProperties: type: string maxLength: 200 description: >- **EXPERIMENTAL** - Optional shared properties that can be accessed and modified by both the bot and any of its integrations. required: - id - createdAt - updatedAt - channel - integration - tags - messageCount description: >- The [Conversation](#schema_conversation) object represents an exchange of messages between one or more users. A [Conversation](#schema_conversation) is always linked to an integration's channels. For example, a Slack channel represents a conversation. additionalProperties: false securitySchemes: BearerAuth: type: http scheme: bearer ````