RetailCRM
API docs by Redocly

MG Node Bot API (1.0.0)

Download OpenAPI specification:Download

MG Node Bot API

Bot

Retrieve list of bots

Retrieves a list of all available bots with optional filtering

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

self
string (Boolean)
Enum: "1" "0" "true" "false"

Filter to include only the current bot

active
string (Boolean)
Enum: "1" "0" "true" "false"

Filters bots by activity status

role
Array of strings (Role)
Items Enum: "responsible" "distributor" "hidden"
Example: role=responsible

Filters bots by one or more assigned roles

since
string <date-time>

Lower limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until
string <date-time>

Upper limit of the date of the last object update

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

Responses

Response Schema: application/json
Array
id
required
integer <int64>

Unique identifier of the bot

name
required
string

Human-readable name of the bot

client_id
required
string

Unique external client identifier of the bot

roles
required
Array of strings (Role)
Items Enum: "responsible" "distributor" "hidden"

List of roles assigned to the bot

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

is_active
required
boolean

Indicates whether the bot is currently active

is_self
required
boolean

Indicates whether this bot is the one currently authenticated

is_system
required
boolean

Indicates whether this bot is a system-level bot

avatar_url
string <uri>

Public URL of the bot's avatar image

deactivated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "avatar_url": "https://avatar.demo/avatar-url",
    • "client_id": "demo-bot-id",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "deactivated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "id": 1,
    • "is_active": true,
    • "is_self": true,
    • "is_system": false,
    • "name": "demo-bot",
    • "roles": [
      ],
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00"
    }
]

Update current bot profile

Updates the information of the currently authenticated bot

Authorizations:
bot_token
Request Body schema: application/json

Bot update request

name
string <= 255 characters

Bot name

avatar_url
string <uri>

URL of bot avatar

roles
Array of strings (Roles)
Items Enum: "responsible" "distributor" "hidden"

Bot role types array

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{ }

Remove a bot command

Deletes the command associated with the given name

Authorizations:
bot_token
path Parameters
command_name
required
string <= 32 characters

Unique identifier of the bot command. Used to reference a specific command in the system

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Channel

Retrieve available channels

Returns a list of channels with optional filters

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

types
Array of strings (ChannelType)
Items Enum: "telegram" "tiktok" "fbmessenger" "viber" "whatsapp" "skype" "vk" "instagram" "consultant" "yandex_chat" "odnoklassniki" "max" "ozon" "wildberries" "yandex_market" "mega_market" "avito" "drom" "youla" "custom"
Example: types=telegram

Filters channels by one or more specified types

active
string (Boolean)
Enum: "1" "0" "true" "false"

Filters channels by activity status

since
string <date-time>

Lower limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until
string <date-time>

Upper limit of the date of the last object update

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

Responses

Response Schema: application/json
Array
id
required
integer <int64>

Unique identifier of the channel

type
required
string
Enum: "telegram" "tiktok" "fbmessenger" "viber" "whatsapp" "skype" "vk" "instagram" "consultant" "yandex_chat" "odnoklassniki" "max" "ozon" "wildberries" "yandex_market" "mega_market" "avito" "drom" "youla" "custom"

Type of the communication channel

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

activated_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

is_active
required
boolean

Indicates whether the channel is currently active

required
object

Configuration settings specific to the channel type

deactivated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

name
string or null

Optional human-readable name of the channel

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "activated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "deactivated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "id": 1,
    • "is_active": true,
    • "name": "Example Channel",
    • "settings": {
      },
    • "type": "telegram",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00"
    }
]

Chat

Retrieve chat list

Returns a filtered list of chats available to the bot

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

channel_id
integer >= 1

Filter by channel ID

channel_type
string (ChannelType)
Enum: "telegram" "tiktok" "fbmessenger" "viber" "whatsapp" "skype" "vk" "instagram" "consultant" "yandex_chat" "odnoklassniki" "max" "ozon" "wildberries" "yandex_market" "mega_market" "avito" "drom" "youla" "custom"
Example: channel_type=telegram

Filter by channel type

customer_id
integer >= 1

Filter by customer ID

customer_external_id
string non-empty

Filter by external customer ID

include_mass_communication
string (Boolean)
Enum: "1" "0" "true" "false"

Whether to include mass communication chats/messages

Responses

Response Schema: application/json
Array
id
required
integer <int64>

Unique identifier of the chat

not_read_messages
required
integer <int64>

Number of unread messages in the chat

unread
required
boolean

Indicates whether any user has unread messages in this chat

author_id
integer <int64>
Deprecated

ID of the user who initiated the chat

avatar
string

URL of the chat's avatar image

object or null

The communication channel (e.g., Telegram, Viber) associated with this chat

object or null

The customer participating in the chat, if any

last_activity
string <date-time>

Date and time in RFC 3339 format

object

The most recent dialog in the chat

object or null

The latest message in the chat, including system or service messages

object or null

The most recent message sent by a user in the chat

name
string

Display name of the chat

reply_deadline
string <date-time>

Date and time in RFC 3339 format

waiting_level
string or null
Enum: "warning" "danger" "none"

Current urgency level of the chat based on business logic (e.g., SLA violations).

waiting_level_transition_time
string or null <date-time>

Date and time in RFC 3339 format

created_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "author_id": 100,
    • "avatar": "https://avatar.demo/chat-avatar",
    • "channel": {
      },
    • "customer": {
      },
    • "id": 1,
    • "last_activity": "2006-01-02T15:04:05Z07:00",
    • "last_dialog": {
      },
    • "last_message": {
      },
    • "last_user_message": {
      },
    • "name": "Example Chat",
    • "not_read_messages": 12,
    • "reply_deadline": "2006-01-02T15:04:05Z07:00",
    • "unread": true,
    • "waiting_level": "warning",
    • "waiting_level_transition_time": "2006-01-02T15:04:05Z07:00",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00"
    }
]

Command

List available bot commands

Returns a list of bot commands filtered by optional parameters

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

since_id
integer <int64> >= 1

Lower bound for object identifiers

since
string <date-time>

Lower limit of the date of the last object update

until_id
integer <int64> >= 1

Upper bound for object identifiers

until
string <date-time>

Upper limit of the date of the last object update

name
string <= 32 characters

Filter commands by name

Responses

Response Schema: application/json
Array
created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

description
required
string

Human-readable description of the command.

id
required
integer <int64>

Unique identifier of the command.

name
required
string

Unique command name, used for execution or identification

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "description": "demo-description",
    • "id": 1,
    • "name": "demo-name",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00"
    }
]

Create or update a command

Creates a new command or updates an existing one with the specified name

Authorizations:
bot_token
path Parameters
command_name
required
string <= 32 characters

Unique identifier of the bot command. Used to reference a specific command in the system

Request Body schema: application/json

Request body for creating or updating a bot command

One of
description
required
string <= 64 characters

Human-readable description of the command's purpose or behavior

name
string

Unique identifier for the command

Responses

Response Schema: application/json
created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

description
required
string

Human-readable description of the command.

id
required
integer <int64>

Unique identifier of the command.

name
required
string

Unique command name, used for execution or identification

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Request samples

Content type
application/json
Example
{
  • "name": "Demo command name",
  • "description": "Demo command description"
}

Response samples

Content type
application/json
{
  • "created_at": "2006-01-02T15:04:05Z07:00",
  • "description": "demo-description",
  • "id": 1,
  • "name": "demo-name",
  • "updated_at": "2006-01-02T15:04:05Z07:00"
}

Customer

Get customers list

Returns a list of customers

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

channel_id
integer >= 1

Filter by channel ID

channel_type
string (ChannelType)
Enum: "telegram" "tiktok" "fbmessenger" "viber" "whatsapp" "skype" "vk" "instagram" "consultant" "yandex_chat" "odnoklassniki" "max" "ozon" "wildberries" "yandex_market" "mega_market" "avito" "drom" "youla" "custom"
Example: channel_type=telegram

Filter by channel type

external_id
string

Filter by external identifier

Responses

Response Schema: application/json
Array
id
required
integer <int64>
created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

is_blocked
required
boolean
external_id
string or null
channel_id
integer or null <int64>
username
string or null
first_name
string or null
last_name
string or null
updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

revoked_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

avatar_url
string or null
profile_url
string or null
country
string or null
language
string or null
phone
string or null
email
string or null
object or null

UTM parameters for tracking marketing campaigns

Response samples

Content type
application/json
[
  • {
    • "id": 1,
    • "external_id": "e3456",
    • "channel_id": 5,
    • "username": "demo_user",
    • "first_name": "Thomas",
    • "last_name": "Smith",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "revoked_at": "2006-01-02T15:04:05.999999Z07:00",
    • "avatar_url": "https://avatar.demo/demo-avatar",
    • "profile_url": "https://profile.demo/demo-profile",
    • "country": "US",
    • "language": "US",
    • "phone": "928-970-2685",
    • "email": "demo@customer.demo",
    • "is_blocked": true,
    • "utm": {
      }
    }
]

Dialog

Retrieve list of dialogs

Returns a list of dialogs with optional filters

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

chat_id
integer >= 1

Filter by chat identifier

user_id
integer >= 1

Filter by user ID

bot_id
integer >= 1

Filter by bot ID

active
string (Boolean)
Enum: "1" "0" "true" "false"

Filter by activity flag

assign
string (Boolean)
Enum: "1" "0" "true" "false"

Filter by assignment status

include_mass_communication
string (Boolean)
Enum: "1" "0" "true" "false"

Whether to include mass communication chats/messages

Responses

Response Schema: application/json
Array
chat_id
required
integer <int64>

ID of the chat this dialog belongs to

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

id
required
integer <int64>

Unique identifier of the dialog

is_active
required
boolean

Indicates if the dialog is currently active

is_assigned
required
boolean

Indicates if the dialog is assigned to someone

begin_message_id
integer or null <int64>

ID of the first message in the dialog

bot_id
integer or null <int64>

ID of the bot assigned to the dialog, if any

closed_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

ending_message_id
integer or null <int64>

ID of the last message in the dialog

object

Current responsible entity for the dialog

Array of objects (Tag)

List of tags associated with the dialog

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

object

UTM parameters associated with the dialog

Response samples

Content type
application/json
[
  • {
    • "begin_message_id": 32,
    • "bot_id": 20,
    • "chat_id": 3,
    • "closed_at": "2006-01-02T15:04:05.999999Z07:00",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "ending_message_id": 39,
    • "id": 1,
    • "is_active": false,
    • "is_assigned": true,
    • "responsible": {
      },
    • "tags": [
      ],
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "utm": {
      }
    }
]

Assign a responsible user to a dialog

Sets or updates the user responsible for handling the specified dialog

Authorizations:
bot_token
path Parameters
dialog_id
required
integer <int64>
Example: 1

Unique identifier of the dialog

Request Body schema: application/json

Request to assign a responsible user and bot to a dialog

bot_id
integer <int64>

Unique identifier of the bot assigned to the dialog

user_id
integer <int64>

Unique identifier of the user in chats to assign as responsible

Responses

Response Schema: application/json
required
object

Currently responsible user for the dialog

is_reassign
required
boolean

Indicates if the assignment is a reassignment

left_user_id
integer or null <int64>

Unique identifier of the user in chats who left the dialog, if applicable

object or null

Previously responsible user before reassignment

Request samples

Content type
application/json
{
  • "bot_id": 1,
  • "user_id": 1
}

Response samples

Content type
application/json
{
  • "is_reassign": true,
  • "left_user_id": 0,
  • "previous_responsible": {
    • "assigned_at": "2006-01-02T15:04:05.999999Z07:00",
    • "external_id": "string",
    • "id": 1,
    • "type": "user"
    },
  • "responsible": {
    • "assigned_at": "2006-01-02T15:04:05.999999Z07:00",
    • "external_id": "string",
    • "id": 1,
    • "type": "user"
    }
}

Unassign responsible user from dialog

Removes the currently assigned responsible user from the specified dialog

Authorizations:
bot_token
path Parameters
dialog_id
required
integer <int64>
Example: 1

Unique identifier of the dialog

Responses

Response Schema: application/json
object or null

Previously responsible user before unassignment

Response samples

Content type
application/json
{
  • "previous_responsible": {
    • "assigned_at": "2006-01-02T15:04:05.999999Z07:00",
    • "external_id": "string",
    • "id": 1,
    • "type": "user"
    }
}

Close a dialog

Marks the specified dialog as closed, preventing further updates or messages

Authorizations:
bot_token
path Parameters
dialog_id
required
integer <int64>
Example: 1

Unique identifier of the dialog

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

Add tags to a dialog

Appends tags to the specified dialog

Authorizations:
bot_token
path Parameters
dialog_id
required
integer <int64>
Example: 1

Unique identifier of the dialog

Request Body schema: application/json

Request to add tags to a dialog

required
Array of objects non-empty

List of tags to add

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "tags": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Remove tags from a dialog

Removes tags from the specified dialog

Authorizations:
bot_token
path Parameters
dialog_id
required
integer <int64>
Example: 1

Unique identifier of the dialog

Request Body schema: application/json

Request to delete tags from a dialog

required
Array of objects non-empty

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "tags": [
    • {
      }
    ]
}

Response samples

Content type
application/json
{ }

Create a dialog

Creates a new dialog within the specified chat

Authorizations:
bot_token
path Parameters
chat_id
required
integer <int64>
Example: 1

Unique identifier of the chat

Request Body schema: application/json

Request to create a new dialog

bot_id
integer or null <int64> >= 1

ID of the bot who starts the dialog

user_id
integer or null <int64> >= 1

Unique identifier of the user in chats who starts the dialog

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier of the created dialog

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

Request samples

Content type
application/json
{
  • "bot_id": 32,
  • "user_id": 43
}

Response samples

Content type
application/json
{
  • "created_at": "2006-01-02T15:04:05.999999Z07:00",
  • "id": 1
}

File

Get direct file URL by ID

Returns a direct URL for downloading a previously uploaded file using its unique identifier

Authorizations:
bot_token
path Parameters
id
required
string <uuid>
Example: e33e5398-814a-47d6-902a-466ba120ce45

Unique identifier (UUID) of the file

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier of the file

type
required
string (FileType)
Enum: "none" "image" "video" "file" "audio"

File type

size
required
integer

Size of the file in bytes

transcription
string or null

Optional text transcription of the file content, if applicable

transcription_status
string
Enum: "in_progress" "ready" "error"

Status of the file transcription process

url
string <uri>

Direct URL for downloading or accessing the uploaded file

Response samples

Content type
application/json
{
  • "id": "e33e5398-814a-47d6-902a-466ba120ce45",
  • "size": 102384,
  • "transcription": "Demo transcription",
  • "transcription_status": "ready",
  • "type": "file",
  • "url": "https://file.demo/demo-file"
}

Upload a new file

Uploads a new file to the server using multipart/form-data

Authorizations:
bot_token
Request Body schema: multipart/form-data
required
file
required
string <binary>

Binary file data to upload (e.g. image, document, video)

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier of the file

type
required
string (FileType)
Enum: "none" "image" "video" "file" "audio"

File type

size
required
integer

Size of the file in bytes

transcription
string or null

Optional text transcription of the file content, if applicable

transcription_status
string
Enum: "in_progress" "ready" "error"

Status of the file transcription process

Response samples

Content type
application/json
{
  • "id": "e33e5398-814a-47d6-902a-466ba120ce45",
  • "size": 102384,
  • "transcription": "Demo transcription",
  • "transcription_status": "ready",
  • "type": "file"
}

Upload a file from a URL

Downloads a file from the provided URL and uploads it to the server

Authorizations:
bot_token
Request Body schema: application/json

Request payload for uploading a file from a remote URL

url
required
string <uri>

The URL of the file to download and upload

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier of the file

type
required
string (FileType)
Enum: "none" "image" "video" "file" "audio"

File type

size
required
integer

Size of the file in bytes

transcription
string or null

Optional text transcription of the file content, if applicable

transcription_status
string
Enum: "in_progress" "ready" "error"

Status of the file transcription process

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "e33e5398-814a-47d6-902a-466ba120ce45",
  • "size": 102384,
  • "transcription": "Demo transcription",
  • "transcription_status": "ready",
  • "type": "file"
}

Update metadata of a previously uploaded file

Updates metadata of the specified file by its identifier

Authorizations:
bot_token
path Parameters
id
required
string <uuid>
Example: e33e5398-814a-47d6-902a-466ba120ce45

Unique identifier (UUID) of the file

Request Body schema: application/json

Request payload for updating metadata of a file

transcription
required
string

Updated transcription text associated with the file

transcription_status
string (FileTranscriptionStatus)
Enum: "in_progress" "ready" "error"

Current status of the file transcription process

Responses

Response Schema: application/json
id
required
string <uuid>

Unique identifier of the file

type
required
string (FileType)
Enum: "none" "image" "video" "file" "audio"

File type

size
required
integer

Size of the file in bytes

transcription
string or null

Optional text transcription of the file content, if applicable

transcription_status
string
Enum: "in_progress" "ready" "error"

Status of the file transcription process

Request samples

Content type
application/json
{
  • "transcription": "Example updated transcription",
  • "transcription_status": "ready"
}

Response samples

Content type
application/json
{
  • "id": "e33e5398-814a-47d6-902a-466ba120ce45",
  • "size": 102384,
  • "transcription": "Demo transcription",
  • "transcription_status": "ready",
  • "type": "file"
}

User

Retrieves a list of chat members

Returns a list of chat members filtered by optional parameters

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

chat_id
integer >= 1

Filter by chat identifier

user_id
integer >= 1

Filter by user ID

state
string
Enum: "active" "kicked" "leaved"

Filter by member state

Responses

Response Schema: application/json
Array
chat_id
required
integer <int64>

ID of the chat the user is a member of

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

id
required
integer <int64>

Unique ID of the chat membership record

is_author
required
boolean
Deprecated

Indicates whether the user is the author of the chat

state
required
string
Enum: "active" "kicked" "leaved"

Membership state of the user in the chat

user_id
required
integer <int64>

Unique identifier of the user in chats

updated_at
string <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "chat_id": 123,
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "id": 123,
    • "is_author": false,
    • "state": "active",
    • "user_id": 123
    }
]

Retrieves a list of users

Returns a list of users filtered by optional parameters

Authorizations:
bot_token
query Parameters
id
integer <int> >= 1

Unique identifier of the object

since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

active
string (Boolean)
Enum: "1" "0" "true" "false"

Filter users by activity status

online
string (Boolean)
Enum: "1" "0" "true" "false"

Filter users by online status

external_id
string

Filter by external identifier

Responses

Response Schema: application/json
Array
id
required
integer <int64>

Internal user ID

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

available
required
boolean

Indicates if the user is available for communication

is_online
required
boolean

Flag indicating if the user is currently online

connected
required
boolean

Indicates if the user has ever connected to the system

is_active
required
boolean

Flag indicating if the user is marked as active

is_technical_account
required
boolean

Indicates if the user is a technical (system) account

avatar_url
string <uri>

URL of the user's avatar

external_id
string

External identifier of the user (e.g. from external system)

first_name
string

First name of the user

last_name
string

Last name of the user

revoked_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

username
string

Username or login name of the user

Response samples

Content type
application/json
[
  • {
    • "avatar_url": "https://avatar.demo/demo-avatar",
    • "available": true,
    • "connected": true,
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "external_id": "user_324",
    • "first_name": "John",
    • "id": 1,
    • "is_active": true,
    • "is_online": true,
    • "is_technical_account": false,
    • "last_name": "Doe",
    • "revoked_at": "2006-01-02T15:04:05.999999Z07:00",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00",
    • "username": "demo-username"
    }
]

Message

Get message list

Returns a list of messages filtered by various criteria

Authorizations:
bot_token
query Parameters
since
string <date-time>

Lower limit of the date of the last object update

until
string <date-time>

Upper limit of the date of the last object update

since_id
integer <int64> >= 1

Lower bound for object identifiers

until_id
integer <int64> >= 1

Upper bound for object identifiers

limit
integer <int> [ 1 .. 1000 ]

The number of elements in the response. Default value is 100

id
Array of integers <int64> [ items <int64 > ]

Filter by a list of message IDs

chat_id
integer >= 1

Filter by chat identifier

user_id
integer >= 1

Filter by user ID

customer_id
integer >= 1

Filter by customer ID

bot_id
integer >= 1

Filter by bot ID

dialog_id
integer <int64> >= 1

Filter by dialog ID

channel_id
integer >= 1

Filter by channel ID

channel_type
string (ChannelType)
Enum: "telegram" "tiktok" "fbmessenger" "viber" "whatsapp" "skype" "vk" "instagram" "consultant" "yandex_chat" "odnoklassniki" "max" "ozon" "wildberries" "yandex_market" "mega_market" "avito" "drom" "youla" "custom"
Example: channel_type=telegram

Filter by channel type

type
string (MessageType)
Enum: "text" "system" "command" "order" "product" "file" "image" "audio"
Example: type=text

Filter by message type

include_mass_communication
string (Boolean)
Enum: "1" "0" "true" "false"

Whether to include mass communication chats/messages

scope
string
Enum: "public" "private"

Filter by message scope (public or private)

Responses

Response Schema: application/json
Array
actions
required
Array of strings (MessageAction)
Items Enum: "edit" "delete" "quote"

List of interactive actions associated with the message

chat_id
required
integer <int64>

ID of the chat this message belongs to

id
required
integer <int64>

Unique identifier of the message

is_edit
required
boolean

Indicates whether the message was edited

is_read
required
boolean

Indicates whether the message was read

scope
required
string
Enum: "undefined" "public" "private"

Scope of the message

status
required
string
Enum: "undefined" "received" "sending" "sent" "failed" "seen"

Current status of the message

time
required
string <date-time>

Timestamp when the message was created

type
required
string
Enum: "text" "system" "command" "order" "product" "file" "image" "audio"

Type of the message

created_at
required
string <date-time>

Date and time in RFC 3339 format with microseconds

action
string or null
Enum: "dialog_opened" "dialog_closed" "user_joined" "user_left" "dialog_assign" "customer_blocked" "customer_unblocked" "dialog_unassign" "dialog_tag_added" "dialog_tag_removed"

System-level action represented by the message

content
string or null

Text content of the message

object or null

Optional dialog related to the message

object or null

Error info related to message sending or processing

object

Actor who sent the message

Array of objects (MessageFile)

List of attached files

note
string or null

Optional internal note or comment for the message

object or null

Optional order data linked to the message

object or null

Optional product data referenced in the message

object or null

Quoted message, if this is a reply

object or null

User responsible for this message or task

template_code
string

Template code for a template message

object or null

Attachments specific to a transport layer

object or null

User associated with the message

channel_id
integer <int64>

ID of the channel where the message was sent

channel_sent_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

updated_at
string or null <date-time>

Date and time in RFC 3339 format with microseconds

Response samples

Content type
application/json
[
  • {
    • "action": "user_joined",
    • "actions": [
      ],
    • "chat_id": 1,
    • "content": "Hi there!",
    • "dialog": {
      },
    • "error": {
      },
    • "from": {
      },
    • "id": 1,
    • "is_edit": true,
    • "is_read": true,
    • "items": [
      ],
    • "note": "Nice cats",
    • "order": {
      },
    • "product": {},
    • "quote": {
      },
    • "responsible": {
      },
    • "scope": "public",
    • "status": "seen",
    • "template_code": "string",
    • "time": "2006-01-02T15:04:05Z07:00",
    • "transport_attachments": {},
    • "type": "text",
    • "user": {
      },
    • "channel_id": 1,
    • "channel_sent_at": "2006-01-02T15:04:05.999999Z07:00",
    • "created_at": "2006-01-02T15:04:05.999999Z07:00",
    • "updated_at": "2006-01-02T15:04:05.999999Z07:00"
    }
]

Send new message

Send a new message to a specified transport channel

Authorizations:
bot_token
Request Body schema: application/json

Request payload for sending a new message

chat_id
required
integer <int64>

ID of the chat where the message is being sent

scope
required
string
Enum: "undefined" "public" "private"

Scope of the message (e.g., user, system)

content
string

Message text content (required for text messages only)

Array of objects

File attachments (required for file, audio and image messages)

note
string

Note or description for the file (required for file, audio and image messages)

object

Order data (required for order messages only)

object

Product data (required for product messages only)

quote_message_id
integer <int64>

ID of the quoted message (required for text messages only)

type
string
Enum: "text" "system" "command" "order" "product" "file" "image" "audio"

Type of the message (e.g. text, file, order, product)

object or null

Transport attachments

mass_communication
boolean

Marks the message as part of a mass mailing. A message sent with this flag does not open a dialog in the chat and does not update the chat’s last_activity. Chats initiated by such messages, as well as the WebSocket events related to them, are returned only when include_mass_communication is explicitly enabled (use the include_mass_communication query parameter for REST lists and the include_mass_communication option for WebSocket connections)

Responses

Response Schema: application/json
message_id
required
integer <int64>

Unique identifier of the message

time
required
string <date-time>

Request samples

Content type
application/json
{
  • "chat_id": 123,
  • "content": "Hello!",
  • "items": [
    • {
      }
    ],
  • "note": "demo note",
  • "order": {
    • "external_id": 56,
    • "cost": {
      },
    • "date": "2021-12-29T14:18:37.051393Z",
    • "delivery": {
      },
    • "discount": {
      },
    • "items": [],
    • "number": "23546",
    • "payments": [
      ],
    • "status": {
      },
    • "url": "https://url.demo/demo-url"
    },
  • "product": {},
  • "quote_message_id": 42,
  • "scope": "user",
  • "type": "text",
  • "transport_attachments": {},
  • "mass_communication": true
}

Response samples

Content type
application/json
{
  • "message_id": 1,
  • "time": "2006-01-02T15:04:05.999999Z07:00"
}

Edit a message by ID

Updates the contents or metadata of an existing message

Authorizations:
bot_token
path Parameters
message_id
required
integer <int64> >= 1
Example: 100

Unique identifier of the message

Request Body schema: application/json

Request payload for editing an existing message

content
string <= 2000 characters

Message text content (required for text messages only)

Array of objects

File attachments (required for file, audio and image messages)

note
string

Note or description for the file (required for file, audio and image messages)

object

Order data (required for order messages only)

object

Product data (required for product messages only)

object or null

Attachments specific to a transport layer

quote_message_id
integer <int64>

ID of the quoted message (required for text messages only)

Responses

Response Schema: application/json
object

Request samples

Content type
application/json
{
  • "content": "Hello!",
  • "items": [
    • {
      }
    ],
  • "note": "demo note",
  • "order": {
    • "external_id": 56,
    • "cost": {
      },
    • "date": "2021-12-29T14:18:37.051393Z",
    • "delivery": {
      },
    • "discount": {
      },
    • "items": [],
    • "number": "23546",
    • "payments": [
      ],
    • "status": {
      },
    • "url": "https://url.demo/demo-url"
    },
  • "product": {},
  • "transport_attachments": {},
  • "quote_message_id": 42
}

Response samples

Content type
application/json
{ }

Delete a message by ID

Deletes a message with the given ID. This operation is irreversible.

Authorizations:
bot_token
path Parameters
message_id
required
integer <int64> >= 1
Example: 100

Unique identifier of the message

Responses

Response Schema: application/json
object

Response samples

Content type
application/json
{ }

WS

WebSocket connection for real-time updates

This URL is used to establish a connection via WebSocket. Using this connection, the bot can receive data for each type of event it is subscribed to. The list of events is passed as a string, with values separated by commas.

Authorizations:
bot_token
query Parameters
events
string non-empty
Example: events=message_new,message_updated,message_restored,message_deleted,dialog_opened,dialog_closed,dialog_assign,chat_created,chat_updated,chats_deleted,user_joined_chat,user_left_chat,user_updated,user_online_updated,channel_updated,customer_updated,bot_updated

Comma-separated list of events to subscribe to via WebSocket

options
string
Example: options=include_mass_communication

Additional WebSocket connection parameters (include_mass_communication — allow receiving events for messages sent via mass mailing actions)

Responses

Response samples

Content type
application/json
{ }