Instant messaging channel (imchannel)

Description

Contains the basic channel description settings.
Used by the im role when creating accounts for instant messaging with messengers. Sets strategies for servicing message sending separately and for receiving accumulated messages and distributing them across data model collections (/model/im/RemoteParties, /model/im/Messages).

Channels 'telegram', 'whatsapp', 'vk' are created and updated automatically from fixture, and are linked by codes to automatic message and event sending and receiving strategies.

Limitations

  • The collection is available in any domain, including the master domain.

  • By default, the system automatically creates the 'telegram' channel.

Fields

Entity structure
{
  "id": uuid,
  "code": str,
  "mode": str,
  "recv_strategy": str,
  "send_strategy": str,
  "opts": {
    "title": str,
    "comment": str,
    "after_read_timeout": int,
    "max_account_mps": int,
    "max_remoteparty_mps": int
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}
Table 1. Fields
Specification Description

Field: id
Mode: inout
Type: uuid
Default: generated

Identifier. Can be specified at creation, otherwise generated by the system.

Field: code
Mode: in
Type: str
Default: required

Code. Used to associate with other entities. Represents the unique channel name, for example telegram or viber.

This code is referenced by IM accounts.

Codes 'telegram', 'whatsapp', 'vk', 'max' define built-in strategies for processing incoming and sending outgoing messages and events.
Other codes imply creating custom strategies on service scripts for sending and processing incoming messages.

Field: mode
Mode: in
Type: str
Default: request

Message receiving mode. Variants:
* request – constant long-polling of the messenger. If a built-in adapter is used, it must support long-polling. Project custom adapters must define the service script with the recv_strategy property.
* webhook – system notification via webhook. If a built-in adapter is used, it must support webhook. Project custom adapters assume data delivery to the im/RemoteParties and im/Messages collections by the script of the corresponding integration channel.
* disabled – the channel is not used in processing by the platform communication layer.

Webhook mode assumes external access to the server from the messenger’s public servers.
In some cases the URL for the webhook request is registered in the bot management console (whatsapp, vk), and in others the address is reported during subscription (max).
For convenience, webhook mode automatically checks/creates an integration channel on the web server and places its path in the account each time (account.webhookInfo.url, e.g. '/api/im/v1/12341234123412341234123412341234').
The public server address and port for the webhook from messenger services should be placed next to it in the 'account.webhookInfo.host' field, or in the account option: account.options.webhookHost, e.g. 'https://my-public-domain.org:443'.

Field: recv_strategy
Mode: in
Type: date | str_empty
Default: str_empty

Name of the message receiving strategy.
If empty, the automatically generated value '%CODE%recv' is used as the strategy name, where %CODE% is the channel code.
The strategy is searched as an Erlang module 'plugin
%RECV_STRATEGY%' with an exported interface, and if absent, as a script with the specified code.
The strategy is used only in mode = request to perform a long-polling request for messages received in the account.
The associated JSON entity from the im/Accounts collection is passed as input.
When receiving messages, the strategy places them in the im/Messages collection, simultaneously creating or updating associated entities in the im/RemoteParties collection.
The tasks solved by the receive strategy include protection against duplicates and failures based on unique message identifiers in the messenger.
If the strategy fails, its call is repeated after a few seconds.

Field: send_strategy
Mode: in
Type: date | str_empty
Default: str_empty

Name of the message sending strategy.
If empty, the automatically generated value '%CODE%send' is used as the strategy name, where 'CODE' is the channel code.
The strategy is searched as an Erlang module 'plugin
%SEND_STRATEGY%' with an exported interface, and if absent, as a script with the specified code.
The strategy is used to send each individual message; associated JSON entities from the im/Accounts, im/RemoteParties, and im/Messages collections are passed as input parameters.
If the strategy fails, the sent message in the collection receives the status error and a description of the reason.

Field: opts
Mode: in
Type: object
Compound field

Field: opts.title
Mode: in
Type: str
Default: empty

Channel name

Field: opts.comment
Mode: in
Type: str
Default: empty

Arbitrary comment

Field: opts.after_read_timeout
Mode: in
Type: int
Default: 100

Timeout in milliseconds applied before the next execution of the receive strategy after control returns from the previous call.

Field: opts.max_account_mps
Mode: in
Type: int
Default: 30

Limit on the number of messages sent to the account within 1 second.

Field: opts.max_remoteparty_mps
Mode: in
Type: int
Default: 1

Limit on the number of messages sent to a specific subscriber within 1 second.

Field: opts.max_text_size
Mode: in
Type: int
Default: 4096

Limit on the text size allowed for one message sent to the messenger channel.

When attempting to send a larger message, it is softly split into parts, preferably at double or single line breaks or spaces.
Overflow parts are sent as separate messages, and information about them is saved in the im/MessageParts collection.
The message collection stores one original message with the full text.
Each sent overflow part has its own message identifier, and if a reply to it arrives, using the 'im/MessageParts' collection it is linked to the original message with the full text.

Field: opts.reactions
Mode: in
Type: str
Default: empty

List of emoji reactions allowed in the channel.
Used in the user workstation as a restriction on possible reactions, unless otherwise specified in the account options.

Field: ext
Mode: inout
Type: object
Compound field

Allows extending the compound with arbitrary keys and values

Field: ext.ct
Mode: out
Type: date
Default: generated

Object creation time

Field: ext.lwt
Mode: out
Type: date
Default: generated

Time of last modification of the object

Field: ext.fixture_version
Mode: out
Type: date

Version of the automatically created fixture. Used for updating from fixture.

Built-in and custom strategies

'telegram', 'whatsapp', 'vk', 'max' accounts are serviced by built-in strategies.

If necessary, custom strategies can be implemented on service scripts specified in the IM channel. Scripts are separate for receiving and sending messages. Channel codes must differ from the standard names of built-in strategies.
The receive script is used for long-polling requests; when messages are delivered by webhooks, processing should be implemented in the scripts of the corresponding integration channel.

The built-in 'telegram' strategy supports:

  • Creating records in the subscriber collection when messages arrive from them.

  • Creating records in the message collection when messages arrive.

  • Receiving text messages, images, audio, video, documents, stickers, locations, contacts, links, and interactive keyboard selections. Including messages consisting of a file and text.

  • Receiving events about text modification of previously sent messages.

  • Receiving replies to previous messages (with links to them).

  • Receiving 'sent', 'delivered', 'read' statuses.

  • Determining the forwarding marking of forwarded messages (flag and original author information).

  • Sending text messages, images, audio, video, documents, stickers, locations, contacts, and interactive keyboards. Including messages consisting of a file and text.

  • Sending emoji reactions to messages.

  • Receiving messages in long-polling mode (does not require the web server port to be accessible from outside).

  • Sending up to 30 messages per second, at 1 message per second per subscriber.

  • Sending messages in silent mode.

  • Sending formatted text.

  • Splitting long text into several messages according to messenger limits (4096 Unicode characters).

The built-in 'whatsapp' (whatsapp_business) strategy supports:

  • Processing the channel confirmation request (registered webhook URI).

  • Creating records in the subscriber collection when messages arrive from them.

  • Creating records in the message collection when messages arrive.

  • Modifying target URIs to the HTTP proxy server URI.

  • Receiving text messages, images, audio, video, documents, stickers, locations, contacts, and interactive keyboard selections. Including messages consisting of a file and text.

  • Receiving replies to previous messages (with links to them).

  • Receiving the read status.

  • Determining the forwarding marking of forwarded messages (flag).

  • Sending text messages, images, audio, video, documents, stickers, locations, contacts, and interactive keyboards. Including messages consisting of a file and text.

  • Sending emoji reactions to messages.

  • Sending the 'read' status.

  • Receiving messages in webhook mode (requires the web server port to be accessible from outside).

  • Splitting long text into several messages according to messenger limits (4096 Unicode characters).

The built-in 'vk' strategy supports working in a community chat:

  • Processing the channel confirmation request (registered webhook URI).

  • Creating records in the subscriber collection when messages arrive from them.

  • Creating records in the message collection when messages arrive.

  • Receiving text messages, photos, documents, stickers, locations. Including messages consisting of a file and text.

  • Splitting messages containing several files.

  • Receiving reactions to messages (converting identifiers to emoji characters).

  • Receiving replies to previous messages (with links to them).

  • Receiving the read status.

  • Sending text messages, images, documents, stickers, locations. Including messages consisting of a file and text.

  • Sending emoji reactions to messages (converting emoji characters to identifiers).

  • Sending the 'read' status.

  • Receiving messages in webhook mode (requires the web server port to be accessible from outside).

  • Splitting long text into several messages according to messenger limits (4096 Unicode characters).

The built-in 'max' strategy supports:

  • Creating records in the subscriber collection when messages arrive from them.

  • Creating records in the message collection when messages arrive.

  • Receiving text messages, images, audio, video, documents, stickers, locations, contacts. Including messages consisting of a file and text.

  • Receiving events about text modification of previously sent messages.

  • Receiving replies to previous messages (with links to them).

  • Determining the forwarding marking of forwarded messages (flag and original author information).

  • Sending text messages, images, audio, video, documents, stickers, locations, contacts, and interactive keyboards. Including messages consisting of a file and text.

  • Receiving messages both in long-polling mode (does not require the web server port to be accessible from outside) and in webhook mode (requires the web server port to be accessible from outside).

  • Sending messages in silent mode.

  • Sending formatted text.

  • Sending up to 30 messages per second, at 1 message per second per subscriber.

  • Splitting long text into several messages according to messenger limits (4000 Unicode characters).

See also

Logical roles

  • im manages message exchange with third-party messengers.