search string side menu

Live chats > Connect messengers to a live chat > Arbitrary messengers / Set up interaction requests in an arbitrary messenger

Set up interaction requests in an arbitrary messenger

General information

The naming, method types, and JSON response structure are developed in accordance with the accepted ELMA365 standards and cannot be altered by the client.

The base URLs and tokens for system interaction are specified in the messenger settings.

The logic of how an operator works with client sessions is implemented within the standard logic of live chats. It is the same for custom messengers as for other messengers, and using arbitrary messengers doesn’t provide additional functionality.

Messenger setup

Connecting an arbitrary messenger to a live chat is done similarly to other available messengers. For more details, refer to the section Connect messengers to a live chat.

Here is a list of settings that should be present in the arbitrary messenger for its connection to a live chat:

  • Channel name for communication with the messenger of type [string]. It doesn’t affect the interaction with the messenger. It serves as additional information and is displayed in the list of connected channels for the administrator and in the session for the operator.
  • Access token to the third-party messenger’s API (confirmation string) of type [string]. It’s filled in when creating a channel for communication with the messenger. It will be sent with every message from the ELMA365 system to the messenger. It can be empty.
  • Messenger’s API URL of type [string] is the URL (webhook) to which messages from the ELMA365 system will be sent.

API

Below are methods for the custom messenger’s interaction with ELMA365.

All methods must return the following values:

  • 200 OK.
  • 401 Unauthorized. This is returned if the token doesn’t match.
  • 404 Not Found. This is returned if the channel doesn’t exist.
  • 500 Internal Server Error. This is returned in case of an unexpected server error.

All methods have an unchangeable prefix. It is the base URL set by the installation settings of ELMA365 and the company.

ELMA365 methods for interaction with the messenger (ELMA365 —> Messenger)

Messenger connection request (POST Connect)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

Parameters for the request:

  • token. Token generated on the messenger’s side.
  • channelId. ID of the channel in the ELMA365 system.
  • data.webhook. Webhook for sending requests to the ELMA365 system.

Sample request body:

{
    "type": "connect",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
    "data": {
        "webhook": "https://my-domain.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30"
    }
}

Method to send a message to the messenger (POST Send Message)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

Parameters for the request:

  • token. Token generated on the messenger’s side.
  • channelId. ID of the channel in the ELMA365 system.
  • data.targetChatId. Chat ID in the messenger.
  • data.text. Message text.
  • data.files. Array of attachments.

Sample request body:

{
    "type": "message",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30",
    "data": {
        "targetChatId": "chat1",
        "text": "text",
        "files": [
            {
                "name": "file1.png",
                "size": 12345,
                "URL": "https://elma365.com/en/img/about/photo-staff.png"
            }
        ]
    }
}

Method to request a delivery notification (POST Send Message Outcome)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

If the message is successfully processed, then success will evaluate to true. If success = false or no response follows, retry sending the message with the specified messageId.

Sample request body:

{
    "type": "messageOutcome",
    "token": "confirm",
    "data": {
        "success": true,
        "messageId": "message1"
    }
}

Method to request user data (POST Get User Info)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

Parameters for the request:

  • token. Token generated on the messenger’s side.
  • channelId. ID of the channel in the ELMA365 system.
  • data.userId. User ID in the messenger.

Response:

  • Avatar. File in the base64 format.

Sample request body:

{
    "type": "userInfo",
    "token": "confirm",
    "data": {
        "userId": "user1"
    }
}

Method to request a read receipt for a message (POST Mark Message As Read)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

Sample request body:

{
    "type": "markAsRead",
    "token": "confirm",
    "data": {
        "messageId": "message1"
    }
}

Method to send a messenger disconnect notification (POST Disconnect)

Request URL:

https://my-domain.com/api/messengers/external/test/webhook

Sample request body:

{
    "type": "disconnect",
    "token": "confirm",
    "channelId": "ebf45efc-cc67-4b60-9e3f-121966ba9f30"
}

Methods for Messenger Interaction with ELMA365 (Messenger —> ELMA365)

Method for sending a message to ELMA365 (POST Send Message)

Request URL:

https://my-domain.com/api/messengers/external/other/webhook/8ec8228f-7ff2-462b-a8d7-4f9b3f62c253

Parameters for the request:

  • token. Token formed on the messenger side.
  • data.externalMessageId. Message ID in the messenger.
  • data.externalChatId. Chat ID in the messenger.
  • data.externalUserId. User ID in the messenger.
  • data.text. Message text.
  • data.files. Array of attachments.

Sample request body:

{
    "type": "message",
    "token": "confirm2",
    "data": {
        "externalMessageId": "message63",
        "externalChatId": "chat12",
        "externalChatName": "Chat name: chat 12",
        "externalUserId": "user12",
        "text": "text test",
        "files": [
            {
                "name": "file1.png",
                "URL": "https://elma365.com/en/img/about/photo-staff.png"
            }
        ]
    }
}

Method to send a notification about a disconnect initiated by the messenger (POST Disconnect)

Request string:

https://my-domain.com/api/messengers/external/other/webhook/ebf45efc-cc67-4b60-9e3f-121966ba9f30

Sample request body:

{
    "type": "disconnect",
    "token": "confirm"
}

Method to request user data (POST Get User Info)

Request string:

https://my-domain.com/api/messengers/external/other/webhook/c5f9889f-0fcc-4112-a8bd-d1a93cd5ab53

Sample request body:

{
    "type": "userInfo",
    "token": "confirm",
    "data": {
        "userId": "95806fe5-f8e8-460c-b2be-ce607068726c"
    }
}

Interaction requests

All requests are sent to the messenger’s webhook (API URL of the messenger) and contain the following information:

  • Messenger token.
  • Request type.
  • Request data.

All requests should receive the 200 response, indicating successful execution.

Request types for ELMA365 interaction with a messenger (ELMA365 → Messenger):

  • Connect. Request to create a connection. Always used when creating a new channel in the ELMA365 system. It serves to meet the external messenger’s data preparation needs. If you do not require data preparation, return code 200.
  • Message. Request to send a message to the client from the operator.
  • UserInfo. Request to get user data: full name, login (unique identifier), phone number, avatar, etc.
  • MarkMessageAsRead. Request to mark a message as read in an external messenger.
  • Disconnect. Notification request about terminating interaction with the messenger.

Request types for messenger Interaction with ELMA365 (Messenger → ELMA365):

  • Message. Request to send a message to the operator from the client.
  • Disconnect. Notification request about terminating interaction initiated by the messenger.
custom-messenger.html inbox.html

Found a typo? Highlight the text, press ctrl + enter and notify us