getOrCreateUser

Retrieves the 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.

POST /v1/chat/users/get-or-create

cURL

cURL

curl --request POST \
  --url https://api.botpress.cloud/v1/chat/users/get-or-create \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-bot-id: <x-bot-id>' \
  --header 'x-bp-authenticated-principal: <x-bp-authenticated-principal>' \
  --data '
{
  "tags": {},
  "integrationName": "<string>",
  "name": "<string>",
  "pictureUrl": "<string>",
  "properties": {},
  "attributes": {},
  "discriminateByTags": [
    "<string>"
  ]
}
'

200

{
  "user": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "tags": {},
    "name": "<string>",
    "pictureUrl": "<string>",
    "properties": {},
    "attributes": {}
  },
  "meta": {
    "created": true
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-bp-authenticated-principal · string · required

Authenticated principal. Injected by the authentication middleware.

x-bot-id · string · required

Bot id

x-integration-id · string

Integration id

x-integration-alias · string

Integration alias

x-real-ip · string

Caller's IP address. Injected by the edge proxy.

Body

application/json

User data

tags · object · required

Tags for the user. Set to null or empty string to remove.

Show child attributes

integrationName · string · deprecated

[DEPRECATED] To create a User from within a bot, call an action of the integration instead.

Maximum string length: 200

name · string

Name of the user

Maximum string length: 200

pictureUrl · string

URI of the user picture

Maximum string length: 40000

properties · object

EXPERIMENTAL - Optional shared properties. Set individual properties to null or empty string to remove them.

Show child attributes

attributes · object · deprecated

DEPRECATED - Use properties instead.

Show child attributes

discriminateByTags · string[]

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.

Maximum string length: 500

Response

200

application/json

Returns a User object if a valid identifier was provided. Returns an Error otherwise

user · object · required

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.

Show child attributes

meta · object · required

Show child attributes