getOrCreateMessage

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

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

cURL

cURL

curl --request POST \
  --url https://api.botpress.cloud/v1/chat/messages/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 '
{
  "userId": "<string>",
  "conversationId": "<string>",
  "type": "<string>",
  "tags": {},
  "payload": {},
  "schedule": {
    "dateTime": "<string>",
    "delay": 123
  },
  "origin": "synthetic",
  "discriminateByTags": [
    "<string>"
  ]
}
'

200

{
  "message": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "type": "<string>",
    "payload": {},
    "direction": "incoming",
    "userId": "<string>",
    "conversationId": "<string>",
    "tags": {},
    "origin": "synthetic"
  },
  "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

Message data

userId · string · required

ID of the User

Required string length: 28 - 36

conversationId · string · required

ID of the Conversation

Required string length: 28 - 36

type · string · required

Type of the Message represents the resource type that the message is related to

Maximum string length: 200

tags · object · required

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

Show child attributes

payload · object

Payload is the content type of the message. Accepted payload options: Text, Image, Choice, Dropdown, Card, Carousel, File, Audio, Video, Location

schedule · object

Schedule the Message to be sent at a specific time. Either dateTime or delay must be provided.

Show child attributes

origin · enum<string>

Available options: synthetic

discriminateByTags · string[]

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.

Maximum string length: 500

Response

200

application/json

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

message · object · required

The Message object represents a message in a Conversation for a specific User.

Show child attributes

meta · object · required

Show child attributes