# Bot API

## Get bot

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot`

Retrieve the bot for this integration

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "env": {
    "MY_VAR": "somevalue"
  },
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}

## Update bot

<mark style="color:orange;">`PUT`</mark> `https://clients.csml.dev/v1/api/bot`

Update a bot's name, default\_flow and/or description. Parameters that are not set will not be changed.

#### Request Body

| Name          | Type   | Description                                 |
| ------------- | ------ | ------------------------------------------- |
| env           | object | key/value hash of bot environment variables |
| default\_flow | string | ID of default flow to set (flow must exist) |
| description   | string |                                             |
| name          | string |                                             |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "MyBot",
  "description": "This is my bot",
  "default_flow": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "created_at": "2019-12-11T18:59:39.391Z",
  "updated_at": "2019-12-13T01:27:38.653Z",
  "flows": [
      {
      "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
      "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
      "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
      "name": "Default",
      "description": "Default custom flow",
      "commands": [
        "/default"
      ],
      "content": "start:\n\tsay \"hello!\"\n\tgoto end",
      "created_at": "2019-12-11T18:59:39.610Z",
      "updated_at": "2019-12-13T01:31:51.507Z",
    },
    ...
  ]
}
```

{% endtab %}
{% endtabs %}

## Get bot flows

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/flows`

Retrieve all the flows in the current bot

{% tabs %}
{% tab title="200 " %}

```javascript
[
  {
    "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
    "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
    "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
    "name": "Default",
    "description": "Default custom flow",
    "commands": [
      "/default"
    ],
    "content": "start:\n\tsay \"hello!\"\n\tgoto end",
    "created_at": "2019-12-11T18:59:39.610Z",
    "updated_at": "2019-12-13T01:31:51.507Z",
  },
  ...
]
```

{% endtab %}
{% endtabs %}

## Create Flow

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/flows`

Add a new flow to the current bot

#### Request Body

| Name        | Type   | Description                                                                  |
| ----------- | ------ | ---------------------------------------------------------------------------- |
| description | string | Description of the flow to create                                            |
| commands    | array  | <p>Commands that will trigger the flow.<br>Example: \["some", "command"]</p> |
| content     | string | CSML Flow                                                                    |
| name        | string | Name of the flow                                                             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 
```

{% endtab %}
{% endtabs %}

## Get flow

<mark style="color:blue;">`GET`</mark> `https://clients/csml.dev/v1/api/bot/flows/:flow_id`

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| flow\_id | string |             |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "fd2e74e5-1305-4650-a300-8097d71df01f",
  "bot_id": "06e63f93-2e1a-4f76-b174-9c4aa6e31401",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "Default",
  "description": "Default custom flow",
  "commands": [
    "/default"
  ],
  "content": "start:\n\tsay \"hello!\"\n\tgoto end",
  "created_at": "2019-12-11T18:59:39.610Z",
  "updated_at": "2019-12-13T01:31:51.507Z",
}



```

{% endtab %}
{% endtabs %}

## Update flow

<mark style="color:orange;">`PUT`</mark> `https://clients/csml.dev/v1/api/bot/flows/:flow_id`

#### Path Parameters

| Name     | Type   | Description |
| -------- | ------ | ----------- |
| flow\_id | string |             |

#### Request Body

| Name        | Type   | Description |
| ----------- | ------ | ----------- |
| commands    | array  |             |
| content     | string |             |
| description | string |             |

{% tabs %}
{% tab title="204 " %}

```javascript
{
  "id": "c3187b49-5833-4572-960f-a6eedd59d9cd",
  "organization_id": "0b50ddf9-052b-4dd6-9901-459caa15ed33",
  "name": "SomeFlow",
  "bot_id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "commands": [
    "/someflow",
    "some command"
  ],
  "content": "start:\n  say \"Hi!\"\n  goto end",
  "created_at": "2020-08-23T17:54:39.461Z",
  "updated_at": "2020-08-23T17:54:39.461Z"
} 
```

{% endtab %}
{% endtabs %}

## Bot usage

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/usage`

Get usage information about a bot

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "currentmonth": {
    "messages": 0,
    "clients": 0
  },
  "last30d": {
    "messages": 0,
    "clients": 0
  },
  "lastmonth": {
    "messages": 0,
    "clients": 0
  }
}
```

{% endtab %}
{% endtabs %}

## Validate bot

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/validate`

Validate bot data against the CSML interpreter

#### Request Body

| Name | Type   | Description                                             |
| ---- | ------ | ------------------------------------------------------- |
|      | object | The bot object as retrieved from the GET /bot operation |

{% tabs %}
{% tab title="200 " %}

```javascript
// bot is valid
{
  "valid": true
}

// bot is invalid
{
  "valid": false,
  "errors": [
    {
      "flow": "someFlow",
      "step": "someStep",
      "line": 0,
      "column": 0,
      "message": "error message"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Build bot

<mark style="color:green;">`POST`</mark> `https://clients.csml.dev/v1/api/bot/build`

Build a new version of the bot

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get bot build version

<mark style="color:blue;">`GET`</mark> `https://clients.csml.dev/v1/api/bot/build`

#### Query Parameters

| Name        | Type   | Description                                                           |
| ----------- | ------ | --------------------------------------------------------------------- |
| version\_id | string | <p>ID of version to retrieve.<br>Defaults to `latest` if not set.</p> |

{% tabs %}
{% tab title="200 " %}

```javascript
{
  "id": "3944ec9b-81c8-4b58-854d-b412c89b8e42",
  "name": "test",
  "default_flow": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
  "created_at": "2020-08-23T17:47:21.229Z",
  "version_id": "40e19091-9f5b-4f38-9494-9a97a1072640",
  "engine_version": "1.4.0",
  "flows": [
    {
      "id": "4c9d5234-cad2-4c97-be47-a82f31ec26a3",
      "name": "Default",
      "commands": [
        "/default"
      ],
      "content": "start:\n  say \"Hello\"\n  goto end",
    }
  ]
}
```

{% endtab %}
{% endtabs %}