Integration channels (integration_points)

Requests

HTTP verb Endpoint Description

POST

/rest/v1/service/integration_points

Creating a new integration channel

GET

/rest/v1/service/integration_points

Getting the list of integration channels

GET

/rest/v1/service/integration_points/<id>

Getting integration channel data

PATCH

/rest/v1/service/integration_points/<id>

Modifying integration channel data

DELETE

/rest/v1/service/integration_points/<id>

Deleting an integration channel

LOOKUP

/rest/v1/service/integration_points

Searching for an integration channel identifier


Creating a new integration channel

Request

Field description: integration_point entity

Example request
POST /rest/v1/service/integration_points HTTP/1.1
Content-Type: application/json; charset=utf-8

integration_point entity

Response

Field description: integration_point entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b4680fbe-016c-d86f-1d6b-50e54938780c",
  "code": "ABCDE",
  "type": "public",
  "token_local": "3f2a07c1d9e84b6a5c0e1f27a9d3e91c", "token_state": "v2",
  "token_remote": "",
  "token_remote2": "",
  "url": "http://trapper.com",
  "recv_svcscriptcode": "ws_hook",
  "recv_svcscriptcode_ws": "",
  "send_svcscriptcode": "send_to_web",
  "send_svcscriptcode_ws": "",
  "opts": {
    "title": "",
    "comment": "",
    "allow_files_api": false,
    "issync": false
  },
  "ext": {
    "ct": "2019-08-28T13:34:16.42Z",
    "lwt": "2019-08-28T13:34:16.42Z"
  }
}

Getting the list of integration channels

Request

Table 1. Request parameters
Name Type Description

filter

object

Filter by field values.

mask

str

List of fields to output. Available fields for output: id, code, type, token_local, token_state, token_remote, token_remote2, recv_svcscriptcode, recv_svcscriptcode_ws, send_svcscriptcode, send_svcscriptcode_ws, opts.title, opts.allow_files_api, opts.allow_modify, opts.issync, ext.lwt, ext.ct.

offset

int

Offset in the list of resources to output.

limit

int

Maximum number of resources in the list.

order

array<object|str>

Sorting order of resources in the list.

flat

bool

Transformation of composite fields to flat form.

Example request
GET /rest/v1/service/integration_points?offset=0&limit=2 HTTP/1.1

Response

Field description: integration_point entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
  {
    "id": "b4680fbe-016c-d86f-1d6b-50e54938780c",
    "code": "ABCDE",
    "type": "public",
    "token_local": "ha_v=5;0a1b2c3d4e5f6071.Qm9vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xl", "token_state": "v2",
    "token_remote": "",
    "token_remote2": "",
    "url": "http://trapper.com",
    "recv_svcscriptcode": "ws_hook",
    "recv_svcscriptcode_ws": "",
    "send_svcscriptcode": "send_to_web",
    "send_svcscriptcode_ws": "",
    "opts": {
      "title": "",
      "allow_files_api": false,
      "issync": false
    },
    "ext": {
      "ct": "2019-08-28T13:34:16.42Z",
      "lwt": "2019-08-28T13:34:16.42Z"
    }
  },
  {
    "id": "a188288e-016c-d86f-cd99-50e54938780c",
    "code": "902",
    "type": "telegram",
    "token_local": "ha_v=5;0a1b2c3d4e5f6071.Qm9vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xl", "token_state": "v2",
    "token_remote": "",
    "token_remote2": "",
    "url": "http://trapper.com",
    "recv_svcscriptcode": "ws_hook",
    "recv_svcscriptcode_ws": "",
    "send_svcscriptcode": "send_to_web",
    "send_svcscriptcode_ws": "",
    "opts": {
      "title": "",
      "allow_files_api": false,
      "issync": false
    },
    "ext": {
      "ct": "2019-08-28T13:34:16.42Z",
      "lwt": "2019-08-28T13:34:16.42Z"
    },
    "ext": {
      "ct": "2019-08-28T13:35:01.52Z",
      "lwt": "2019-08-28T13:35:01.52Z"
    }
  }
]

Getting integration channel data

Request

Table 2. Request parameters
Name Type Description

mask

str

List of fields to output.

flat

bool

Transformation of composite fields to flat form.

Example request
GET /rest/v1/service/integration_points/a188288e-016c-d86f-cd99-50e54938780c HTTP/1.1

Response

Field description: integration_point entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b4680fbe-016c-d86f-1d6b-50e54938780c",
  "code": "ABCDE",
  "type": "public",
  "token_local": "ha_v=5;0a1b2c3d4e5f6071.Qm9vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xl", "token_state": "v2",
  "token_remote": "",
  "token_remote2": "",
  "url": "http://trapper.com",
  "recv_svcscriptcode": "ws_hook",
  "recv_svcscriptcode_ws": "",
  "send_svcscriptcode": "send_to_web",
  "send_svcscriptcode_ws": "",
  "opts": {
    "title": "",
    "comment": "",
    "allow_files_api": false,
    "issync": false
  },
  "ext": {
    "ct": "2019-08-28T13:34:16.42Z",
    "lwt": "2019-08-28T13:34:16.42Z"
  }
}

Modifying integration channel data

Fields prohibited for modification: id, token_local (except `+*****+`, the mask with the current token fingerprint `*****#<8 hex>`, and the encrypted token of this channel)

Request

Field description: integration_point entity

Example request
PATCH /rest/v1/service/integration_points/b4680fbe-016c-d86f-1d6b-50e54938780c HTTP/1.1
Content-Type: application/json; charset=utf-8

integration_point entity

Response

Field description: integration_point entity

Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  "id": "b4680fbe-016c-d86f-1d6b-50e54938780c",
  "code": "ABCDE",
  "type": "public",
  "token_local": "ha_v=5;0a1b2c3d4e5f6071.Qm9vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xlZ29vZ2xl", "token_state": "v2",
  "token_remote": "00ea293c29f9dc30",
  "token_remote2": "",
  "url": "http://trapper.com",
  "recv_svcscriptcode": "ws_hook",
  "recv_svcscriptcode_ws": "",
  "send_svcscriptcode": "send_to_web",
  "send_svcscriptcode_ws": "",
  "opts": {
    "title": "",
    "comment": "",
    "allow_files_api": false,
    "issync": false
  },
  "ext": {
    "ct": "2019-08-28T13:34:16.42Z",
    "lwt": "2019-09-10T12:49:25.17Z"
  }
}

Deleting an integration channel

Request

Example request
DELETE /rest/v1/service/integration_points/b4680fbe-016c-d86f-1d6b-50e54938780c HTTP/1.1

Response

Example response
HTTP/1.1 204 No Content

Searching for an integration channel identifier

Searches for a resource by the specified key and returns the identifier(s) for building the endpoint.

Key fields for search: id, code

Request

Example request
LOOKUP /rest/v1/service/integration_points HTTP/1.1
Content-Type: application/json; charset=utf-8

"ABCDE"

Response

Example successful response
HTTP/1.1 200 OK
content-type: application/json; charset=utf-8

[
  "b4680fbe-016c-d86f-1d6b-50e54938780c"
]
Example failed response
HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "error_code": 1404,
  "error_message": "Lookup failed"
}

Token reissue

POST /rest/v1/service/integration_points/<id>/token — a new channel token. User session only (request via integration channel token — 403); rights are the same as for modifying the channel.

Response — the token in plaintext, once:

{"id": "b4680fbe-016c-d86f-1d6b-50e54938780c", "token_local": "3f2a...e91c"}

The previous token stops working immediately on the site web servers (on other sites — after synchronization, up to 30 seconds); WebSocket connections using it are closed. External systems, scripts, and settings using the token (for example, survival_options) must be reconfigured. Product layer microservices receive the new token via the %TOKEN%, %TOKENFILE% macros on restart.

Bulk token reissue

POST /rest/v1/service/integration_points/token — reissues tokens of several domain channels, for example after a compromise. Administrator only (admin role) and user session only (request via integration channel token or without the admin role — 403).

The body is one of the keys:

  • ids — list of channel identifiers (no more than 20);

  • all: true — all domain channels except service channels with permanent identifiers (product layer product_layer, service_era_meet: their reissue restarts microservices — only explicitly by ids); if there are more than 20 channels — error 422, reissue in parts by ids.

{"ids": ["b4680fbe-016c-d86f-1d6b-50e54938780c", "4c1d3a52-0193-7e1b-9a0d-5f2e8c6b1a07"]}

Each channel is reissued in the same way as with a single request (the previous token stops working, WebSocket connections using it are closed). The response is a list in request order: the new token in plaintext (once) or an error text for a channel that could not be reissued:

[
  {"id": "b4680fbe-016c-d86f-1d6b-50e54938780c", "code": "crm", "token": "3f2a...e91c"},
  {"id": "4c1d3a52-0193-7e1b-9a0d-5f2e8c6b1a07", "code": null, "error": "Integration point is not found"}
]
Channels are reissued one by one. If no response is received (connection break, client timeout), tokens of already processed channels are revoked and the new ones are lost — such channels must be reissued again. The "Result is unknown" error for a channel means the domain center did not respond: the token may have been reissued, check the channel or reissue it again; the remaining channels of the request are not processed after that ("Not requested").

After reissue, tokens of vk and whatsapp IM account channels must be re-entered in the webhook address in the provider dashboard. The number of reissued tokens is written to the journal (without tokens).