# Stories

A story is a conversation scenario between customers and the bot. You can design the bot to do things like receiving pizza orders or scheduling doctor appointments or whatever you want.

## List all stories

Returns list of all stories.

GET https://api.chatbot.com/stories

#### Request URL
```bash
curl --request GET \
\t--url https://api.chatbot.com/stories \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
```

#### Response Example
```json
[\
    {\
        "id": "58ee11d75fb5580005cb8199",\
        "name": "Example name",\
        "description": "Example description",\
        "integrations": [],\
        "metrics": [\
            {\
                "date": "2018-01-16",\
                "conversations": 15\
            },\
            [...]\
        ]\
    }\
]
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `id` | String | Story id. |
| `name` | String | Story name. |
| `description` | String | Story description. |
| [`integrations`](https://www.chatbot.com/docsv1/stories/#integrations) | Array.< [String](https://www.chatbot.com/docsv1/stories/#integrations) > | An array of [element](https://www.chatbot.com/docsv1/stories/#integrations) strings that describes which integrations story is connected with. |
| [`metrics`](https://www.chatbot.com/docsv1/stories/#metrics) | Array.< [object](https://www.chatbot.com/docsv1/stories/#metrics) > | An array of [element](https://www.chatbot.com/docsv1/stories/#metrics) objects that includes weekly metrics for the story. |

#### `integrations`

A string array that describes which integrations story is connected with. Possible values: `livechat`, `messenger`, `slack`, `widget`.

#### `metrics`

| Property | Type | Description |
| --- | --- | --- |
| `date` | String | Day. |
| `conversations` | Number | The number of conversations. |

## Get a single story

Returns single story for the given id.

GET https://api.chatbot.com/stories/:ID

#### Request URL
```bash
curl --request GET \
\t--url https://api.chatbot.com/stories/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}'
```

#### Response Example
```json
{\
    "id": "58ee11d75fb5580005cb8199",\
    "name": "Example story name",\
    "description": "Example story description",\
    "order": [\
        "58ee2d045d033800059a3f7e"\
    ],\
    "interactions": {\
        "58ee2d045d033800059a3f7e": {\
            "name": "parent",\
            "root": true,\
            "references": [],\
            "contextOut": [\
                "58ee2d105fb5580005cb81aa"\
            ],\
            "webhook": "",\
            "id": "58ee2d045d033800059a3f7e"\
        },\
        "58ee2d105fb5580005cb81aa": {\
            "name": "child",\
            "root": false,\
            "references": [],\
            "contextOut": [],\
            "webhook": "",\
            "id": "58ee2d105fb5580005cb81aa"\
        }\
    }\
}
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `id` | String | Story id. |
| `name` | String | Story name. |
| `description` | String | Story description. |
| `order` | Array.<String> | A string array that states the interactions order at the first story tree level. This order is considered while searching and matching interactions. |
| `interactions` | Object | An object includes all interactions created in the story. |

## Add a new story

Create a new story:

POST https://api.chatbot.com/stories

#### Request URL
```bash
curl --request POST \
\t--url https://api.chatbot.com/stories \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json' \
\t--data '\n    {\n      "name": "Story name",\n      "description": "Story description"\n    }\n'
```

#### Response Example
```json
{\
    "id": "58ee2e085d033800059a3f7f",\
    "timestamp": "2017-04-12T13:39:20.721Z",\
    "status": {\
        "code": 200,\
        "type": "success"\
    }\
}
```

#### Properties

| Property | Type | Description |
| --- | --- | --- |
| `name` | String | Story name. <br>`String(1, 1024)` |
| `description` | String | **Optional.** Story description. <br>`String(0, 2048)` |

## Update a story

Update story with the given id.

PUT https://api.chatbot.com/stories/:ID

#### Request URL
```bash
curl --request PUT \
\t--url https://api.chatbot.com/stories/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json' \
\t--data '\n    {\n      "name": "Story name",\n      "description": "Story description"\n    }\n'
```

#### Response Example
```json
{\
    "timestamp": "2017-04-12T13:40:40.260Z",\
    "status": {\
        "code": 200,\
        "type": "success"\
    }\
}
```

#### Properties

## Delete a story

Removes a story with the given id.

DELETE https://api.chatbot.com/stories/:ID

#### Request URL
```bash
curl --request DELETE \
\t--url https://api.chatbot.com/stories/:ID \
\t--header 'authorization: Bearer ${DEVELOPER_ACCESS_TOKEN}' \
\t--header 'content-type: application/json'
```

#### Response Example
```json
{\
    "timestamp": "2017-04-12T13:41:47.020Z",\
    "status": {\
        "code": 200,\
        "type": "success"\
    }\
}
```

## Start a free ChatBot trial and build your first chatbot today!

Free 14-day trialNo credit card required