Here are listed main endpoints that you could use to empower your chatbot

Get time

Use this endpoint to get date in the needed format

Sample Request

POST /api/v1/utils/datetime/now HTTP/1.1
Content-Type: application/json
Content-Length: 66
Host: common.botscrew.net

{
  "timeZone" : "UTC",
  "outputFormat" : "yyyy-MM-dd HH:mm:ss"
}

Request fields

Path Type Description

timeZone

class java.lang.String

Zone offset (+2, -4, etc.) or UTC

outputFormat

class java.lang.String

Pattern like yyyy-MM-dd HH:mm or EPOCH

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 36

{
  "data" : "2024-03-07 16:37:36"
}

Response fields

Path Type Description

data

String

Current date/time/epoch in time zone (UTC if not specified), with provided output format

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/datetime/now' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "timeZone" : "UTC",
  "outputFormat" : "yyyy-MM-dd HH:mm:ss"
}'

Format date and time

Use this endpoint to convert date from one format into another

Sample Request

POST /api/v1/utils/format/datetime HTTP/1.1
Content-Type: application/json
Content-Length: 100
Host: common.botscrew.net

{
  "date" : "2022-02-24 04:30",
  "inputFormat" : "yyyy-MM-dd HH:mm",
  "outputFormat" : "MMM dd"
}

Request fields

Path Type Description

date

class java.lang.String

Date to convert from input format to output format

inputFormat

class java.lang.String

Pattern like yyyy-MM-dd HH:mm

outputFormat

class java.lang.String

Pattern like yyyy-MM-dd HH:mm

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 23

{
  "data" : "Feb 24"
}

Response fields

Path Type Description

data

String

Converted data to output format

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/format/datetime' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "date" : "2022-02-24 04:30",
  "inputFormat" : "yyyy-MM-dd HH:mm",
  "outputFormat" : "MMM dd"
}'

Doing math

This is useful when you need to do some operations with attributes, like:

  1. Increment / decrement its value

  2. Sum two attributes

  3. Divide/multiply one attribute by another and so on…​

Sample Request

POST /api/v1/utils/math HTTP/1.1
Content-Type: application/json
Content-Length: 28
Host: common.botscrew.net

{
  "expression" : "2 + 3"
}

Request fields

Path Type Description

expression

class java.lang.String

The expression written as a string (for instance, sin(pi/2) + 1.0)

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 20

{
  "data" : "5.0"
}

Response fields

Path Type Description

data

String

The result of evaluation as double value or NaN

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/math' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "expression" : "2 + 3"
}'
PRO TIP!
Combining it with the date endpoint, we can calculate time difference!

1. First, get current date (provide EPOCH as an 'outputFromat' field);
2. Using math controller to add/substract time.

More over, you can compare values, for example:
Expression like "(120 – 40) > 100" will return 0.0.

Just use your imagination!

Doing math V2

The main difference between Math V1 and the new version is the addition of a new field called 'decimalFormat,' which allows for specifying the format of an outputted number.

Sample Request

POST /api/v2/utils/math HTTP/1.1
Content-Type: application/json
Content-Length: 53
Host: common.botscrew.net

{
  "expression" : "2 + 3",
  "decimalFormat" : "#"
}

Request fields

Path Type Description

expression

class java.lang.String

The expression written as a string (for instance, sin(pi/2) + 1.0)

decimalFormat

class java.lang.String

The DecimalFormat value written as a string (for instance, #)

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 18

{
  "data" : "5"
}

Response fields

Path Type Description

data

String

The result of evaluation as double value or NaN

CURL request example

$ curl 'https://common.botscrew.net/api/v2/utils/math' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "expression" : "2 + 3",
  "decimalFormat" : "#"
}'

Redirect user

This allows to redirect a user using the atom name saved to an attribute

Sample Request

POST /api/v1/utils/messages/redirect HTTP/1.1
Content-Type: application/json
Content-Length: 228
Host: common.botscrew.net

{
  "nextAtomName" : "Welcome message",
  "chatId" : 123456789,
  "botId" : 222,
  "authentication" : {
    "chatbotPlatformToken" : "<YOUR TOKEN>",
    "chatbotPlatformHost" : "https://platform.botscrew.net/api/public/v1"
  }
}

Request fields

Path Type Description

botId

class java.lang.Long

The ID for your bot — could be obtained from attribute called bot_id

chatId

class java.lang.Long

User’s chat ID — could be obtained from attribute called chat_id

nextAtomName

class java.lang.String

The atom name to redirect to (case sensitive)

authentication.chatbotPlatformHost

class java.lang.String

The host for your platform (should include https scheme and path to the public API)

authentication.chatbotPlatformToken

class java.lang.String

You can generate your token in Settings → Integrations —> API

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 29

{
  "data" : "Atom is sent"
}

Response fields

Path Type Description

data

String

Notification that the atom is sent.

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/messages/redirect' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "nextAtomName" : "Welcome message",
  "chatId" : 123456789,
  "botId" : 222,
  "authentication" : {
    "chatbotPlatformToken" : "<YOUR TOKEN>",
    "chatbotPlatformHost" : "https://platform.botscrew.net/api/public/v1"
  }
}'

AES CBC 128 decrypt

This allows to decrypt a message using AES CBC 128 algorithm

Sample Request

POST /api/v1/utils/crypto/aes-cbc-128/decrypt HTTP/1.1
Content-Type: application/json
Content-Length: 127
Host: common.botscrew.net

    {
        "message":"qS/zU8XTW62J9fmGYAGppyTvQJk0UG4JE0A+5ghSHmM=",
        "key":"b869302b60a78f5ae19973c128578a67"
    }

Request fields

Path Type Description

message

class java.lang.String

Base64-encoded message to decrypt

key

class java.lang.String

Key to decrypt message — 32 hex characters representing 16 bytes

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 30

{
  "data" : "200031:567765"
}

Response fields

Path Type Description

data

String

Decrypted message

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/crypto/aes-cbc-128/decrypt' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '    {
        "message":"qS/zU8XTW62J9fmGYAGppyTvQJk0UG4JE0A+5ghSHmM=",
        "key":"b869302b60a78f5ae19973c128578a67"
    }
'

String contains

This allows to check if substring contains in value

Sample Request

POST /api/v2/utils/strings HTTP/1.1
Content-Type: application/json
Content-Length: 121
Host: common.botscrew.net

{
  "action" : "contains",
  "data" : {
    "value" : "The sun was just beginning to set.",
    "substring" : "sun"
  }
}

Request fields

Path Type Description

action

class java.lang.String

Action to do

data.value

class java.lang.String

Text to check if it contains another text

data.substring

class java.lang.String

Search text

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 25

{
  "data" : [ "true" ]
}

Response fields

Path Type Description

data

class java.lang.Boolean

Boolean that represents is value contains substring

CURL request example

$ curl 'https://common.botscrew.net/api/v2/utils/strings' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "action" : "contains",
  "data" : {
    "value" : "The sun was just beginning to set.",
    "substring" : "sun"
  }
}'

String compare

This allows to compare two strings. The result is a lexicographical comparison of the two strings. If two strings are equal, it is guaranteed to return 0. If the first one is "bigger", the value will be >0, otherwise <0.

Sample Request

POST /api/v1/utils/strings HTTP/1.1
Content-Type: application/json
Content-Length: 76
Host: common.botscrew.net

{
  "action" : "compare",
  "data" : {
    "values" : [ "123", "123" ]
  }
}

Request fields

Path Type Description

action

class java.lang.String

Action to do

data.values

class [Ljava.lang.String;

Array with to strings to compare

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 41

{
  "data" : {
    "response" : "0"
  }
}

Response fields

Path Type Description

data.response

class java.lang.String

Lexicographical difference of the provided strings. String value of integer.

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/strings' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "action" : "compare",
  "data" : {
    "values" : [ "123", "123" ]
  }
}'

Parse JSON String to JSON object

This allows to parse a JSON string to a JSON object.

Sample Request

POST /api/v1/utils/strings HTTP/1.1
Content-Type: application/json
Content-Length: 197
Host: common.botscrew.net

{
  "action" : "parseJson",
  "data" : {
    "value" : "{\n  \"city\": \"East Andrea\",\n  \"province\": \"Wyoming\",\n  \"province_code\": \"WY\",\n  \"street\": \"42 Random Throughway\"\n}"
  }
}

Request fields

Path Type Description

action

class java.lang.String

Action to do. In this case, 'parseJson'

data.value

class java.lang.String

JSON string to parse.

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 175

{
  "data" : {
    "response" : {
      "city" : "East Andrea",
      "province" : "Wyoming",
      "province_code" : "WY",
      "street" : "42 Random Throughway"
    }
  }
}

Response fields

Path Type Description

data.response.city

class java.lang.String

Parsed city from the JSON string.

data.response.province

class java.lang.String

Parsed province from the JSON string.

data.response.province_code

class java.lang.String

Parsed province code from the JSON string.

data.response.street

class java.lang.String

Parsed street from the JSON string.

CURL request example

$ curl 'https://common.botscrew.net/api/v1/utils/strings' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{
  "action" : "parseJson",
  "data" : {
    "value" : "{\n  \"city\": \"East Andrea\",\n  \"province\": \"Wyoming\",\n  \"province_code\": \"WY\",\n  \"street\": \"42 Random Throughway\"\n}"
  }
}'

Email v1 send

This endpoint allows sending emails

Sample Request

POST /api/v2/utils/email/send HTTP/1.1
Content-Type: application/json
Sender-Email: example_sender@mail.com
Sender-Password: password
Content-Length: 247
Host: common.botscrew.net

{
  "email" : {
    "subject" : "Subject of the email",
    "body" : "Body of the email",
    "receiver" : "example_receiver@mail.com",
    "isHtml" : false
  },
  "senderConfigData" : {
    "host" : "smtp-mail.outlook.com",
    "port" : 587
  }
}

Request fields

Path Type Description

email.subject

class java.lang.String

Subject of the email

email.body

class java.lang.String

Body of the email

email.receiver

class java.lang.String

Email address of the receiver

email.isHtml

class java.lang.Boolean

Is body of the email is HTML

senderConfigData.host

class java.lang.String

SMTP server used for sending emails

senderConfigData.port

class java.lang.Integer

SMTP port

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 27

{
  "data" : "email sent"
}

Response fields

Path Type Description

data

class java.lang.String

Text 'email sent' that indicates that request was successful

CURL request example

$ curl 'https://common.botscrew.net/api/v2/utils/email/send' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Sender-Email: example_sender@mail.com' \
    -H 'Sender-Password: password' \
    -d '{
  "email" : {
    "subject" : "Subject of the email",
    "body" : "Body of the email",
    "receiver" : "example_receiver@mail.com",
    "isHtml" : false
  },
  "senderConfigData" : {
    "host" : "smtp-mail.outlook.com",
    "port" : 587
  }
}'

Email v2 send

This endpoint allows sending emails with HTML and attachment

Sample Request

POST /api/v2/utils/email/send HTTP/1.1
Content-Type: application/json
Sender-Email: example_sender@mail.com
Sender-Password: password
Content-Length: 542
Host: common.botscrew.net

{
  "email" : {
    "subject" : "Subject of the email",
    "body" : "Body of the email. Attributes resolve {{test}}",
    "receiver" : "example_receiver@mail.com",
    "isHtml" : false,
    "attachment" : {
      "link" : "https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_PDF.pdf",
      "name" : "Free_Test_Data_1MB_PDF.pdf",
      "description" : "Description for the file"
    }
  },
  "senderConfigData" : {
    "host" : "smtp-mail.outlook.com",
    "port" : 587
  },
  "attributes" : {
    "test" : "success"
  }
}

Request fields

Path Type Description

email.subject

class java.lang.String

Subject of the email

email.body

class java.lang.String

Body of the email - plain text or base64 encoded HTML

email.receiver

class java.lang.String

Email address of the receiver

email.isHtml

class java.lang.Boolean

Is body of the email is HTML

senderConfigData.host

class java.lang.String

SMTP server used for sending emails

senderConfigData.port

class java.lang.Integer

SMTP port

attributes

Object

User attributes from platform

email.attachment.link

class java.lang.Integer

Link to the file

email.attachment.name

class java.lang.Integer

Name of the file

email.attachment.description

class java.lang.Integer

Description of the file

Sample Response

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 27

{
  "data" : "email sent"
}

Response fields

Path Type Description

data

class java.lang.String

Text 'email sent' that indicates that request was successful

CURL request example

$ curl 'https://common.botscrew.net/api/v2/utils/email/send' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Sender-Email: example_sender@mail.com' \
    -H 'Sender-Password: password' \
    -d '{
  "email" : {
    "subject" : "Subject of the email",
    "body" : "Body of the email. Attributes resolve {{test}}",
    "receiver" : "example_receiver@mail.com",
    "isHtml" : false,
    "attachment" : {
      "link" : "https://freetestdata.com/wp-content/uploads/2021/09/Free_Test_Data_1MB_PDF.pdf",
      "name" : "Free_Test_Data_1MB_PDF.pdf",
      "description" : "Description for the file"
    }
  },
  "senderConfigData" : {
    "host" : "smtp-mail.outlook.com",
    "port" : 587
  },
  "attributes" : {
    "test" : "success"
  }
}'