Creating a Session

In BotDojo, sessions are the foundation of maintaining state and context throughout your chatbot interactions. By default, every flow request automatically creates and manages a session that stores:

• Chat history
• Uploaded files
• Canvas states
• User actions
• Flow variables

Session State

While sessions are created automatically, there are times when you'll want to pre-populate a session with specific information before starting a conversation. This is particularly useful when you want your chatbot to have context about the user it's interacting with.

For example, you might want to:

• Initialize a session with user profile information
• Pre-load user preferences
• Store custom metadata

The flow will then have immediate access to this information, allowing for personalized and context-aware interactions from the very first message.

Creating a Session

Endpoint

POST https://api.botdojo.com/api/v1/accounts/:account_id/projects/:project_id/flow_sessions/createSession

params (Array)

Index	Name	Description	Type
0	flow_id	The ID of the flow you want to start a session for	String
1	session_data	Session initialization data	Object

Session Data Structure

{
  "NameYouComeUpWith": {
    "variables": {
      "user_info": {
        "id": "user123",
        "name": "John Doe",
        "email": "john@example.com",
        "role": "admin"
      }
    }
  }
}

Get the session information from a code node.

// Retrieve form field later
const userName = await sessionState.get("NameYouComeUpWith").getVariable("user_info").name

Returns

• session state object

Example cURL Request

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY" \
  -d '{
    "params": [
      "YOUR_FLOW_ID",
      {
        "auth": {
          "variables": {
            "user_info": {
              "id": "user123",
              "name": "John Doe",
              "email": "john@example.com",
              "role": "admin"
            }
          }
        }
      }
    ]
  }' \
  https://api.botdojo.com/api/v1/accounts/YOUR_ACCOUNT_ID/projects/YOUR_PROJECT_ID/flow_sessions/createSession

Example Response

{
    "tags": [],
    "id": "0ca32840-2733-11f0-b7e1-0d3b837d1d83",
    "flow_id": "FLOW_ID",
    "sessionState": {
        "auth": {
            "variables": {
                "user_info": {
                    "id": "user123",
                    "name": "John Doe",
                    "email": "john@example.com",
                    "role": "admin"
                }
            }
        }
    },
    "created": "2025-05-02T08:54:25.732Z",
    "owner_uid": "XTKnBee4nqPk7K7sw6KGiFjOyOS2",
    "modified": "2025-05-02T08:54:25.732Z",
    "account_id": "ACCOUNT_ID",
    "modified_uid": "XTKnBee4nqPk7K7sw6KGiFjOyOS2",
    "project_id": "PROJECT_ID
}