> ## Documentation Index
> Fetch the complete documentation index at: https://botpress.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# getOrCreateUser

> Retrieves the [User](#schema_user) object for given discriminating tags. If the user does not exist, it will be created. If the user already exists, its name, pictureUrl, attributes, and tags will be updated with the provided values.



## OpenAPI

````yaml /runtime-openapi.json post /v1/chat/users/get-or-create
openapi: 3.0.0
info:
  title: Botpress Runtime API
  description: API for Botpress Runtime
  version: 1.82.0
servers:
  - url: https://api.botpress.cloud
security:
  - BearerAuth: []
tags:
  - name: documented
  - name: experimental
paths:
  /v1/chat/users/get-or-create:
    post:
      tags:
        - Endpoints
      description: >-
        Retrieves the [User](#schema_user) object for given discriminating tags.
        If the user does not exist, it will be created. If the user already
        exists, its name, pictureUrl, attributes, and tags will be updated with
        the provided values.
      operationId: getOrCreateUser
      parameters:
        - 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
      requestBody:
        $ref: '#/components/requestBodies/getOrCreateUserBody'
      responses:
        '200':
          $ref: '#/components/responses/getOrCreateUserResponse'
        default:
          $ref: '#/components/responses/getOrCreateUserResponse'
components:
  requestBodies:
    getOrCreateUserBody:
      description: User data
      content:
        application/json:
          schema:
            type: object
            properties:
              tags:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 500
                description: Tags for the [User](#schema_user)
              integrationName:
                type: string
                maxLength: 200
                description: >-
                  [DEPRECATED] To create a [User](#schema_user) from within a
                  bot, call an action of the integration instead.
                deprecated: true
              name:
                type: string
                maxLength: 200
                description: Name of the user
              pictureUrl:
                type: string
                maxLength: 40000
                description: URI of the user picture
              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.
              attributes:
                type: object
                additionalProperties:
                  type: string
                  maxLength: 200
                description: DEPRECATED - Use properties instead.
                deprecated: true
              discriminateByTags:
                type: array
                items:
                  type: string
                  maxLength: 500
                description: >-
                  Optional list of tag names to use for strict matching when
                  looking up existing users. If provided, all specified tags
                  must match exactly for a user to be considered a match. For
                  example, with an existing user 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:
              - tags
            title: getOrCreateUserBody
            additionalProperties: false
  responses:
    getOrCreateUserResponse:
      description: >-
        Returns a [User](#schema_user) object if a valid identifier was
        provided. Returns an [Error](#errors) otherwise
      content:
        application/json:
          schema:
            type: object
            properties:
              user:
                $ref: '#/components/schemas/User'
              meta:
                type: object
                properties:
                  created:
                    type: boolean
                required:
                  - created
                additionalProperties: false
            required:
              - user
              - meta
            title: getOrCreateUserResponse
            additionalProperties: false
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          minLength: 28
          maxLength: 36
          description: Id of the [User](#schema_user)
        createdAt:
          type: string
          format: date-time
          description: Creation date of the [User](#schema_user) in ISO 8601 format
        updatedAt:
          type: string
          format: date-time
          description: Updating date of the [User](#schema_user) in ISO 8601 format
        tags:
          type: object
          additionalProperties:
            type: string
          description: >-
            Set of [Tags](/docs/developers/concepts/tags) that you can attach to
            a [User](#schema_user). The set of
            [Tags](/docs/developers/concepts/tags) available on a
            [User](#schema_user) 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.
        name:
          type: string
          maxLength: 200
          description: Name of the [User](#schema_user)
        pictureUrl:
          type: string
          maxLength: 40000
          description: Picture URL of the [User](#schema_user)
        properties:
          type: object
          additionalProperties:
            type: string
            maxLength: 200
          description: Optional properties
        attributes:
          type: object
          additionalProperties:
            type: string
            maxLength: 200
          description: Optional attributes
      required:
        - id
        - createdAt
        - updatedAt
        - tags
      description: >-
        The user object represents someone interacting with the bot within a
        specific integration. The same person interacting with a bot in slack
        and messenger will be represented with two different users.
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

````