1. Overview
  2. Create a Space
  3. Get My Spaces
  4. Join a Space
  5. Invite to a Space
  6. Change Settings
  7. Remove member
  8. Change member role
  9. Direct Space
  10. Delete a Space
  11. Hide a Direct Space
  12. Un-Hide a Direct Space

1 Overview

Evidently, a space is at the core of the features provided by Avaya Spaces. Users must be a member of a space to communicate via chat or video/audio, getting everybody in the same space is important. This tutorial outlines the steps to perform the most common actions related to a space: create, join, list, and invite.

It is important to note that there are 2 types of spaces: group and direct. Direct spaces are used for direct communication with another user. This tutorial covers group spaces, for more information on direct spaces see section 9.

2 Create a Space

Only registered Avaya Spaces users can create a new space. To create a space make a POST request to /api/spaces/. For example:

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    data: {
        cid: '',    //userid of current user
        title: 'new space',
        description: 'new space for tutorial',
        members: [
            {
                member: '',     //userid of current user
                memberType: 'userid',
                role: 'admin'
            },
            {
                member: '',     //userid of member
                memberType: 'userid',
                role: 'member'
            }
        ]
    },
    success: function(response) {
        console.log(response);
    }
});

Note: Members can be added and removed at any time after the space is created.

Note: To obtain an access_token see here.

If we want Avaya Spaces to send invites to each member when we create the space make a request to /api/spaces/invite instead.

3 Get my Spaces

To get a list of the spaces the current user is a member of (including direct spaces), make a request to /api/users/me/spaces. For example:

GET https://spacesapis.zang.io/api/users/me/spaces?topicstatus=0&topictype=group

This example will return a list of group spaces that are not archived. The spaces are ordered such that the most recently accessed spaces will be first. See the api reference for more information and options.

4 Join a Space

Once a user has been invited to join a space, they must join it. Joining the space notifies other members we have joined and retrieves information about the space so that the user can participate. This includes retrieving the media server to join audio/video communications. To join a space make a request to /api/spaces/{spaceId}/join. For example:

GET https://spacesapis.zang.io/api/spaces/{spaceId}/join

5 Invite to a Space

To add users to an existing space we must invite them, even if they are not users of Avaya Spaces they will be able to join our space as a guest. To send invites make a POST request to /api/spaces/{spaceId}/invite. For example:

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/59381425e8466d05641bb80f/invite',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    data: {
        "invitees": [
            {
                "inviteeType": "email",   // this is not registered user
                "invitee": "han42@avaya.com",
                "role": "guest"  //optional: 'member' (default), 'admin', 'guest'
            },
            {
                "inviteeType": "userId",   // this is a registered user
                "invitee": "5890b1243bab0e18ff044943", // this is the user id
                "role": "member" //optional: 'member' (default), 'admin', 'guest'
            }
        ]
    },
    success: function(response) {
        console.log(response);
    }
});

When invites are sent, users will be notified by email with a link to directly join the space.

6 Change Settings

An admin of a space can change the settings of a space, for example the title. To do this make a POST request to /api/spaces/{spaceId}. The following example will update the title to Emergency Meeting.

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/{spaceId}',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    data: {
        title: 'Emergency Meeting'
    },
    success: function(response) {
        console.log(response);
    }
});

Also, any member of a space can favorite a space and toggle notifications for a space. These are individual user settings for a space and can be updated by making a POST request to /api/users/me/topics/{spaceId}/preference. For example:

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/{spaceId}',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    data: {
        isPinned: true,
        notification: true
    },
    success: function(response) {
        console.log(response);
    }
});

This example will favorite the space and enable notifications for it.

7 Remove Member

To remove a member from a space. Send a DELETE request to /api/spaces/{spaceId}/attendees/{attendeeType}/{userId}. For example:

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/59381425e8466d05641bb80f/attendees/userid/588d08e53bab0e18ff043f12',
    type: 'DELETE',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    success: function(response) {
        console.log(response);
    }
});

Note: Members cannot be removed from a direct space.

Note: There must be 1 admin in a space, so an admin cannot remove himself/herself if there is no other admin.

8 Change Member Role

There are 3 role types in a space: admin, member and guest. To change the role of an attendee of a space, make a POST request to/api/spaces/{spaceId}/attendees/{attendeeType}/{userId}. This example will promote the user to admin.

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/59381425e8466d05641bb80f/attendees/userid/588d08e53bab0e18ff043f12',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    data: {
        role: 'admin'
    },
    success: function(response) {
        console.log(response);
    }
});

Admins
have full control of a space.
Members
can create posts, tasks and see the full history of a space.
Guests
can view/send messages and participate in audio/video session.

9 Direct Space

Direct spaces are used to communicate between two parties only. The following API endpoint is used to get or create a direct space between the current user and another user: /api/spaces/direct/{userType}/{userId}. This example will return the spaceId and other details for a space between the current user and another spaces user:

GET https://spacesapis.zang.io/api/spaces/direct/user/588d08e53bab0e18ff043f12

The following actions are not available on direct spaces:

  • Invite members
  • Remove members
  • Change settings (favorite, notifications)

10 Delete Space

This API allows an admin to delete a space. To do this make a DELETE request to /api/spaces/{spaceId}.

Note: This space and all of its content will be deleted permanently!.

$.ajax({
    url: 'https://spacesapis.zang.io/api/spaces/{spaceId}',
    type: 'DELETE',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    success: function(response) {
        console.log(response);
    }
});

The Spaces-Server would send the following Socket event to all members of deleted space.

var message = {
    sender: {
        _id: '{senderId}',
        type: 'user',
        displayname: 'Sender display name'
    },
    category: 'topic.deleted',
    topicId: '{spaceId}'
};

11 Hide Direct Spaces

This API allows a user to hide a direct space from direct-spaces list.
To hide a Space make a POST request to /api/users/me/spaces/{spaceId}/hide.

Note:

  • All contents for the space identified by spaceId is preserved and visible to the other party.
  • The other party will still see this user's Direct Space in his/her list of direct spaces.
  • The other party can initiate chat with this user anytime.
  • If a user re-enters the hidden Direct Space that space will become active and visible again.

$.ajax({
    url: 'https://spacesapis.zang.io/api/users/spaces/{spaceId}/hide',
    type: 'POST',
    headers: {
        'Authorization': 'bearer ' + access_token
    },
    success: function(response) {
        console.log(response);
    }
});

The Spaces-Server would send the following Socket event to the user. So, other apps would hide this space from the user's Direct Spaces list.

var message = {
    sender: {
        _id: '{senderId}',
        type: 'user',
        displayname: 'Sender display name'
    },
    category: 'topic.hidden',
    topicId: '{spaceId}'
};

12 Un-Hide Direct Spaces

Un-Hiding of direct spaces is done by accessing hidden direct-spaces via the following apis:


User can re-enter the hidden Direct Space by:

Upon re-entering a hidden direct-space, the Spaces-Server would send the following Socket event to the user. So, other apps would add this space to the user's Direct Spaces list.


var message = {      
  "category":"app.event.topic.new",
  "content":{     
    "_id":"fake_topicid1",
    "uid":"DT_user_fake_userid1&user_fake_userid2",
    "cid":"fake_userid2",
    //... more topic data
  },
  "sender":{  
    "_id":"fake_userid1",
    "type":"user",
    "displayname":"user1"
  }
}