setState

cURL

curl --request POST \
  --url https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name} \
  --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 '
{
  "payload": {},
  "expiry": 1296000000.5
}
'

import requests

url = "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}"

payload = {
    "payload": {},
    "expiry": 1296000000.5
}
headers = {
    "x-bp-authenticated-principal": "<x-bp-authenticated-principal>",
    "x-bot-id": "<x-bot-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-bp-authenticated-principal': '<x-bp-authenticated-principal>',
    'x-bot-id': '<x-bot-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({payload: {}, expiry: 1296000000.5})
};

fetch('https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payload' => [
        
    ],
    'expiry' => 1296000000.5
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-bot-id: <x-bot-id>",
    "x-bp-authenticated-principal: <x-bp-authenticated-principal>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}"

	payload := strings.NewReader("{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-bp-authenticated-principal", "<x-bp-authenticated-principal>")
	req.Header.Add("x-bot-id", "<x-bot-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}")
  .header("x-bp-authenticated-principal", "<x-bp-authenticated-principal>")
  .header("x-bot-id", "<x-bot-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-bp-authenticated-principal"] = '<x-bp-authenticated-principal>'
request["x-bot-id"] = '<x-bot-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}"

response = http.request(request)
puts response.read_body

{
  "state": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "botId": "<string>",
    "name": "<string>",
    "type": "conversation",
    "payload": {},
    "conversationId": "<string>",
    "userId": "<string>",
    "expiry": 2,
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "state": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "botId": "<string>",
    "name": "<string>",
    "type": "conversation",
    "payload": {},
    "conversationId": "<string>",
    "userId": "<string>",
    "expiry": 2,
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

POST

chat

states

{type}

{id}

{name}

cURL

curl --request POST \
  --url https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name} \
  --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 '
{
  "payload": {},
  "expiry": 1296000000.5
}
'

import requests

url = "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}"

payload = {
    "payload": {},
    "expiry": 1296000000.5
}
headers = {
    "x-bp-authenticated-principal": "<x-bp-authenticated-principal>",
    "x-bot-id": "<x-bot-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-bp-authenticated-principal': '<x-bp-authenticated-principal>',
    'x-bot-id': '<x-bot-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({payload: {}, expiry: 1296000000.5})
};

fetch('https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'payload' => [
        
    ],
    'expiry' => 1296000000.5
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-bot-id: <x-bot-id>",
    "x-bp-authenticated-principal: <x-bp-authenticated-principal>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}"

	payload := strings.NewReader("{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-bp-authenticated-principal", "<x-bp-authenticated-principal>")
	req.Header.Add("x-bot-id", "<x-bot-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}")
  .header("x-bp-authenticated-principal", "<x-bp-authenticated-principal>")
  .header("x-bot-id", "<x-bot-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.botpress.cloud/v1/chat/states/{type}/{id}/{name}")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-bp-authenticated-principal"] = '<x-bp-authenticated-principal>'
request["x-bot-id"] = '<x-bot-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payload\": {},\n  \"expiry\": 1296000000.5\n}"

response = http.request(request)
puts response.read_body

{
  "state": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "botId": "<string>",
    "name": "<string>",
    "type": "conversation",
    "payload": {},
    "conversationId": "<string>",
    "userId": "<string>",
    "expiry": 2,
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

{
  "state": {
    "id": "<string>",
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "botId": "<string>",
    "name": "<string>",
    "type": "conversation",
    "payload": {},
    "conversationId": "<string>",
    "userId": "<string>",
    "expiry": 2,
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

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.

Path Parameters

type

enum<string>

required

Represents the resource type that the state is related to

Available options:

conversation,

user,

bot,

integration,

workflow

string

required

Id of the State which will be either the botId, the userId or the conversationId

name

string

required

Name of the State which is declared inside the bot definition

Body

application/json

State content

payload

object | null

required

Payload is the content of the state defined by your bot.

expiry

number | null

Expiry of the State in milliseconds. The state will expire if it is idle for the configured value. By default, a state doesn't expire.

Required range: 1 <= x <= 2592000000

Response

Returns the updated State object if a valid identifier was provided. Returns an an error otherwise

state

object

required

The state object represents the current payload. A state is always linked to either a bot, a conversation or a user.

Show child attributes

Last modified on July 3, 2026

Get Started

Chat API

Admin API

Files API

Tables API

Runtime API

Authorizations

Headers

Path Parameters

Body

Response