This documentation contains Alterdesk Gateway specifications to take in consideration when implementing the API in your system.
The gateway is a WebSocket server located at wss://api.alterdesk.com/v1/gateway
Clients are rate limited per access token. Clients surpassing these limits will receive an error and are immediately disconnected.
Clients connected are limited to 250 events every 60 seconds.
Clients connected are limited to 100 messages every 60 seconds.
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"
}
}
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"
}
}
A conversations demo preview of this gateway can be found here.
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"
}
}
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"
}
}
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"
}
}
A groupchats demo preview of this gateway can be found here.
{
"event": "new_groupchat",
"data": {
"groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
}
}
{
"event": "groupchat_removed",
"data": {
"groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
}
}
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"
}
}
Receiving dial in code changed notification:
{
"event":"groupchat_dial_in_code_changed",
"data": {
"groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f",
"user_id": "342c08c9-827e-42dc-badb-b1ba87c50ba1",
"dial_in_code": "123456789"
}
}
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"
}
}
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"
}
}
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"
]
}
}
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"
}
}
Receiving from Groupchat:
{
"event":"groupchat_closed",
"data": {
"groupchat_id": "dc1481a7-80a7-42fe-9622-e33c7e75d90f"
}
}