Skip to Content

30.5.4. Webhooks

<< Prev   Next >>

30.5.4.1. Using webhooks

As mentioned earlier, if you use webhooks, integration is one-way. Messages are sent from the external system to the collaboration system, and then to the application.

The user who will represent the system that sends messages to the application will be called an integration user. So that the external system can use a webhook, it must be provided with the endpoint URL. To get it, use the CollaborationSystemIntegration.EndpointURL() method. Use this address when you set up the system that will send messages.

Once a message from the external system gets to the endpoint, perform the following actions:

  • Parse the message body.
  • Create an integration user if there is no created one.

    The integration user name is:

    • Username passed in the createUser message.
    • Integration instance name if no user (message author) is specified in the external system message.
  • Create a collaboration system conversation if there is no created one.
    • Conversation participants are:
      • Integration user.
      • Users that were specified as default participants upon integration setup.
    • If you want messages to get into a pre-created conversation with the selected participants, you need to:
      • Pre-create a conversation using 1C:Enterprise language.
      • Pass the created conversation ID to an external system so that this system uses this ID in its messages. To get a string presentation of the conversation ID, use the String() function whose parameter is an object of the CollaborationSystemConversation.ID type.
  • Message whose author is an integration user is added to the conversation. This message depends on the external system message.

30.5.4.2. Supported commands

30.5.4.2.1. General information

The command is a POST request of an external system. The request must meet the following requirements:

  • Request body is generated in UFT-8 without BOM.
  • Request body is a JSON document.
  • Request body generally looks as follows:
{
"command" : {
"param1": value1,
…
"paramN": valueN
}
}

If the command allows HTML text, the following formatting options are supported:

  • Supported elements: a, b, big, font, i, li, ol, s, small, span, strike, strong, u, and ul.
  • style element attribute: background-color, color, font-family, font-size, font-style, font-weight, or text-decoration.

The command result is displayed as a return code:

  • 200 OK. Command is completed successfully.
  • 404 No active integration. Integration is not found or not active.
  • 409 Conflict. When you call the create… command for an already existing object.
  • 500 <Error text>. Error occurred when processing the command.

For more information about the command formats, see below.

30.5.4.2.2. createConversation

Description:

Creates a new conversation.

Syntax:

{
"createConversation": {
"extConversationId": "1",
"title": "Conversation title",
"extUserId": "1",
"members": [
"1"
]
}
}

Parameters:

  • extConversationId. External ID of the conversation to be created.
  • title. Title of the conversation to be created (as a string).
  • extUserId. External ID of the user on whose behalf the conversation is created.

    If not specified, a collaboration system user will be created. The user's name will be the same as the integration name, and the user will be added to the conversation. In this case, all requests related to this conversation must not include the extUserId, members, addMembers, and removeMembers parameters.

    Optional parameter.

  • members. Array of external IDs of users who are conversation participants from the external system.

    Optional parameter.

30.5.4.2.3. createMessage

Description:

Creates a new message in the conversation.

Syntax:

{
"createMessage": {
"extId": "1",
"text": "Message text",
"textFormat": "text/plain",
"extUserId": "1",
"extConversationId": "1"
}
}

Parameters:

  • extId. External ID of the message to be created.
  • text. Message text.
  • textFormat. Message text format. Possible values are text/plain and text/html.

    Optional parameter. The default value is text/plain.

  • extUserId. External ID of the message author.

    If not specified, a collaboration system user will be created. The user's name will be the same as the integration name, and the user will be added to the conversation. In this case, all requests related to this conversation must not include the extUserId, members, addMembers, and removeMembers parameters.

    Optional parameter.

  • extConversationId. External ID of the conversation where the message is being created.
30.5.4.2.4. createUser

Description:

Creates an integration user in the collaboration system.

Syntax:

{
"createUser" : {
"extUserId": ,
"name": ,
"fullName": ,
"picture":
}
}

Parameters:

  • extUserId. External ID of an external user.
  • name. Short name of an external user (as a string).
  • fullName. Full name of an external user (as a string). Optional parameter.
  • picture. User picture as a string in base64 format. Optional parameter.
30.5.4.2.5. updateConversation

Description:

Changes the conversation parameters. Use it to change the conversation title, and add or delete conversation users.

Syntax:

{
"updateConversation": {
"extConversationId": "1",
"title": "New conversation title",
"extUserId": "5",
"addMembers": [
"5"
],
"removeMembers": [
"1"
]
}
}

Parameters:

  • extConversationId. External ID of the conversation being changed.
  • title. Conversation title.

    Optional parameter.

  • extUserId. External ID of the user on whose behalf the conversation is being changed.

    If not specified, a collaboration system user will be created. The user's name will be the same as the integration name, and the user will be added to the conversation. In this case, all requests related to this conversation must not include the extUserId, members, addMembers, and removeMembers parameters.

    Optional user.

  • addMembers. Array of external IDs of users to be added to the conversation participants.

    Optional parameter.

  • removeMembers. Array of external IDs of users to be removed from the conversation participants.

    Optional parameter.

30.5.4.2.6. updateMessage

Description:

Updates an existing message.

Syntax:

{
"updateMessage": {
"extId": "1",
"text": "Message text",
"textFormat": "text/plain",
"extUserId": "1",
"extConversationId": "1"
}
}

Parameters:

  • extId. External ID of the message being changed.
  • text. Message text.
  • textFormat. Message text format. Possible values are text/plain and text/html.

    Optional parameter. The default value is text/plain.

  • extUserId. External ID of the message author.

    If not specified, a collaboration system user will be created. The user's name will be the same as the integration name, and the user will be added to the conversation. In this case, all requests related to this conversation must not include the extUserId, members, addMembers, and removeMembers parameters.

    Optional parameter.

  • extConversationId. External ID of the conversation where the message is being changed.
30.5.4.2.7. updateUser

Description:

Updates the parameters of an integration user in the collaboration system.

Syntax:

{
"updateUser" : {
"extUserId": ,
"name": ,
"fullName": ,
"picture":
}
}

Parameters:

  • extUserId. External ID of an external user.
  • name. New short name of an external user (as a string). Optional parameter.
  • fullName. New full name of an external user (as a string). Optional parameter.
  • picture. New user picture as a string in base64 format. Optional parameter.

<< Prev   Next >>

Icon/Social/001 Icon/Social/006 Icon/Social/005 Icon/Social/004 Icon/Social/002