im/Accounts

Collection of IM (Instant Messaging) accounts. The collection is created and used by the 'im' microservice.

Accounts are created bound to an instant messaging channel that sets common processing scripts.

Storage type: category.

Table 1. Class fields
Field Description

id

Identifier.

name

Account name.

channel

Instant messaging channel type. The value corresponds to the code of an existing im channel.

Accounts telegram, whatsapp, vk, max are served by built-in strategies.

For an account of type 'whatsapp', 'vk', or 'max' in webhook mode to work, an integration channel of type 'im' must be created with exactly the same identifier as this im account. A channel of another type or with scripts and rights is converted by the system to type 'im' (the token is preserved); a deleted one is recreated; a channel with another code is not used or modified. Webhooks with incoming messages from the messenger arrive at the web server page '/api/im/v1/:TOKEN', and from there, by the identifier of the integration channel whose token is specified in the webhook URL, reach the im account servicing service.

For convenience, when creating a 'whatsapp', 'vk', or 'max' account, a messenger channel /rest/v1/uc/imchannels and an integration channel /rest/v1/service/integration_points are created automatically. The information useful for webhook registration is automatically placed in the 'webhookInfo' field.

enabled

Account switch.

options

Additional arbitrary account options by channel types.

For Telegram:

  • token - required. When registering a bot via @BotFather, the token is reported as the result.

  • disable_notification (true | false) - optional. Silent message delivery mode switch. Default 'false' - deliver with notification.

  • parse_mode ('none' | 'markDown' | 'HTML') - optional. Message formatting mode selector. Default 'none'.

  • proxyUrl - optional. Allows routing requests to the messenger to an http proxy server. Either by shifting the entire URL one page level (for example, if the value is https://proxy.com/, then instead of 'https://api.telegram.org/bot…​' the call is sent to 'http://proxy.com/api.telegram.org/bot…​'. The system makes requests to 'https://api.telegram.org/bot…​' and 'https://api.telegram.org/file/bot…​', so routes for these domain addresses must be configured on the proxy server). Or a regular expression according to modifier rules, formats: '/reg/Pattern/Replacement' or '/reg/Pattern/Replacement/Opts' or '/reg{<SEPARATOR>}/Pattern<SEPARATOR>Replacement<SEPARATOR>Opts'.

For Whatsapp business:

  • token - required. Token provided by the provider service when registering the webhook. Used to send any requests to messenger servers.

  • phoneNumberId - required. Account phone number substituted into all outgoing message sending requests.

  • proxyUrl - optional. Allows routing requests to the messenger to an http proxy server. Either by shifting the entire URL one page level (for example, if the value is http://proxy.com/, then instead of 'https://graph.facebook.com/v20.0/…​' the call is sent to 'http://proxy.com/graph.facebook.com/v20.0/…​'. The system makes requests to 'https://graph.facebook.com/' and 'https://lookaside.fbsbx.com/', so routes for these domain addresses must be configured on the proxy server). Or a regular expression according to modifier rules, formats: '/reg/Pattern/Replacement' or '/reg/Pattern/Replacement/Opts' or '/reg{<SEPARATOR>}/Pattern<SEPARATOR>Replacement<SEPARATOR>Opts'

  • fixTo - optional. Allows applying a regular expression to replace the subscriber phone number when sending messages. Thus, if /reg/^79/789 is specified, then instead of 79991234567 the message will contain 789991234567.

For VK:

  • token - required. Token provided by the provider service when creating an access key in VK. Used to send any requests to messenger servers.

  • server_secret - required. String that the server must return when confirming the address for the webhook. Provided on the 'Callback API' tab when configuring a VK community in the 'Working with API' section.

  • client_secret - required. Secret key set on the 'Callback API' tab when configuring a VK community in the 'Working with API' section.

  • groupId - optional. Group identifier. Not used by the system.

For MAX:

  • token - required. Token provided by the provider service when creating an access key in VK. Used to send any requests to messenger servers.

  • secret - optional. Secret key reported to the messenger server when subscribing to new message notifications and sent in each notification. Applies in 'webhook' mode over https. If the field is not set, the account.webhookInfo.verifyToken value acts as the secret.

  • disable_link_preview - optional. Switch for the messenger server preparing previews for links in sent messages.

  • notify ('true' | 'false') - optional. Silent message delivery mode switch. Default 'true' - deliver with notification.

  • format ('none' | 'markdown' | 'html') - optional. Message formatting mode selector. Default 'none'.

  • webhookHost - optional, for channel mode mode='webhook'. The webhook mode in the messenger requires subscription with the URL for the webhook request. The path is automatically placed in the webhookInfo.url field, and this field must contain the host part of the URL for the webhook request, for example 'https://my-public-domain.org:443'.

  • proxyUrl - optional. Allows routing requests to the messenger to an http proxy server or substituting the main address in the URL. Either by shifting the entire URL one page level (for example, if the value is http://proxy.com/, then instead of 'https://platform-api2.max.ru/…​' the call is sent to 'http://proxy.com/platform-api2.max.ru/…​'. Thus routes for these domain addresses must be configured on the proxy server). Or a regular expression according to modifier rules, formats: '/reg/Pattern/Replacement' or '/reg/Pattern/Replacement/Opts' or '/reg{<SEPARATOR>}/Pattern<SEPARATOR>Replacement<SEPARATOR>Opts'

Secret (token, secret, client_secret, server_secret): on reading — ciphertext; the plain value is not exposed via the API, decrypted by the service when used (Encryption and keys).

statusText

Status message. Populated by the system when failures are detected in interaction scripts.

isSystem

System platform account (for example, the administrator bot, administrator bot). Product services do not use such accounts. Default false.

webhookInfo

Field into which the system automatically enters data for registration on the provider side: the webhook page and verification token.

  • url - path to the endpoint for the webhook request from the messenger service side. Populated automatically and regularly, placing here the token of the bound integration channel of type 'im' (a new one when the token is reissued). A manually written value is replaced. The token is accepted only by this endpoint; to protect against forged webhooks, set provider secrets (client_secret for vk, secret for max).

  • verifyToken - optional. Automatically places the account Id here, used as the default secret key if one is not explicitly set in the account options.

  • host - optional. Can be filled by the administrator as an alternative to options.webhookHost for the MAX messenger channel.

Example value
{
  "url": "/api/im/v1/0123456789abcdef0123456789abcdef",

  "verifyToken": "d4012683-0191-a406-c746-7cd30a921f58"
}

When registering the system to receive webhooks, the scheme and host name by which the server is accessible must be appended to the provided page. For example, 'https://my-public-domain.org:443', so that it becomes 'https://my-public-domain.org:443/api/im/v1/…​'.