Integration channels (integration_points)
Requests
| HTTP verb | Endpoint | Description |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Creating a new integration channel
Request
Field description: integration_point entity
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
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
| Name | Type | Description |
|---|---|---|
|
|
Filter by field values. |
|
|
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 in the list of resources to output. |
|
|
Maximum number of resources in the list. |
|
|
Sorting order of resources in the list. |
|
|
Transformation of composite fields to flat form. |
GET /rest/v1/service/integration_points?offset=0&limit=2 HTTP/1.1
Response
Field description: integration_point entity
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
| Name | Type | Description |
|---|---|---|
|
|
List of fields to output. |
|
|
Transformation of composite fields to flat form. |
GET /rest/v1/service/integration_points/a188288e-016c-d86f-cd99-50e54938780c HTTP/1.1
Response
Field description: integration_point entity
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
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
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
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
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 layerproduct_layer,service_era_meet: their reissue restarts microservices — only explicitly byids); if there are more than 20 channels — error 422, reissue in parts byids.
{"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).