Bots

Overview

A bot is an automation that can be triggered either through a survey or slash command in the channel workspace. Once triggered, a bot runs a routine based on the stages or steps that were programmed.

additional resources

These are just some of the most basic API requests. For a complete list of endpoints, consult our API documentation on Swagger.

Get All Bots

Returns all the bots that exist within the company.

GET /bots

Endpoint URL

https://www.cotalker.com/api/v1/bots

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v1/bots' \
--header 'Authorization: Bearer $ACCESS_TOKEN'

Response Sample

Responses follow the COTBots data model.

---

Get Bot by Id

Returns the bot indicated by its Id.

GET /bots/{id}

Endpoint URL

https://www.cotalker.com/api/v1/bots/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the bot that is to be returned.	ObjectId<COTBot>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN

Request Sample

curl --location --request GET 'https://www.cotalker.com/api/v1/bots/618a69512c7cae88b3aa2fe3' \
--header 'Authorization: Bearer ACCESS_TOKEN'

Response Sample

The response follows the COTBot data model.

---

Create a New Bot

Creates a new bot within the company.

POST /bots

Endpoint URL

https://www.cotalker.com/api/v1/bots

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Indicates the body's format.	Required	application/json

Request Body

Only required fields are listed below. For a complete schema description, please go to the COTBot data model. Unrequired fields that are not submitted are either filled in automatically or left blank.

Element	Description	Type	Required	Notes
name	The bot's name.	string	Required

Request Sample

Bot created with the minimum required fields.

curl --location --request POST 'https://www.cotalker.com/api/v1/bots' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
    "name": "test bot"
}'

Response Sample

Go to COTBot for a complete description of the response.

{
    "parametrizedBot": {
        "default": {
            "stages": []
        },
        "stages": []
    },
    "version": 0,
    "process": "none",
    "isActive": true,
    "global": false,
    "extraData": [],
    "_id": "61adff87cc298ff6f5050283",
    "name": "test bot",
    "company": "6136968b580aaf2b0e49d844",
    "createdAt": "2021-12-06T12:14:17.323Z",
    "commands": [],
    "__v": 0
}

---

Update State Machine

Updates or edits the indicated bot.

PATCH /bots/{id}

Endpoint URL

https://www.cotalker.com/api/v1/bots/{id}

Path Parameters

Parameter	Description	Type	Required	Notes
id	The ObjectId of the bot that is to be modified.	ObjectId<COTBot>	Required

Headers

Header	Description	Required	Values
Authorization	Sends your access token to make an API request. Click here to see how to obtain an access token.	Required	Bearer $ACCESS_TOKEN
Content-Type	Sets the body's format.	Required	application/json

Request Body

Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTBot data model.

Request Sample

This request adds the way the bot is summoned and the routine it follows.

curl --location --request PATCH 'https://www.cotalker.com/api/v1/bots/61adff87cc298ff6f5050283' \
--header 'Authorization: Bearer $ACCESS_BOT' \
--header 'Content-Type: application/json' \
--data-raw '{
    "commands": [
        {
            "surveyIds": [],
            "isActive": true,
            "showHelp": true,
            "_id": "61ae063c2a3aad0d189d5f27",
            "description": "",
            "slashCmd": "sendemail",
            "isSlash": true,
            "isSurvey": false,
            "arguments": []
        }
    ],
    "parametrizedBot": {
        "start": "email",
        "maxIterations": 2,
        "stages": [
            {
                "_id": "61ae064f3ed2961e152dcddc",
                "key": "email",
                "name": "PBEmail",
                "version": null,
                "data": {
                    "subject": "Hey! We need to talk to you",
                    "content": {
                        "recipientName": "",
                        "recipientEmail": "",
                        "companyName": "ACME",
                        "title": [
                            "Your team is looking for you."
                        ],
                        "action": "",
                        "code": "",
                        "messageA": "$JOIN# #Your presence is requested in the #($VALUE#channel|nameDisplay)# channel.",
                        "messageB": ""
                    },
                    "targets": [
                        "$VALUE#cmdArgs"
                    ],
                    "cc": []
                },
                "next": {
                    "DEFAULT": "message"
                },
                "customNetworkRequest": []
            },
            {
                "_id": "61ae067aa58401211950b7f3",
                "key": "message",
                "name": "PBMessage",
                "data": {
                    "content": "📩 Email sent ✅",
                    "contentType": "text/system",
                    "sentBy": "$VALUE#user|_id",
                    "channelIds": "$VALUE#channel|_id"
                },
                "next": {},
                "customNetworkRequest": []
            }
        ],
        "version": "v3"
    }
}'

Response Sample

Go to COTBot for a complete description of the response.

{
    "parametrizedBot": {
        "start": "email",
        "maxIterations": 2,
        "stages": [
            {
                "_id": "61ae064f3ed2961e152dcddc",
                "key": "email",
                "name": "PBEmail",
                "version": null,
                "data": {
                    "subject": "Hey! We need to talk to you",
                    "content": {
                        "recipientName": "",
                        "recipientEmail": "",
                        "companyName": "ACME",
                        "title": [
                            "Your team is looking for you."
                        ],
                        "action": "",
                        "code": "",
                        "messageA": "$JOIN# #Your presence is requested in the #($VALUE#channel|nameDisplay)# channel.",
                        "messageB": ""
                    },
                    "targets": [
                        "$VALUE#cmdArgs"
                    ],
                    "cc": []
                },
                "next": {
                    "DEFAULT": "message"
                },
                "customNetworkRequest": []
            },
            {
                "_id": "609c1d542f0eac0008ee17ce",
                "key": "message",
                "name": "PBMessage",
                "data": {
                    "content": "📩 Email sent ✅",
                    "contentType": "text/system",
                    "sentBy": "$VALUE#user|_id",
                    "channelIds": "$VALUE#channel|_id"
                },
                "next": {},
                "customNetworkRequest": []
            }
        ],
        "version": "v3"
    },
    "version": 0,
    "process": "none",
    "isActive": true,
    "global": false,
    "extraData": [],
    "_id": "61adff87cc298ff6f5050283",
    "name": "test bot",
    "company": "618a696218446b289ab7b847",
    "createdAt": "2021-12-06T12:14:17.323Z",
    "commands": [
        {
            "surveyIds": [],
            "isActive": true,
            "showHelp": true,
            "_id": "61ae063c2a3aad0d189d5f27",
            "description": "",
            "slashCmd": "sendemail",
            "isSlash": true,
            "isSurvey": false,
            "arguments": []
        }
    ],
    "__v": 1
}

---