Skip to main content

Botpress API

API ReferenceIndiaMART / Versalence Agent Builder

Agent Builder External API v2

Swagger style interactive documentation for listing bots, inspecting bot integrations, and retrieving conversation messages.

Servers

https://backend.versalence.online/api/v2/agent-builder/ext
Security: Never paste API keys or webhook secrets into a published Bookshelf page. Live testing is available in the standalone API reference, subject to CORS permissions.

Bot Operations

GET/workspaces/{workspaceId}/botsList Bots

List the bots registered in the selected workspace, including build type and timestamps.

Path parameters

Name Type Required Description
workspaceId string Yes Workspace identifier

Responses

200 Successful response · application/json

{
  "success": "boolean",
  "data": [
    {
      "id": "string (UUID)",
      "name": "string",
      "buildType": "string",
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)"
    }
  ],
  "partial": "boolean"
}

Example response

{
  "success": true,
  "data": [
    {
      "id": "29b31b9e-39a6-4bac-8a0c-ea5c1e9d3fc8",
      "name": "Desk",
      "buildType": "Workflow",
      "createdAt": "2026-10-14T17:01:54.818Z",
      "updatedAt": "2026-10-14T17:01:55.876Z"
    },
    {
      "id": "87884a25-71da-4c2d-ae95-5013bd4480ab",
      "name": "Empty Bot",
      "buildType": "Workflow",
      "createdAt": "2026-10-14T17:01:56.945Z",
      "updatedAt": "2026-10-14T17:01:57.722Z"
    },
    {
      "id": "4fad64bd-0254-46a5-afdf-cdcae98c85b5",
      "name": "National Industries",
      "buildType": "Workflow",
      "createdAt": "2026-10-15T17:47:13.259Z",
      "updatedAt": "2026-10-23T14:31:09.036Z"
    },
    {
      "id": "9e451f63-f9c2-4e46-9b92-005738f2ccb5",
      "name": "Sewa Enterprises",
      "buildType": "Workflow",
      "createdAt": "2026-10-16T07:58:01.480Z",
      "updatedAt": "2026-10-23T11:55:55.059Z"
    },
    {
      "id": "a2986485-befd-4a71-a05a-3942e58b57e8",
      "name": "Exotica Steel",
      "buildType": "Workflow",
      "createdAt": "2026-10-16T13:07:16.893Z",
      "updatedAt": "2026-10-23T11:48:36.887Z"
    },
    {
      "id": "e9debc74-5c1e-4204-b497-49bba1fc5e25",
      "name": "Herbaveda Overseas",
      "buildType": "Workflow",
      "createdAt": "2026-10-16T13:08:39.757Z",
      "updatedAt": "2026-10-23T11:52:34.675Z"
    },
    {
      "id": "cc4ec02f-54f9-4639-b7e9-e20ce6a7bfc9",
      "name": "Unicorn Equipment",
      "buildType": "Workflow",
      "createdAt": "2026-10-16T13:24:08.863Z",
      "updatedAt": "2026-10-23T11:57:31.259Z"
    },
    {
      "id": "314aa3eb-0136-4ebb-a709-b3d5d598375a",
      "name": "Jay Shree Machine Tools",
      "buildType": "Workflow",
      "createdAt": "2026-10-17T04:47:37.910Z",
      "updatedAt": "2026-10-19T15:37:44.557Z"
    }
  ],
  "partial": false
}
GET/workspaces/{workspaceId}/bots/{botId}/credentialsGet Bot Integrations

Fetch integration status and webhook configuration for the requested bot. Treat the response as sensitive because it can contain a webhook secret.

Path parameters

Name Type Required Description
workspaceId string Yes Workspace identifier
botId UUID Yes Bot identifier

Responses

200 Successful response · application/json

{
  "success": "boolean",
  "data": {
    "botId": "string (UUID)",
    "name": "string",
    "enabled": "boolean",
    "workspaceId": "string",
    "webhook": {
      "integrationId": "string",
      "enabled": "boolean",
      "webhookId": "string (UUID)",
      "secret": "string (sensitive)"
    }
  }
}

Example response

{
  "success": true,
  "data": {
    "botId": "4fad64bd-0254-46a5-afdf-cdcae98c85b5",
    "name": "National Industries",
    "enabled": true,
    "workspaceId": "wkspace_01M4XM03S725556S8YM712H1W0",
    "webhook": {
      "integrationId": "intver_01KVC0MXH1NRBX66RQ9CR7Z14E",
      "enabled": true,
      "webhookId": "a05ffe7b-4c0a-4b27-acc5-de6d209ff6f7",
      "secret": "REDACTED"
    }
  }
}
GET/workspaces/{workspaceId}/bots/{botId}/conversations/{conversationId}/messagesGet Chats by conversation_id

Return conversation messages, including text and choice payloads, direction, timestamps and optional pagination token. The illustrated response is ordered newest first; sort by createdAt to reconstruct the conversation chronologically.

Path parameters

Name Type Required Description
workspaceId string Yes Workspace identifier
botId UUID Yes Bot identifier
conversationId string Yes Conversation identifier

Responses

200 Successful response · application/json

{
  "success": "boolean",
  "data": [
    {
      "id": "string (UUID)",
      "createdAt": "string (date-time)",
      "updatedAt": "string (date-time)",
      "conversationId": "string",
      "payload": {
        "type": "text | choice",
        "text": "string",
        "options": "array<{label:string,value:string}> (optional)"
      },
      "tags": "object",
      "userId": "string",
      "type": "text | choice",
      "direction": "incoming | outgoing"
    }
  ],
  "nextToken": "string | null"
}

Example response

{
  "success": true,
  "data": [
    {
      "id": "c916f588-5fc3-4954-b32a-54ad215c60a9",
      "createdAt": "2026-10-22T11:03:22.793Z",
      "updatedAt": "2026-10-22T11:03:22.793Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "type": "text",
        "text": "This session has ended after 5 minutes of inactivity. You can message us again whenever you are ready."
      },
      "tags": {
        "iteration": "",
        "origin": "workflow://wf-timeout/node/nd-e6c012a652/card/ins-e1f8c437b3"
      },
      "userId": "user_01M50ATG6S5X341FZGP8B48FBV",
      "type": "text",
      "direction": "outgoing"
    },
    {
      "id": "67a86a7d-3b2a-4a69-b42d-170e5e5be750",
      "createdAt": "2026-10-22T10:58:18.453Z",
      "updatedAt": "2026-10-22T10:58:18.453Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "type": "choice",
        "text": "To help you further, could you tell me the shredding type you need? For example: cross cut, strip cut, or micro cut.",
        "options": [
          {
            "label": "Cross cut",
            "value": "Cross cut"
          },
          {
            "label": "Strip cut",
            "value": "Strip cut"
          },
          {
            "label": "Micro cut",
            "value": "Micro cut"
          },
          {
            "label": "Other (type below)",
            "value": "Other (type below)"
          }
        ]
      },
      "tags": {
        "iteration": "",
        "origin": "LLMZ"
      },
      "userId": "user_01M50ATG6S5X341FZGP8B48FBV",
      "type": "choice",
      "direction": "outgoing"
    },
    {
      "id": "89460308-2d7a-4efe-add6-a5f1ece48d5a",
      "createdAt": "2026-10-22T10:58:17.290Z",
      "updatedAt": "2026-10-22T10:58:17.290Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "type": "text",
        "text": "The starting price for office use paper shredders is **₹12,000 per unit**. Other models are available at ₹16,500, ₹18,000, ₹32,000, and up to ₹35,000 per piece for higher-capacity machines. These are indicative prices; the team will confirm the final price based on your exact requirement."
      },
      "tags": {
        "iteration": "",
        "origin": "LLMZ"
      },
      "userId": "user_01M50ATG6S5X341FZGP8B48FBV",
      "type": "text",
      "direction": "outgoing"
    },
    {
      "id": "547febde-e8a3-4c35-ae7e-83230a9a635b",
      "createdAt": "2026-10-22T10:58:10.189Z",
      "updatedAt": "2026-10-22T10:58:10.189Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "text": "prices kya hain inke?",
        "type": "text"
      },
      "tags": {},
      "userId": "user_01M5HM3QTXSXZ0SJXXBAQWQS00",
      "type": "text",
      "direction": "incoming"
    },
    {
      "id": "f92cf6b7-bb6b-4974-8ab4-c1a4d1acb32f",
      "createdAt": "2026-10-22T10:57:22.070Z",
      "updatedAt": "2026-10-22T10:57:22.070Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "type": "choice",
        "text": "To help you choose the right office shredder, could you tell me the shredding type you need?",
        "options": [
          {
            "label": "Cross Cut",
            "value": "Cross Cut"
          },
          {
            "label": "Micro Cut",
            "value": "Micro Cut"
          },
          {
            "label": "Other (type below)",
            "value": "Other"
          }
        ]
      },
      "tags": {
        "iteration": "",
        "origin": "LLMZ"
      },
      "userId": "user_01M50ATG6S5X341FZGP8B48FBV",
      "type": "choice",
      "direction": "outgoing"
    },
    {
      "id": "e4010052-2c2e-425e-9c26-7037ed914448",
      "createdAt": "2026-10-22T10:57:15.389Z",
      "updatedAt": "2026-10-22T10:57:15.389Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "type": "choice",
        "text": "Please select the category you are interested in:",
        "options": [
          {
            "label": "Glue Binding Machine",
            "value": "Glue Binding Machine"
          },
          {
            "label": "Comb Binding Machines",
            "value": "Comb Binding Machines"
          },
          {
            "label": "Spiral Binding Machines",
            "value": "Spiral Binding Machines"
          },
          {
            "label": "Corner Cutter Machine",
            "value": "Corner Cutter Machine"
          },
          {
            "label": "Currency Counting Machines",
            "value": "Currency Counting Machines"
          },
          {
            "label": "Safety Locker",
            "value": "Safety Locker"
          },
          {
            "label": "Notebook Making Machines",
            "value": "Notebook Making Machines"
          },
          {
            "label": "Plastic Spirals",
            "value": "Plastic Spirals"
          },
          {
            "label": "Wiro Ring Wire And Plastic Comb Spico",
            "value": "Wiro Ring Wire And Plastic Comb Spico"
          },
          {
            "label": "Creasing Machine",
            "value": "Creasing Machine"
          },
          {
            "label": "Pouch Laminator",
            "value": "Pouch Laminator"
          },
          {
            "label": "Corner Taping Machine",
            "value": "Corner Taping Machine"
          },
          {
            "label": "Plotter Paper Rolls",
            "value": "Plotter Paper Rolls"
          },
          {
            "label": "Other (type below)",
            "value": "Other (type below)"
          }
        ]
      },
      "tags": {
        "iteration": "",
        "origin": "LLMZ"
      },
      "userId": "user_01M50ATG6S5X341FZGP8B48FBV",
      "type": "choice",
      "direction": "outgoing"
    },
    {
      "id": "d3704492-5ba0-4d65-8bca-ff5798b4c035",
      "createdAt": "2026-10-22T10:57:11.853Z",
      "updatedAt": "2026-10-22T10:57:11.853Z",
      "conversationId": "conv_01M5HM3R4N9VTXTDSK55H7JRVG",
      "payload": {
        "text": "office shredder chahiye tha",
        "type": "text"
      },
      "tags": {},
      "userId": "user_01M5HM3QTXSXZ0SJXXBAQWQS00",
      "type": "text",
      "direction": "incoming"
    }
  ],
  "nextToken": null
}

Authentication & examples

All endpoints require x-api-key in the request header. The base URL and documented paths combine as follows:

curl --request GET \
  --url 'https://backend.versalence.online/api/v2/agent-builder/ext/workspaces/{workspaceId}/bots' \
  --header 'x-api-key: YOUR_API_KEY'

Data model notes

Field Meaning
success Boolean indicating application level success
data Endpoint result; array for bots and messages, object for integrations
partial List bots response field indicating partial result in the supplied example
nextToken Message pagination token; null in the supplied example. Its request parameter format is not documented in the supplied samples.
payload May be text or a choice object with labeled options
direction incoming or outgoing

Only HTTP 200 response bodies were provided. Error statuses, pagination request semantics, scopes, limits, and other integrations are not asserted here.

Based on supplied sample API responses · Documentation generated 26 October 2026 · Do not publish live credentials.
Back to top