Alterdesk Gateway Specifications

This documentation contains Alterdesk Gateway specifications to take in consideration when implementing the API in your system.

Connection

The gateway is a WebSocket server located at wss://api.alterdesk.com/v1/gateway

Rate Limiting

Clients are rate limited per access token. Clients surpassing these limits will receive an error and are immediately disconnected.

Sending Events

Clients connected are limited to 250 events every 60 seconds.

Sending Messages

Clients connected are limited to 100 messages every 60 seconds.

Authentication

The authentication handshake needs to be send within 10 seconds of connecting to the Gateway. The token variable is the OAuth 2.0 token that is also used for the REST API.

          {
            "event": "handshake",
            "data": {
              "token": "generated-access-token",
              "properties": {
                "os": "Operating System Name",
                "browser": "Library Name",
                "device": "Library Name",
                "version": "Library Version String"
              }
            }
          }
        

Response:

          {
            "event":"authenticated",
            "data": {
              "user":{
                "id": "476bfd54-81f4-4661-9052-180a9516bf47",
                "type": "user",
                "first_name": "User First Name",
                "last_name": "User Last Name",
                "company_name": "User Company Name",
                "company_id": "a4b9186f-ef89-448b-8cce-8e82c3c8f4ff",
                "position": "User Job Title",
                "avatar": "https://link/to/avatar",
                "active": true
              },
              "session_id":"b22221e0-266d-497b-89e2-1b4bb0778427"
            }
          }
        

Presence

Sending own presence updates:

          {
            "event":"presence_update",
            "data": {
              "status": "online|busy|away|offline"
            }
          }
        

Receiving presence updates from other users:

          {
            "event":"presence_update",
            "data": {
              "status": "online|busy|away|offline",
              "user_id": "57e56938-a455-422d-8173-80efb2146d1c"
            }
          }
        

Conversations

A conversations demo preview of this gateway can be found here.

New Conversation

Event when a new Conversation is created:

          {
            "event":"new_conversation",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1"
            }
          }
        

Messages

Sending message to a Conversation:

          {
            "event":"conversation_new_message",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "body": "message body"
            }
          }
        

Receiving message from a Conversation:

          {
            "event":"conversation_new_message",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "body": "message body"
            }
          }
        

Receiving message liked notification:

          {
            "event":"conversation_message_liked",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Receiving message deleted notification:

          {
            "event":"conversation_message_deleted",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Typing Indicator

Sending to Conversation:

          {
            "event":"typing|stop_typing",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1"
            }
          }
        

Receiving from Conversation:

          {
            "event":"typing|stop_typing",
            "data": {
              "conversation_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1"
            }
          }
        

Groupchats

A groupchats demo preview of this gateway can be found here.

New Groupchat invitation

          {
            "event": "new_groupchat",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Removed from Groupchat

          {
            "event": "groupchat_removed",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Subscribe to Groupchat events

To receive message body, event when the groupchat has been closed and typing indicators from users in a groupchat, you must subscribe to the groupchat by sending the following message:

          {
            "event":"groupchat_subscribe",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Unsubscribe from Groupchat events

To stop receiving message body, event when the groupchat has been closed and typing indicators from users in a groupchat, you must unsubscribe from the groupchat by sending the following message:

          {
            "event":"groupchat_unsubscribe",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Messages

Sending message to a Groupchat:

          {
            "event":"groupchat_new_message",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "body": "message body"
            }
          }
        

Receiving message from a Groupchat:

Note: The message body can only be received when subscribed to the groupchat and receiving messages can have a short delay without groupchat subscription.

          {
            "event":"groupchat_new_message",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "body": "message body"
            }
          }
        

Receiving messages with optional question options :

Note: Empty users array means all members can answer

          {
            "event":"groupchat_new_message",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "body": "message body",
              "question": {
                "users": [],
                "options": [
                  {
                    "name": "yes",
                    "label": "Yes",
                    "style": "green"
                  },
                  {
                    "name": "no",
                    "label": "No",
                    "style": "red"
                  }
                ],
                "style": "horizontal|vertical",
                "multi_answer": false
              }
            }
          }
        

Answering question messages using the option name:

          {
            "event":"groupchat_question_answer",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15",
              "options": [
                "yes"
              ]
            }
          }
        

Receiving question answers:

          {
            "event":"groupchat_question_answer",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15",
              "options": [
                "yes"
              ]
            }
          }
        

Receiving message liked notification:

          {
            "event":"groupchat_message_liked",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Receiving message deleted notification:

          {
            "event":"groupchat_message_deleted",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Verification Requests

Receiving verification requests:

          {
            "event":"groupchat_verification_request",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15",
              "provider": {
                "provider_id": "55b23a74-f3d9-4995-8793-0ad6212a9bb0",
                "title": "Identity Provider"
              },
              "target_user_id": "302a2654-f07b-4a19-b3ce-598db7f31424"
            }
          }
        

Receiving accepted verification request:

          {
            "event":"groupchat_verification_accepted",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Receiving rejected verification request:

          {
            "event":"groupchat_verification_rejected",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Rejecting a verification request:

          {
            "event":"groupchat_verification_reject",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "message_id": "237b25e7-b404-41cd-aeb8-cf7329210e15"
            }
          }
        

Typing Indicator

Sending to Groupchat:

Note: Can only be send and received when subscribed to the groupchat

          {
            "event":"typing|stop_typing",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Receiving from Groupchat:

          {
            "event":"typing|stop_typing",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1"
            }
          }
        

Groupchat Member Changes

Members added or removed:

          {
            "event":"groupchat_members_added|groupchat_members_removed",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "users": [
                "12e9d8af-d8ca-4cae-8753-44a52b462354",
                "7818e8a8-09d8-4262-bd1a-689abe563e4c"
              ]
            }
          }
        

Groupchat Closed

Receiving from Groupchat:

Note: Can only be received when subscribed to the groupchat

          {
            "event":"groupchat_closed",
            "data": {
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }