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"
            }
          }
        

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:

          {
            "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:

          {
            "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 Subject Changes

Receiving from Groupchat:

          {
            "event":"groupchat_subject_changed",
            "data": {
              "from": "old subject",
              "to": "new subject",
              "user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
              "groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
            }
          }
        

Groupchat Closed

Receiving from Groupchat:

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