Integration channel (integration_point)

Description

The integration channel basically defines a point for handling HTTP(s) webhooks coming from external systems, as well as a point for websocket connections with predefined permissions.
In some cases, the integration channel defines the URL of the external system to send HTTP requests to it from the scripts.

Supports streaming asynchronous processing of messages coming from websocket connections and sending response messages and events to them.

Supports the creation of project APIs using service scripts.

Websocket-connection to the integration channel is made by specifying token_local directly in the URL or in the Authorization header. Read more.

Http(s)-connection to the integration channel is made with token_local. Used for accessing project API, and for downloading call recordings.

Limitations

  • The collection is available in any domain.

  • Licensed by a quantitative parameter: a license per channel type is consumed.

Fields

Entity structure
{
  "id": uuid,
  "code": str,
  "type": str,
  "token_local": str,
  "token_remote": str,
  "token_remote2": str,
  "url": str,
  "recv_svcscriptcode": str,
  "send_svcscriptcode": str,
  "recv_svcscriptcode_ws": str,
  "send_svcscriptcode_ws": str,
  "opts": {
    "allow_files_api": bool,
    "comment": str,
    "issync": bool,
    "recv_timeout": int,
    "roles": ["special01"],
    "userid": "37a85e8-1a01-835f-4490-e78015a20052",
    "title": str
  },
  "ext": {
    "ct": date,
    "lwt": date
  }
}

Description of the specification’s characteristics

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 and script components.

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

Integration Channel Type.
The number of integration channels of each type is limited by the license.

Field: token_local
Mode: out
Type: str
Default: generated

Local token.
Used when HTTP webhooks and Websocket connections are received from external systems to the platform’s web servers for the purpose of authorization and detection of the associated integration channel.
Unique across all domains.
Not subject to modification.

Field: token_remote
Mode: in
Type: str
Default: empty

External token.
Used in bound scenarios to build queries to an external system.

Field: token_remote2
Mode: in
Type: str
Default: empty

Optional external token.
Can be used in bound scenarios to build queries to an external system.

Field: remoteipmask
Mode: in
Type: str
Default: "0.0.0.0.0/0"

The mask of the IP address of the request sender for which API access is allowed through this token.
IP address values can be:

  • IP-address (e.g. '192.168.0.10');

  • Subnet mask (e.g. '192.168.0.0/24');

  • IP address range (e.g. '172.25.0.50+10')

Field: recv_svcscriptcode
Mode: in
Type: str
Default: empty | required

The code of the service script that is run to process an incoming HTTP request using token_local.
Mandatory field for type = public.

Enables the realization of project API.

Endpoint to refer to the script: /api/token/v1/:TOKEN_LOCAL
Depending on the value of the opts.issync field, the script is executed synchronously or asynchronously. The opts.recv_timeout field specifies the maximum time to wait for the script to execute in seconds.

The following parameters are passed to the service script as input (available in expressions using the method startparam(N)):

  1. JSON representation of the entity of the integration channel through which the request was received.

  2. Method (GET, POST, …​).

  3. The full URL (e.g, http://172.27.1.112/api/token/v1/12341234-1234-1234-1234-123412341234?s=1).

  4. The contents of the request body.

  5. All query headers are in string form.

  6. IP-forwarding address.

  7. Scheme (http, https, …​)

The service script created local string variables whose values define the HTTP response:

  • response_code - response code (e.g. 200, 404, …​)

  • response_headers - JSON-object with specific headers for the response. For example, {"X-Era-Test1": "bbb", "content-type": "application/json"}.

  • response_content - the body of the answer. For example, {"a": 1, "b": "asdf"}.

The format of the body can be arbitrary and is defined by the header Content-Type.

Field: send_svcscriptcode
Mode: in
Type: str
Default: empty

Code of the service script run to send an HTTP request to the channel from the chatbot scripts

Field: recv_svcscriptcode_ws
Mode: in
Type: str
Default: empty

The code of the service script to be run to process an incoming websocket message using the token_local.

Enables the realization of project API.

As part of the websocket connection to tokenize a method to invoke the script API: ["message", {"qid": …​, "data": …​, …​}].
Depending on the value of the opts.issync field, the script is executed synchronously or asynchronously. The opts.recv_timeout field specifies the maximum time to wait for the script to execute in seconds.

The following parameters are passed to the service script as input (available in expressions using the method startparam(N)):

  1. JSON representation of the entity of the integration channel through which the request was received.

  2. Method from websocket message: "message".

  3. The full URL of the websocket connection (for example, http://172.27.1.112/ws/token/v1).

  4. Message body content from the field 'data'.

  5. The identifier of the websocket connection.

  6. IP-forwarding address.

  7. Scheme: websocket.

The service script created local string variables whose values define the HTTP response:

  • response_content - the content of the response, placed in the response message in the 'data' field. For example, {"a": 1, "b": "asdf"}. The format can be arbitrary. A JSON object or list is sent as a response without additional escape formatting.

Response Message Format:
[
  "message_result",
  {
    "qid": ...,
    "success": true,
    "data": ...
  }
]

Field: send_svcscriptcode_ws
Mode: in
Type: str
Default: empty

Code of the service script run to send a websocket message to the channel from the chatbot scripts

Field: url
Mode: in
Type: str
Default: empty

Data Provider URL. Used when constructing full URLs in the "Webquery" component of "Webquery" scripts. Relevant for domains with solenoid types that exclude the possibility of specifying full URLs in the "Webquery" component properties"__.

Field: opts
Mode: in
Type: object
Composite field

Field: opts.allow_files_api
Mode: in
Type: bool
Default: false

Authorization to work with files. Available only for type=public

Field: opts.filter_capabilities
Mode: in
Type: array
Default: empty

Allow websocket connections to work with specific Websocket Token-APIs. You can list specific ones, or allow for all by specifying ["*"]. Always allowed by default capability subscribe.

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

Arbitrary comment

Field: opts.issync
Mode: in
Type: bool
Default: false

Switch on synchronous script startup mode, true - wait for a response from a script

Field: opts.recv_timeout
Mode: in
Type: int
Default: 0

Maximum recv_svcscript execution time in seconds. 0 means that the value defined by the web server (10 seconds) will be applied. The maximum allowed value is 60 sec.

Field: opts.roles
Mode: in
Type: array
Default: empty

Defines the composition of roles for authorization through the service IAM

Field: opts.userid
Mode: in
Type: uuid
Default: empty

Identifier of the system user on whose behalf the queries are executed. The roles of this user are also applied.

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

Arbitrary header

Field: ext
Mode: inout
Type: object
Compound field

Allows you to extend 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

Types of integration channel

Table 2. Types of integration channel
Value Description

"public"

General purpose integration channel. Used in:

  • sending HTTP requests from scripts in solutions that have restrictions on URL selection in the "Web-request" component. The final URL is calculated by concatenating the value of the url field of the selected integration channel, the / symbol and the specified page.

  • receiving incoming HTTP requests from arbitrary senders using token_local. In this case the recv_svcscriptcode script is launched. In particular when receiving messages for chat sessions.

  • creating its own internal API in service scripts on HTTP and websocket protocols. The values of recv_svcscriptcode, recv_svcscriptcode_ws, url and token_local fields are applied, as well as the "Sending websocket message" component".

  • sending messages from chatbot scripts to the channel. Fields apply send_svcscriptcode, send_svcscriptcode_ws.

"subscr"

Integration channel for subscribers to system events.
Supports subscription via HTTP and Websocket.
In the first case, events are sent by webhooks to the address specified in the subscription request, or to the url.
In the second case, events are sent back to the websocket connection.

To each integration channel, regardless of the number of connections and subscriptions, each event is sent no more than 1 time.

The recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode, and send_svcscriptcode_ws fields are not used.

Other

Defined by the domain soluuon. The composition of other types of integration channels and service scripts are contained in the solusenet assemblies.

The nature of operation is similar to the "public" channel, but the values of the url, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode and send_svcscriptcode_ws fields are not used. Instead, the values specified in the solenoid metadata are used.

See also

API

Logical roles

  • ws maintains websocket connections and accepts HTTP webhooks.

  • svc Processes service scripts, including sending HTTP requests by the "Web-request" component".

  • Personalization
  • Increase font size
  • Decrease font size