# Bot APIs

# Botpress API

<main id="bkmrk-agent-builder-extern">## End Point

<p class="callout info">https://backend.versalence.online/api/v2/agent-builder/ext</p>

<p class="callout warning">**The x-api-key will be provided separtely**</p>

## Bot Operations

##### **<span class="descr">List Bots</span>**

<section class="endpoint open" id="bkmrk-get%2Fworkspaces%2F%7Bwork"><p class="callout info"><span class="method">GET </span><span class="path">/workspaces/{workspaceId}/bots</span></p>

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

##### Path parameters

<div class="body"><table class="tbl"><tbody><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr><tr><td>`workspaceId`</td><td>string</td><td>Yes</td><td>Workspace identifier</td></tr></tbody></table>

</div>Curl

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

<p class="callout success">**200** Successful response · `application/json`</p>

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

##### Example response

```json
{
  "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
}
```

</section>##### **<span class="descr">Get Bot Info</span>**

<section class="endpoint open" id="bkmrk-get%2Fworkspaces%2F%7Bwork-1"><p class="callout info"><span class="descr"><span class="method">GET </span><span class="path">/workspaces/{workspaceId}/bots/{botId}/credentials</span></span></p>

<span class="descr">Get Bot Integrations f</span>etch integration status and webhook configuration for the requested bot. Treat the response as sensitive because it can contain a webhook secret.

##### Path parameters

<div class="body"><table class="tbl"><tbody><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr><tr><td>`workspaceId`</td><td>string</td><td>Yes</td><td>Workspace identifier</td></tr><tr><td>`botId`</td><td>UUID</td><td>Yes</td><td>Bot identifier</td></tr></tbody></table>

</div>##### Curl

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

##### Responses

<p class="callout success">**200** Successful response · `application/json`</p>

```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

```json
{
  "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"
    }
  }
}
```

</section><section class="endpoint open" id="bkmrk-get%2Fworkspaces%2F%7Bwork-2"><div class="head">  
</div>##### **<span class="descr">Get Conversations by conversation\_id</span>**

<div class="head"><section class="endpoint open" id="bkmrk-get-%2Fworkspaces%2F%7Bwor"><p class="callout info">GET /workspaces/{workspaceId}/bots/{botId}/conversations/{conversationId}/messagesGet</p>

</section></div>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

<div class="body"><table class="tbl"><tbody><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr><tr><td>`workspaceId`</td><td>string</td><td>Yes</td><td>Workspace identifier</td></tr><tr><td>`botId`</td><td>UUID</td><td>Yes</td><td>Bot identifier</td></tr><tr><td>`conversationId`</td><td>string</td><td>Yes</td><td>Conversation identifier</td></tr></tbody></table>

</div>##### Curl

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

##### Responses

<p class="callout success">**200** Successful response · `application/json`</p>

```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

```json
{
  "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
}
```

</section>##### Data model notes

<table class="tbl" style="width:100%;"><tbody><tr><th style="width:16.9167%;">Field</th><th style="width:83.0833%;">Meaning</th></tr><tr><td style="width:16.9167%;">`success`</td><td style="width:83.0833%;">Boolean indicating application level success</td></tr><tr><td style="width:16.9167%;">`data`</td><td style="width:83.0833%;">Endpoint result; array for bots and messages, object for integrations</td></tr><tr><td style="width:16.9167%;">`partial`</td><td style="width:83.0833%;">List bots response field indicating partial result in the supplied example</td></tr><tr><td style="width:16.9167%;">`nextToken`</td><td style="width:83.0833%;">Message pagination token; null in the supplied example. Its request parameter format is not documented in the supplied samples.</td></tr><tr><td style="width:16.9167%;">`payload`</td><td style="width:83.0833%;">May be text or a choice object with labeled options</td></tr><tr><td style="width:16.9167%;">`direction`</td><td style="width:83.0833%;">`incoming` or `outgoing`</td></tr></tbody></table>

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

<div class="footer">  
</div></main>