Skip to main content
POST
/
v1
/
chat
/
messages
/
get-or-create
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>' \
  --data '
{
  "payload": {},
  "userId": "<string>",
  "conversationId": "<string>",
  "type": "<string>",
  "tags": {},
  "schedule": {
    "dateTime": "<string>",
    "delay": 123
  },
  "origin": "synthetic",
  "discriminateByTags": [
    "<string>"
  ]
}
'
{
  "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"
  }
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
x-bot-id
string
required

Bot id

​
x-integration-id
string

Integration id

​
x-integration-alias
string

Integration alias

Body

application/json

Message data

​
payload
object
required

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

​
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

Set of Tags that you can attach to a Message. The set of Tags available on a Message is restricted by the list of Tags defined previously by the Bot. Individual keys can be unset by posting an empty value to them.

​
schedule
object

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

​
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

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.

Last modified on November 13, 2025