REST API of Bot.Az allows to programmatically manipulate various resources inside Bot.Az from your server.

Data format

The only supported data format is JSON.

POST and PUT requests must include Content-Type: application/json header:

Content-Type: application/json

Errors

In case of an error Bot.Az will respond with an appropriate status code, response body will (in most cases) contain detailed information about the error:

{
	"status": "error",
	"message": "You must be logged in to do this."
}

messages

Send, edit or delete agents’ messages. Receive any message by its ID.

POST Send a message as an agent

https://app.bot.az/api/messages/

Example request

{
	"userId": "MvSzqx36KksKNxHmK",
	"visitorId": "BtR7qAyvZfTWoaC7a",
	"text": "Good morning! Can I help you?"
}

userId — agent’s ID generated for each agent and available at the agents page

visitorId — visitor’s ID generated for each visitor and available at the address bar of the browser while chat with the visitor is open (https://app.bot.az/chat/:id)

text — message text

Example response

Newly created message is returned as a response:

{
	"_id": "qZkS5QLZSBLKzYAwm",
	"userId": "MvSzqx36KksKNxHmK",
	"visitorId": "BtR7qAyvZfTWoaC7a",
	"text": "Good morning! Can I help you?",
	"seen": false,
	"sentAt": "2019-01-03T07:14:07.438Z"
}

GET Get an existing message

https://app.bot.az/api/messages/:id

:id — ID of the message

Example response

Requested message is returned as a response:

{
	"_id": "qZkS5QLZSBLKzYAwm",
	"userId": "MvSzqx36KksKNxHmK",
	"visitorId": "BtR7qAyvZfTWoaC7a",
	"text": "Good afternoon! Can I help you?",
	"seen": false,
	"sentAt": "2019-01-03T07:14:07.438Z"
}

PUT Edit agent’s message

https://app.bot.az/api/messages/:id

:id — ID of the message

Only agents’ messages can be edited.

Example request

{
	"text": "Good evening! Can I help you?"
}

Example response

Updated message is returned as response:

{
	"_id": "qZkS5QLZSBLKzYAwm",
	"userId": "MvSzqx36KksKNxHmK",
	"visitorId": "BtR7qAyvZfTWoaC7a",
	"text": "Good evening. Can I help you?",
	"seen": false,
	"sentAt": "2019-01-03T07:14:07.438Z"
}

DELETE Delete agent’s message

https://app.bot.az/api/messages/:id

:id — ID of the message

Only agents’ messages can be deleted.

Example response

Deleted message is returned as response:

{
	"_id": "qZkS5QLZSBLKzYAwm",
	"userId": "MvSzqx36KksKNxHmK",
	"visitorId": "BtR7qAyvZfTWoaC7a",
	"text": "Good evening. Can I help you?",
	"seen": false,
	"sentAt": "2019-01-03T07:14:07.438Z"
}

visitors

Receive visitors’ information. Edit basic visitor’s information (such as name, email, phone number, notes) as if it was edited from Bot.Az dashboard.

GET Receive visitor’s information

https://app.bot.az/api/visitors/:id

:id — visitor’s ID generated for each visitor and available at the address bar of the browser while chat with the visitor is open (https://app.bot.az/chat/:id)

Example response

Requested visitor’s info is returned as a response:

{
	"_id": "BtR7qAyvZfTWoaC7a",
	"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
	"appName": "Netscape",
	"appVersion": "5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
	"platform": "Linux x86_64",
	"cookieEnabled": true,
	"banned": false,
	"addedAt": "2018-11-22T12:18:48.812Z",
	"agents": [
		"MvSzqx36KksKNxHmK"
	],
	"name": "Anar Hasanzade",
	"email": "[email protected]",
	"phone": "+994124801574",
	"notes": "Asked about tariff plans",
	"preformFilled": true,
	"lastOnline": "2019-01-03T09:00:48.059Z",
	"showBotMessages": false
}

PUT Edit basic visitor’s information

https://app.bot.az/api/visitors/:id

:id — visitor’s ID generated for each visitor and available at the address bar of the browser while chat with the visitor is open (https://app.bot.az/chat/:id)

Example requests

Set visitor’s name, email address, phone number and notes:

{
	"email": "[email protected]",
	"name": "Anar Hasanzade",
	"phone": "+994124801574",
	"notes": "Asked about new functionality"
}

Remove visitor’s phone number and change email address:

{
	"email": null,
	"phone": "+994124801574",
}

null is used to remove values.

Example response

Updated visitor’s info is returned as a response:

{
	"_id": "BtR7qAyvZfTWoaC7a",
	"userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
	"appName": "Netscape",
	"appVersion": "5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/70.0.3538.110 Safari/537.36",
	"platform": "Linux x86_64",
	"cookieEnabled": true,
	"banned": false,
	"addedAt": "2018-11-22T12:18:48.812Z",
	"agents": [
		"MvSzqx36KksKNxHmK"
	],
	"name": "Anar Hasanzade",
	"email": null,
	"phone": "+994124801574",
	"notes": "Asked about new functionality",
	"preformFilled": true,
	"lastOnline": "2019-01-03T09:00:48.059Z",
	"showBotMessages": false
}