NAV
cURL NodeJS

Introduction

The Bandyer API are organized around REST. Our API has predictable, resource-oriented URLs, and use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code)

JSON is returned by all API responses, including errors.

Authentication

Authenticate your account when using the API by including your secret API key in the request. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

The API key must be in the header of every request otherwise the request will fail.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

If you need help feel free to contact us: support@bandyer.com

Company

Update company

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/company/update" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
            "name" : "Test Company",
            "default_language" : "it",
        }'

Example Response

{
    "company": {
        "name": "Test Company",
        "default_language": "it"
    }
}

Update name and/or the default language of the company related to the given api_key;

HTTP Request

POST https://sandbox.bandyer.com/rest/company/update

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Type Required Default Description
name String no “” Name of the company to create, allowed chars are alphanumeric and #&@’.,?!
default_language String no “” Default language of the company and users created. Available options are “en” or “it”.

Error

Status Name Code Reason
400 invalid_request_error update_company_error Unable to update, please retry.
401 invalid_api_key invalid_api_key Apikey is not valid.
404 invalid_request_error company_not_found Company not found
422 validation_error invalid_company_name Invalid comapny name. Allowed chars are alphanumeric and #&@’.,?!
422 validation_error invalid_language Invalid language. The allowed languages are it, en

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/company/logo/update" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: multipart/form-data" \
     -F "logo=@/YOUR_LOCAL_IMAGE_PATH/image_name.png;type=image/png"

Example Response

{
    "logo_url": "https://static.bandyer.com/corporate/logos/logo_company_name.png"
}

Update the company logo.

The image provided must have a minimum size of 200x200, the recommended size is 300x300, otherwise, Bandyer will automatically resize the image for you. The max size allowed is 500Kb per file. The request will return the company logo image URL.

HTTP Request

POST https://sandbox.bandyer.com/rest/company/logo/update

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters (form-data)

Parameter Type Required Default Description
logo File yes The company logo image. The mime-type must be image/png or image/jpeg. Max file size is 500Kb. Suggested dimensions are 300*300 pixels.

Error

Status Name Code Reason
400 invalid_request_error upload_error Unable to upload your file, please retry
400 invalid_request_error file_not_found The file provided must be a multipart file
401 invalid_api_key invalid_api_key Apikey is not valid.
404 invalid_request_error company_not_found Company not found
422 validation_error invalid_file Check the ‘logo’ param and the file validity (allowed extensions are png and jpg).
422 validation_error wrong_file_dimension Wrong dimensions, the file must be at least 200 x 200
422 validation_error error_processing_image Error while processing the image, check the logo and retry

User

Create User

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/user/create" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
         "id" : "user_xxx",
         "role" : "basic",
         "can_video": "1"
         "language": "it"
     }'

Example Response

{
  "user": {
    "id": "user_xxx",
    "role" : "basic",
    "can_video": true,
    "language": "it"
  },
  "id": "jhon.doe"
}

Create a user in Bandyer. Users are identified by a unique ID which can be customized specifying it as input or it will be generated randomly. Each user must have a role. Valid roles are:

Role Description
basic Allow the user to join rooms
plus Allow the user to create and join rooms

Note: A basic user can create a room only if one of the participants have a plus role

HTTP Request

POST https://sandbox.bandyer.com/rest/user/create

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Required Default Description
id no random_str Custom user id, useful to avoid the Bandyer/Customer users mapping.
If specified, it must be unique within your account.
The custom id can be composed by alphanumeric characters [a-zA-Z] and . _ - symbols.
If the param is not specified, Bandyer will generate a random ID automatically (Max 128 characters).
role yes “” Roles of the user.
Available options are “basic” or “plus”
can_video no 1 The user’s video publishing permission.
language no Company default language Language of the user.
Available options are “en” or “it”.

Error

Status Name Code Reason
400 invalid_request_error user_id_already_exists The specified user_id already exists in this company
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error role_validation_error Invalid role, available options are basic or plus

Deprecated parameters — Deprecation date: 22/01/20

Parameter Required Default Description
firstname no “” Firstname of the user (Max 32 characters).
lastname no “” Lastname of the user (Max 32 characters).
nickname no “” Will be displayed in the system. If not specified, the system will assign a random nickname (Max 16 characters).
email no “” Email of the user.

Deprecated Error

Status Name Code Reason
422 validation_error email_validation_error Email invalid format

Update user

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X PUT "https://sandbox.bandyer.com/rest/user/update/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
          "can_video": "1"
          "language": "it"
     }'

Example Response

{
  "user": {
    "id": "usr_5b63a42e7ec2",
    "role": "basic",
    "can_video": true,
    "language": "it",
    "firstName": "Jane",
    "lastName": "Doe",
    "nickname": "jane.doe",
    "email": "john@doe.com"
  }
}

Updates a user by setting the values of the parameters passed as input. Not specified parameters will be left unchanged.

Note: The id and the role cannot be updated.

HTTP Request

PUT https://sandbox.bandyer.com/rest/user/update/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
id yes “” The id of the user to update

Body Parameters

Parameter Required Default Description
can_video no “1” The user’ video publishing permission.
language no “en” Language of the user. Available options are “en” or “it”.

Error

Status Name Code Reason
400 invalid_request_error invalid_user_id The specified user_id not exists in this company
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error role_validation_error Invalid role, available options are basic or plus

Deprecated parameters — Deprecation date: 22/01/20

Parameter Required Default Description
firstname no “” Firstname of the user (Max 32 characters).
lastname no “” Lastname of the user (Max 32 characters).
nickname no “” Will be displayed in the system.
email no “” Email of the user.

Deprecated Error

Status Name Code Reason
422 validation_error email_validation_error Email invalid format

Update all users permissions

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X PUT "https://sandbox.bandyer.com/rest/user/update/all/permissions" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
          "can_video" : "1"
     }'

Example Response

{
  "users": {
    "count": 241,
    "can_video": 1
  }
}

Updates video permission to all users of a company.

The request must contain the can_video permission parameter. The request will response with the number of user updated with the value of permissions updated.

HTTP Request

PUT https://sandbox.bandyer.com/rest/user/update/all/permissions

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Required Default Description
can_video yes “1” The user’ video publishing permission.

Update user avatar

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X PUT "https://sandbox.bandyer.com/rest/user/avatar/update/:user_id" \
  -H "apikey: COMPANY_APIKEY" \
  -H "Content-Type: multipart/form-data" \
  -F "avatar=@/YOUR_LOCAL_IMAGE_PATH/image_name.png;type=image/png"

Example Response

{
    "avatar_url": "https://static.bandyer.com/corporate/sample_avatar/custom/cmpny_tnc948cnr798ds/usr_5b63a42e7ec2"
}

Updates a user avatar image uploaded as param in the post request.

The request must contain the id of the user to update an image to, as the avatar param. The provided image should have the 300*300 pixel size, otherwise, Bandyer will automatically resize the image for you. The max size permitted to upload is 500Kb per file. The request will return the user avatar image URL.

HTTP Request

PUT https://sandbox.bandyer.com/rest/user/avatar/update/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.
content-type yes multipart/form-data Must be this value only

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to update

Body Parameters (form-data)

Parameter Required Default Description
avatar yes no default The user avatar image. The mime-type must be image/png or image/jpeg. Max file size is 500Kb. Suggested dimensions are 300*300 pixels.

Delete user

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X DELETE "https://sandbox.bandyer.com/rest/user/delete/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "id": "usr_55608a20053f",
    "message": "user deleted"
}

By specifying the id of the user is possible to delete a user from the platform. The response will contain a confirmation message.

HTTP Request

DELETE https://sandbox.bandyer.com/rest/user/delete/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to delete

Retrieve user

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/user/list/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
  "user": {
    "id": "usr_5b63a42e7ec2",
    "role" : "basic",
    "can_video": true,
    "language": "it",
    "firstName": "Jane",
    "lastName": "Doe",
    "nickname": "jane.doe",
    "email": "john@doe.com"
  }
}

Retrieves the details of the user.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/list/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to retrieve

Error

Status Name Code Reason
400 invalid_request_error invalid_user_id The specified user_id not exists in this company
401 invalid_api_key invalid_api_key Apikey is not valid

Get users list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/user/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
  "user_id_list": [
    "usr_5b63a42e7ec2",
    "usr_e3bf12fd6827"
  ]
}

Returns a list of user ids. If there are no users, the list will be empty. The response will be an array of user ids.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/list

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Get user rooms list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/user/room/list/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "filter" : [{ "limit": X, "skip" : Y }]
      }'

Example Response

{
    "room_list": [
        {
            "room_id": "room_e3bf12fd6827",
            "creation_date": "2017-02-04T22:44:30.652Z"
        }
    ]
}

Get rooms created by a specific user or those he attended. If the user does not exist or has no rooms the returned list will be empty.

The response has a [room_list] key containing an array of rooms in which is specified the [room_id] and the [creation_date] and an optional parameters [disabled]

This REST endpoint has a filter parameter with two possible keys (filter[limit] and filter[skip]). This two filter can be used to retrieve a specific number of rooms(filter[limit]) or for example to paginate the results through the use of the skip filter (filter[skip])

Note: All date fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/room/list/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to retrieve room IDs.

Query Parameters

Parameter Required Default Description
filter[limit] no 0 The limit number of array elements as response.
filter[skip] no 0 The number of skipped elements.

Response

Parameter Description
room_id Room name
creation_date creation date of the room (ISO8601 time)
disabled Optional, if it is present the value is true and the room is disabled. When a room is disabled all the links are inactive

Get user broadcasts list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/user/broadcast/list/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "filter" : [{ "limit": X, "skip" : Y }]
      }'

Example Response

{
    "broadcast_list": [
        {
            "broadcast_id": "bro_e3bf12fd6827",
            "creation_date": "2017-02-04T22:44:30.652Z"
        }
    ]
}

Get broadcasts created by a specific user or those he attended. If the user does not exist or has no broadcasts the returned list will be empty.

The response has a [broadcast_list] key containing an array of rooms in which is specified the [broadcast_id] and the [creation_date]

This REST endpoint has a filter parameter with two possible keys (filter[limit] and filter[skip]). This two filter can be used to retrieve a specific number of broadcasts(filter[limit]) or for example to paginate the results through the use of the skip filter (filter[skip])

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/broadcast/list/:user_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to retrieve broadcast IDs.

Query Parameters

Parameter Required Default Description
filter[limit] no 0 The limit number of array elements as response.
filter[skip] no 0 The number of skipped elements.

Get user chats list

Example Request (change COMPANY_APIKEY with a valid API key and user_id with valid users):

curl -X GET "https://sandbox.bandyer.com/rest/user/:user_id/chat/list"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "user_id": "usr_xxx",
    "chat_list": [
        {
          "users": ["usr_xxx","usr_yyy"],
          "unread_messages_count": 1,
          "last_message": {
            "index": 2,
            "body": "message",
            "from": "usr_xxx",
            "date": "2020-01-15T11:57:43.000Z",
            "type": "text"
          }
        },
        {
          "users": ["usr_xxx","user_zzz"],
          "unread_messages_count": 0,
          "last_message": null
      }
    ]
}

Returns the list of the chats of the user. Each element of the chat_list array contains information about the chat such as, the unread message count and the last message sent.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/:user_id/chat/list

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes “” The id of the user to retrieve the chat list.

Error

Status Name Code Reason
400 invalid_request_error invalid_users_length Users array must contain at least two valid users.
400 invalid_request_error chat_service_disabled The chat service is not enabled for your company
400 invalid_request_error invalid_user_id User id not found
400 invalid_request_error invalid_chat Unable to retrieve chat information such as members

Get user uploads list

Example Request (change COMPANY_APIKEY with a valid API key and user_id with valid users):

curl -X GET "https://sandbox.bandyer.com/rest/user/:user_id/upload/list"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "upload_type" : "snapshot"
        "skip" : X,
        "limit" : Y
     }'

Example Response

{
  "skip": 0,
  "limit": 20,
  "has_more": true,
  "count": 20,
  "uploads": [
    {
      "key": "sandbox/comapny/user_id/1585071715613-c8a493a0217fcbd69c7f",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:41:56.000Z",
      "user_id": "user_id",
      "session_id": "session_a1n5bk022jg9",
      "room_id": null
    },
    {
      "key": "sandbox/comapny/user_id/1585070036835-7eccda27957cf7b27d5c",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:13:57.000Z",
      "user_id": "user_id",
      "session_id": "session_a1n5bk022jg9",
      "room_id": "room_5beecf8c0f29"
    }
    ]
}

Returns a list uploaded resources for the given user with additional information including the key of the resource to collect it using the dedicated Get upload resource api. If no uploads are present an empty list will be returned.

It is possible to filter the returned list specifying upload_type, skip and limit filter values.

The response will be an object containing the following information:

HTTP Request

GET https://sandbox.bandyer.com/rest/user/:user_id/upload/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes The id of the user to retrieve the chat list.

Query Parameters

Parameter Required Type Default Description
upload_type no String The upload_type can be one of file_upload, generic and snapshot
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in uploads array
uploads Array Array of uploaded resources matching the filters ordered by creation_date (DESC)

Error

Status Name Code Reason
400 invalid_request_error invalid_user_id User not found
401 invalid_api_key invalid_api_key Apikey is not valid

Get user sessions list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/:user_id/session/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
        "skip": X
        "limit": Y,
        "start_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
        "end_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
     }'

Example Response

{
  "skip": 0,
  "limit": 2,
  "has_more": true,
  "count": 2,
  "sessions": [
    {
      "session_id": "session_46365c12bc1c",
      "creation_date": "2020-05-08T15:14:16.000Z",
      "duration": null,
      "connected_participants": [
        "user_xxx",
        "user_yyy"
      ],
      "room_id": "room_7f60e61bd24e"
    },
    {
      "session_id": "session_919e35d58c29",
      "creation_date": "2020-05-07T08:33:00.000Z",
      "duration": null,
      "connected_participants": [
        "user_xxx",
        "user_yyy",
        "user_zzz"
      ],
      "room_id": "room_7f60e96lk24e"
    }
  ]
}

This end-point could be used to get basic information of all the sessions of the given user.

The results are ordered by creation_date and can be filtered by skip, limit, start_date and end_date,

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/user/:user_id/session/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes The id of the user to retrieve the session list.

Query Parameters

Parameter Required Type Default Description
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100
start_date no Date-Time Filter apply to a creation_date. creation_date greater then start_date
end_date no Date-Time Filter apply to a creation_date. creation_date lower then end_date

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in sessions array
sessions Array Array of sessions resources matching the filters ordered by creation_date (DESC)

Sessions Object

Parameter Type Description
session_id String Id of the session.
creation_date String
duration Number Elapsed time of the session, if 0 the session timing was not elaborated yet.
connected_participants Array of String List of users who actually participated in the call (Can be differ from the users invited to the call).
room_id String Id of the Room that have generated this session.

Error

Status Name Code Reason
400 invalid_request_error invalid_user_id Invalid user, please check if the user exists
401 invalid_api_key invalid_api_key Apikey is not valid

Room

In this section, it is explained how to create a room in the Bandyer platform.

A room is a sort of virtual place where users, identified at room creation time, can communicate.

Note: With a room you can set a maximum call duration, recording option, direct call link and listening to webhook events described in Web Hooks section.

A room can be created only if one of the users have a plus role. Refer to the users section for more info

Create room

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/room/create" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
         "participants": [{"user_id": "usr_xxx", "tools": {"chat":true}, "is_admin": true }, {"user_id": "usr_yyy"}],
         "record": "1",
         "duration": "120",
         "description": "A textual description of the rest room created",
         "initiatorAlias": "usr_xxx"
     }'

Example Response

{
    "room": {
        "room_id": "room_xyz",
        "record": 1,
        "duration": 120,
        "directCall": false,
        "call_type": "audio_video",
        "live": false,
        "description": "A textual description of the rest room created...",
        "user_urls": [
            {
                "user": "usr_xxx",
                "url": "https://sandbox.bandyer.com/attach/rest-call-handler/aaaaaaaaaa",
                "tools": {
                    "screen_sharing": false,
                    "whiteboard": false,
                    "chat": true,
                    "file_upload": false,
                    "live_edit": false,
                    "snapshot": false,
                    "live_pointer": false
                    },
                "is_admin": true
            },
            {
                "user": "usr_yyy",
                "url": "https://sandbox.bandyer.com/attach/rest-call-handler/bbbbbbbbbb",
                "tools": {
                    "screen_sharing": true,
                    "whiteboard": {
                        "wb_pen": true,
                        "wb_eraser": true,
                        "wb_add_file": true,
                        "wb_text": true,
                        "wb_shape": true,
                        "wb_cursor": true
                    },
                    "chat": true,
                    "file_upload": true,
                    "live_edit": true,
                    "snapshot": true,
                    "live_pointer": true
                    },
                "is_admin": false
            }
        ]
    }
}

The duration parameter indicates the maximum duration of the call. It is expressed in seconds. If the parameter is not specified, the call has unlimited duration. The minimum duration is 60 minutes.

The directCall parameter indicates the type of link provided by the endpoint. If directCall is true, the user will have direct access to the call. The user will not see the Bandyer landing page with information about invited users and call options. Default is false.

The response returns the URLs that each user can use to join the call.

Note: Within the sandbox server, calls won’t be registered even if indicated in the REST parameters. If you would like to try the recording option in sandbox, please contact us at support.

Note: 30 seconds before the time is up all clients get notifications of the short time left. When the duration expires the call ends. Available time runs only when clients are in the videocall. If they are experiencing problems and the connection drops, the timer will stop.

Note: If you have enabled WebHooks (described in Web Hooks section), the room_id returned in the response, could be saved in your database for further hook events that might be received.

HTTP Request

POST https://sandbox.bandyer.com/rest/room/create

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body Parameters

Parameter Required Type Default Description
participants yes Array Array of users who will participate in the call. See more in participants section
record no String “0” This param defines whether the room should be recorded “1” or not “0”.
recording_type no String “automatic” This param defines if the recording must be activated automatically for the whole session or if it must be activated manually. Allowed values are automatic and manual. N.B: at the moment this param setting is observed only web components (web links and web widget)
call_type no String “audio_video” This param defines type of the call. Allowed values are audio_only, audio_upgradable or audio_video.
directCall no Boolean false Setting this param to true gives direct access to the call bypassing the pre call summary.
description no String A textual description of the room.
live no Boolean false This param defines whether the usage of generated links triggers widget and mobile ringing or not. If set to true it also trigger the sending of the on_call_incoming webhook.
initiatorAlias no String Room creator alias (a valid user alias).
duration no Number Maximum value expressed in seconds of effective calling time allowed for the room. The minimum value is 60. If not specified, the call duration is unlimited. With effective calling time is intended the sum of the time where the room is running with at least two connected users.

Deprecated parameters — Deprecation date: 07/04/20

Parameter Required Type Default Description
user_list_in_call no Array The array of the user alias that will participate to the room.

Participants parameter

{
    "participants": [
    {
        "user_id": "user_xxx",
        "is_admin": true,
        "tools": {
            "chat" : true,
            "file_upload":true,
            "screen_sharing": true,
            "whiteboard": true,
            "snapshot": true,
            "live_edit": true,
            "live_pointer": true
        }
    },
    {
        "user_id": "user_yyy",
        "tools": {
            "chat" : true,
            "whiteboard": { "wb_text": true, "wb_pen": true },
            "snapshot": true
        }
    }
    ]
}
Parameter Required Type Default Description
user_id yes String Id of the user who join the call
is_admin no Boolean false Allow the user to trigger some events on the other participants, for example the admin can toggle the whiteboard to the other users.
tools no Object All enabled Allows you to enable the available tools during the call. See tools section for more details

Tools

The tools parameter is included in the participants field.

By default, if no tools are provided (missing field), all the tools are enabled. If the tools field is defined but empty, all the tools are disabled.

List of available tools

Name Description
chat Enable the chat feature
screen_sharing Enable the screen_sharing feature
file_upload Enable the capability to send file
whiteboard If true enable all the whiteboard tools. Can be an object of whiteboard tools
snapshot Enable the snapshot feature
live_edit Enable the live_Edit feature
live_pointer Enable to send pointer-events to others participants (always active in reception)
Combination Receive live_edit Collaborate Snapshot & Gallery Open whiteboard
SN+ LE + WB
SN
SN + WB (default LE active in reception)
WB (default LE active in reception)
NONE

Whiteboard tools

{
    "tools": {
        "whiteboard": {
            "wb_add_file": true,
            "wb_cursor": true,
            "wb_text": true,
            "wb_shape": true,
            "wb_pen": true,
            "wb_eraser" : true
        }
    }
}

The whiteboard tools object is included in the tools parameter of the participants field.

Name Description
wb_add_file Allows to add files on the whiteboard
wb_cursor Allows to send the cursor events to the other participants
wb_text Allows to add text on the whiteboard
wb_shape Allows to add shape on the whiteboard
wb_pen Allows to using the pen on the whiteboard
wb_eraser Allows to erase a previous draw on the whiteboard

Get rooms list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/room/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
         "skip": X
         "limit": Y
     }'

Example Response

{
  "skip": 0,
  "limit": 2,
  "has_more": true,
  "count": 2,
  "rooms": [
    {
      "room_id": "room_20201cff4be7",
      "record": true,
      "call_type": "audio_video",
      "live": false,
      "description": null,
      "status": "NOT_RUNNING",
      "creationDate": "2020-04-16T11:56:55.746Z"
    },
     {
      "room_id": "room_1106b1c1b106",
      "record": false,
      "call_type": "audio_video",
      "live": true,
      "description": null,
      "status": "CLOSED",
      "creationDate": "2020-04-16T09:48:10.340Z",
      "disabled": true
    }
  ]
}

This end-point could be used to get basic information of all the rooms of a company.

The results are ordered by creationDate and can be filtered by skip and limit,

HTTP Request

GET https://sandbox.bandyer.com/rest/room/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Query Parameters

Parameter Required Type Default Description
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in rooms array
rooms Array Array of rooms resources matching the filters ordered by creation_date (DESC)

Rooms Object

Parameter Type Description
room_id String The id of the room that you want the information
record Boolean True if the room is recordable
call_type String This is the call type, it can be ‘audio_only’, ‘audio_upgradable’ or 'audio_video’.
description Number A textual description of the room.
status String This parameter explains the status of the room as you can see in the table below.
creationDate String Date and time of when the room was created ISO8601 standard.
disabled Boolean Optional, if it is present the value is true and the room is disabled. When a room is disabled, the user_urls param is empty
Status Description
NOT_RUNNING Current room is not running
RUNNING Current room is running
CLOSED Current room is deleted or ended (not available)

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Get room information

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/room/info/:room_id" \
     -H "apikey: COMPANY_APIKEY"

Example Response

{
    "room": {
        "room_id": "room_b571df8d8h3d",
        "record": 1,
        "duration": 120,
        "durationUsed": 0,
        "call_type": "audio_video",
        "live": false,
        "description": "A textual description of the rest room created...",
        "status": "NOT_RUNNING",
        "user_urls": [
            {
                "user": "usr_xxx",
                "url": "https://sandbox.bandyer.com/attach/rest-call-handler/aaaaaaaaaaaaaaaaaaaaa"
            },
            {
                "user": "usr_yyy",
                "url": "https://sandbox.bandyer.com/attach/rest-call-handler/bbbbbbbbbbbbbbbbbbb"
            }
        ],
        "dialInfo": {
            "sessions": {
                "number": 7,
                "hours": 0,
                "minutes": 8,
                "seconds": 4,
                "users": 2,
                "details": [
                    {
                        "session": "session_c73d8cfe4330",
                        "creationDate": "2017-02-04T22:44:30.652Z",
                        "hours": 0,
                        "minutes": 2,
                        "seconds": 37,
                        "users": 2,
                        "userEvents": [
                            {
                                "user": "usr_cd4791a26916",
                                "timestamp": "2017-02-04T22:44:30.652Z",
                                "event": "user connected"
                            }
                        ],
                        "userActivities": [
                            {
                                "user": "usr_e39b045f215f",
                                "startTime": "2017-02-04T22:44:30.652Z",
                                "stopTime": "2017-02-04T22:44:30.652Z",
                                "seconds": 57
                            }
                        ]
                    }
                ]
            }
        }
    }
}

This end-point could be used to get room information through a valid room_id.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/room/info/:room_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
room_id yes String The id of the room that you want the informations.

Response

Parameter Description
room_id Room name
record True if the room is recordable
duration Max duration limit of the room, if 0 is unlimited
durationUsed How many seconds the room was in RUNNING state. If the duration used is equals to the duration parameter, the room status will be CLOSED.
call_type This is the call type, it can be ‘audio_only’, 'audio_upgradable’ or 'audio_video’.
description A textual description of the room.
status This parameter explains the status of the room as you can see in the table below.
disabled Optional, if it is present the value is true and the room is disabled. When a room is disabled, the user_urls param is empty
user_urls Array of obj that contains the url of each user
dialInfo Contains informations about sessions and users: room total time and users, detail for each session (with partial time and user count) and every user activity and event.
Status Description
NOT_RUNNING Current room is not running
RUNNING Current room is running
CLOSED Current room is deleted or ended (not available)

Get room session recording

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/room/recording/:session_id" \
     -H "apikey: COMPANY_APIKEY" \
     -d '{
         "expire_time": XXXX
     }'

Example Response

{
    "url": "https://recordings.bandyer.com/sandbox/135/23715/23715.mp4?Expires=1529053578&Policy=eyJTdGF0ZW1gbnQiOlt7IlJlc291cmNlIjoiaHR0cHM6Ly9yZWNvcmRpbmdzLmJhbmR5ZXIuY25tL2RldmVsb3BtZW50LzEyNS8yMzc5NS8yMzc5NS5tcDQiLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiLjE1MjkwNTM1Nzh9fX1dfQ__&Signature=LjDbMYIASbdJCSfWFxfu1A0HzKjzrUWKXqgCCc2OX-YzdGSOOHfPfiHaDOwdi0uBjqpvOegjakmy1QE5DGV8~OYYjT5IBiTWZTx9gTZRwYTMGwgvHmAUndi8Tiq8wWqZislv4n413QBSwq74oVMyZxx611Ssl7R62YN0-3OiSJS16bh4yhlvx4JlwG~3rL1aERYBiixlYpadhS4~Syr6p69wHwPLqAew4v3FlWvfoJLr4NudHt9OAfB0vHCX6iAbHpYznyhIWf7k451GRr01KKmvwky~I2lRTWEHoDOXolAouyuXExR9Z5SkqI30RueQPd3axugaZ1KtXwT4dqR~Og__&Key-Pair-Id=APKARQIFJNX5UZ22C7FA"
}

This endpoint is used to obtain a session recording link.

In order to get a recording session URL, you have to choose the sessionID from Get Room Information section.

HTTP Request

GET https://sandbox.bandyer.com/rest/room/recording/:session_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
session_id yes String The id of a room session.

Query Parameters

Parameter Required Type Default Description
expire_time false Number 30000 The amount of time express in milli-seconds of the validity of the generated resource URL.

Error

Status Name Code Reason
400 invalid_request_error recording_not_found Recording for session :session_id not found.a
400 invalid_request_error room_no_recordable The room associated to the session :session_id is not recordable

Disable room

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X PUT "https://sandbox.bandyer.com/rest/room/disable/:room_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "room": {
            "room_id": "room_bb71dd8d8f3d",
            "message": "Room room_bb71dd8d8f3d and all user links associated disabled"
        }
}

This endpoint disable a specific room and all URL token link associated with it. A disabled room will not able to be used again, however, the latter will not be deleted from Bandyer’s data structure, all statistics will be still available. The request will reply with a message. In case of error, the message will explain the problem.

HTTP Request

PUT https://sandbox.bandyer.com/rest/room/disable/:room_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Default Description
room_id yes The id of the room to disable

Delete room

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X DELETE "https://sandbox.bandyer.com/rest/room/delete/:room_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "room": {
            "room_id": "room_bb71dd8d8f3d",
            "message": "Room room_bb71dd8d8f3d and all user links associated deleted"
        }
}

This endpoint deletes a specific room and all URL token link associated with it. The request will reply with a message. In case of error, the message will explain the problem.

HTTP Request

DELETE https://sandbox.bandyer.com/rest/room/delete/:room_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Default Description
room_id yes The id of the room to delete

Get room uploads list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/room/:room_id/upload/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
        "upload_type" : "snapshot"
        "skip" : X,
        "limit" : Y
     }'

Example Response

{
  "skip": 0,
  "limit": 20,
  "has_more": true,
  "count": 20,
  "uploads": [
    {
      "key": "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:41:56.000Z",
      "user_id": "user_xxx",
      "session_id": "session_c1b5bc092ea2",
      "room_id": "room_5beecf8c0f29"
    },
    {
      "url": "sandbox/company/user_yyy/1585070036835-7eccda27957cf7b27d5c",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:13:57.000Z",
      "user_id": "user_yyy",
      "session_id": "session_a1n5bk022jg9",
      "room_id": "room_5beecf8c0f29"
    }
    ]
}

Returns a list uploaded resources of a specific company room’s matching the apikey with additional information including the key of the resource to collect it using the dedicated Get upload resource api. If no uploads are present an empty list will be returned.

It is possible to filter the returned list specifying upload_type, skip and limit filter values.

HTTP Request

GET https://sandbox.bandyer.com/rest/room/:room_id/upload/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
room_id yes String The id of the room that you want the upload list.

Query Parameters

Parameter Required Type Default Description
upload_type no String The upload_type can be one of file_upload, generic and snapshot
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in uploads array
uploads Array Array of uploaded resources matching the filters ordered by creation_date (DESC)

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Broadcast

Create broadcast

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/broadcast/create" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "publisher_id": "usr_xxx",
        "panelists": [{"user_id" : "usr_yyy"}, {"user_id" : "usr_zzz"}]
        "description": "TestEvent",
        "record": "0"
     }'

Example Response

{
  "broadcast_id": "bro_beefa9f45545",
  "description": "TestEvent",
  "chat": true,
  "recording": false,
  "publisher_id": "usr_xxx",
  "panelists": [
      {
          "user_id": "usr_yyy"
      },
      {
          "user_id": "usr_zzz"
      }
  ]
}

The broadcast call is composed by one publisher and N subscribers. The publisher is the user who will present the event. The panelists are the co-presenters of the events (Up to 4), each of them can be broadcasted by the publisher. The subscribers are the users who will attend the event. The publisher can use his microphone and webcam in order to present the webinar. He can also use additional features such as screen-sharing, chat and file sharing. This type of call is mainly indicated for hosting an event with a high number of subscribers (~2000).

If the panelists parameter is specified the publisher in addition to our audio/video/screenshare can broadcast the source of the others participants. The broadcasted ‘video’ is the representation of the publisher view.

The request must contain the id of the user who will be the presenter of the broadcast event. It is possible to choose the name of the event and whether the event will be recorded or not. The response returns the broadcast id which will be used to join the broadcast event created.

HTTP Request

POST https://sandbox.bandyer.com/rest/broadcast/create

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body parameters

Parameter Required Type Default Description
publisher_id yes String Id of the user who will be the publisher of the broadcast event.
panelists no Array Lists of co-presenters that can be broadcasted by the publisher. Up to 4 panelists.
description yes String Name of the event.
chat no Boolean true If false disable the chat feature for all the subscriber’s
record yes String “” 1 if the user wants to record the videocall, 0 otherwise.

Error

Status Name Code Reason
400 invalid_request_error invalid_user_id Invalid user id for publisher or panelists
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_panelists_count Too many panelists. Max allowed panelists count is 4.

Call broadcast

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/call/:user_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
         "broadcast_id" : "broadcast_id"
     }'

Example Response

{
  "url": "https://sandbox.bandyer.com/connect/rest-call-handler/xxxyyyzzz"
}

To join a broadcast event, the user needs to be redirect in a specific Bandyer page. The request must contain the broadcast id of the event and the user id who has requested to join it. The response returns the url in which either the publisher or the subscriber must be redirected to join the broadcast event.

HTTP Request

GET https://sandbox.bandyer.com/rest/call/:user_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Default Description
user_id yes Id of the user who join the event

Query Parameters

Parameter Required Default Description
broadcast_id yes Broadcast id of the event
direct no false if set to true it will generate a link that will give direct access to the call without opening a new popup window

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
404 invalid_request_error invalid_broadcast_id Please specify at least one of the parameters between broadcast_id and callee

Deprecated parameters — Deprecation date: 20/10/20

Parameter Default Description
callee Broadcast id of the event

Get Broadcasts List

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/broadcast/list"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "skip" : X,
        "limit" : Y
     }'

Example Response

{
    "broadcasts": [
    {
        "id": "bro_cn92r039862rcn",
        "status": "CLOSED",
        "record": true,
        "chat": true,
        "description": "The description of the Broadcast",
        "creationDate": "2020-02-04T22:44:30.652Z",
        "publisher": {
            "id": "usr_yyy",
            "firstName": "Name",
            "lastName": "Surname",
            "email": "name.surname@dominio.com"
        }
    },
    {
      "id": "bro_2cad1c846749",
      "status": "NOT_RUNNING",
      "record": false,
      "chat": false,
      "description": "The description of the Broadcast",
      "creationDate": "2020-03-13T10:55:08.780Z",
      "publisher": {
        "id": "user_xxx",
        "firstName": "Name",
        "lastName": "Surname",
        "email": "name.surname@dominio.com"
      }
    }
    ]
}

This endpoint returns the list of broadcasts created for the company matching the provided apikey.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/broadcast/list

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Query Parameters

Parameter Required Default Description
skip no Skips the first the specified number of returned records.
limit no Limits the number of returned records to the specified number(or less if there aren’t enough).

Response

Status Description
NOT_RUNNING The broadcast is not running
RUNNING The broadcast is running
CLOSED The broadcast is ended (not available anymore)

Get broadcast information

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/broadcast/info/:broadcast_id"
     -H "apikey: COMPANY_APIKEY"

Example Response

{
    "broadcast": {
        "id": "bro_cn92r039862rcn",
        "status": "CLOSED",
        "record": true,
        "chat": true,
        "description": "The description of the Broadcast",
        "creationDate": "2017-02-04T22:44:30.652Z",
        "publisher": {
            "id": "usr_767bfa79c146",
            "firstName": "Name",
            "lastName": "Surname",
            "email": "name.surname@dominio.com"
        },
        "dialInfo": {
            "numberOfSessions": 2,
            "totalDurationTime": "00:12:37",
            "sessions": [
                {
                    "session_id": "session_cnruow48987",
                    "creationDate": "2017-02-04T22:44:30.652Z",
                    "subscribersCount": 0,
                    "subscribersConnTime": "00:00:00",
                    "publishTime": "00:06:18",
                    "totalTime": "00:06:18"
                },
                {
                    "session_id": "session_923846cb2398",
                    "creationDate": "2017-02-04T22:44:30.652Z",
                    "subscribersCount": 0,
                    "subscribersConnTime": "00:00:00",
                    "publishTime": "00:06:19",
                    "totalTime": "00:06:19"
                }
            ]
        }
    }
}

This end-point could be used to get broadcast information through a valid broadcast_id.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/broadcast/info/:broadcast_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
broadcast_id yes String “” The id of the broadcast that you want the informations.

Response

Status Description
NOT_RUNNING Current broadcast is not running
RUNNING Current broadcast is running
CLOSED Current broadcast is ended (not available anymore)

Get broadcast session recording

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/broadcast/recording/:session_id"
     -H "apikey: COMPANY_APIKEY" \
     -d '{
         "expire_time" : XXXX
     }'

Example Response

{
    "url": "https://recordings.bandyer.com/sandbox/135/23715/23715.mp4?Expires=1529053578&Policy=eyJTdGF0ZW1gbnQiOltsIlJlc291cmNlIjoiaHR0cHM6Ly9yZWNvcmRpbmdzLmJhbmR5ZXIuY25tL2RldmVsb3BtZWh0LzEyNS8yMzc5NS8yMzc5NS5tcDQiLCJDb25kaXRpb24iOnsiRGF0ZUxlc3NUaGFuIjp7IkFXUzpFcG9jaFRpbWUiLj71MjkwNTM1Nzh9fX1dfQ__&Signature=LjDbMYIASbdJCSfWFxfu1A0HzKjzrUWKXqgCCy2OX-YzdGSOOHfPfiHaDOwdi0uBjqpvOegjakmy1QE5DGV8~OYYjT5IBlTWZTx9gTZRwYTMGwgvHmAUndi8Tiq8wWqZislv4n413QBSwq74oVMyZxx611Ssl7R62YN0-3OiSJS16bh4yhlvx4JlwG~3rL1aERYBiixlYpadhS4~Syr6p69wHwPLqLew4v3FlWvfoJLr4NudHt9OAfB0vHCX6iAbHpYznyhIWf7k451GRr01KKmvwky~I2lRTWEHoDOXolAouyuXExR9Z5SkqI30RueQPd3axugaZ8KtXwT4dqR~Og__&Key-Pair-Id=APKARQIFJNX5US22C7FA"
}

This endpoint is used to obtain a broadcast session recording link. In order to get a recording session URL, you have to choose the sessionID from Get Broadcast Information section.

Note: In the Get Broadcast Information section, you can find all sessions’ information belonging to that specific broadcast. To find the sessionID needed, you can set up your favourite query such as: duration/creation_date/participants choosing among the key set in the response object.

HTTP Request

GET https://sandbox.bandyer.com/rest/broadcast/recording/:session_id?expire_time=30000

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
session_id yes String “” The id of a broadcast session.

Query Parameters

Parameter Required Type Default Description
expire_time false Number 30000 The quantity of validity time [ms] of the URL generated.

Error

Status Name Code Reason
400 invalid_request_error recording_not_found Recording for session :session_id not found.
400 invalid_request_error invalid_room_type The room associated with the session :session_id is not a broadcast

Session

Get sessions list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/session/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
        "skip": X
        "limit": Y,
        "start_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
        "end_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
     }'

Example Response

{
  "skip": 0,
  "limit": 2,
  "has_more": true,
  "count": 2,
  "sessions": [
    {
      "session_id": "session_46365c12bc1c",
      "creation_date": "2020-05-08T15:14:16.000Z",
      "duration": null,
      "connected_participants": [
        "user_xxx",
        "user_yyy"
      ],
      "room_id": "room_7f60e61bd24e",
      "broadcast_id": null
    },
    {
      "session_id": "session_919e35d58c29",
      "creation_date": "2020-05-07T08:33:00.000Z",
      "duration": null,
      "connected_participants": [
        "user_xxx",
        "user_yyy",
        "user_zzz"
      ],
     "room_id": null,
     "broadcast_id": "bro_7g258t62hn98y"
    }
  ]
}

This end-point could be used to get basic information of all the sessions of a company.

The results are ordered by creation_date and can be filtered by skip, limit, start_date and end_date,

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/session/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Query Parameters

Parameter Required Type Default Description
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100
start_date no Date-Time Filter apply to a creation_date. creation_date greater then start_date
end_date no Date-Time Filter apply to a creation_date. creation_date lower then end_date

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in sessions array
sessions Array Array of sessions resources matching the filters ordered by creation_date (DESC)

Sessions Object

Parameter Type Description
session_id String Id of the session.
creation_date String
duration Number Elapsed time of the session, if 0 the session timing was not elaborated yet.
connected_participants Array of String List of users who actually participated in the call (Can be differ from the users invited to the call).
room_id String Id of the Room that have generated this session. Can be null in case of the session refer to a broadcast
broadcast_id String Id of the Broadcast that have generated this session. Can be null in case of the session refer to a Room

Error

Status Name Code Reason
400 invalid_request_error get_session_list_error Impossible to get session list, please retry
401 invalid_api_key invalid_api_key Apikey is not valid

Get session information

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/session/:session_id" \
     -H 'apikey: COMPANY_APIKEY' \

Example Response

{
  "session_id": "session_46936c12bd1c",
  "creation_date": "2020-05-08T15:14:16.000Z",
  "duration": 300,
  "connected_participants": [
    "user_xxx",
    "user_yyy",
    "user_zzz"
  ],
  "room_id": "room_0f69e94yu24e",
  "broadcast_id": null
}

This end-point could be used to get session information through a valid session_id.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/session/:session_id

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
session_id yes String The id of the session that you want the information.

Response

Parameter Type Description
session_id String Id of the session.
creation_date String
duration Number Elapsed time of the session, if 0 the session timing was not elaborated yet.
connected_participants Array of String List of users who actually participated in the call (Can be differ from the users invited to the call).
room_id String Id of the Room that have generated this session. Can be null in case of the session refer to a broadcast
broadcast_id String Id of the Broadcast that have generated this session. Can be null in case of the session refer to a Room

Error

Status Name Code Reason
400 invalid_request_error get_session_error Impossible get session information, please retry
401 invalid_api_key invalid_api_key Apikey is not valid
404 invalid_request_error session_not_found Session not found

Get session connections list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/session/:session_id/connection/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
        "skip": X
        "limit": Y
     }'

Example Response

{
  "skip": 0,
  "limit": 20,
  "has_more": false,
  "count": 4,
  "session_id": "session_b3hg66d196987",
  "connection_events": [
    {
      "user_id": "user_xxx",
      "timestamp": "2020-05-06T14:52:12.898Z",
      "event": "user_disconnect"
    },
    {
      "user_id": "user_yyy",
      "timestamp": "2020-05-06T14:52:01.851Z",
      "event": "user_disconnect"
    },
    {
      "user_id": "user_xxx",
      "timestamp": "2020-05-06T14:52:01.845Z",
      "event": "user_connect"
    },
    {
      "user_id": "user_yyy",
      "timestamp": "2020-05-06T14:52:01.688Z",
      "event": "user_connect"
    }
  ]
}

This end-point could be used to get all the connection events of the users that have joined the session.

The results are ordered by timestamp and can be filtered by skip, limit

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/session/session_id/connection/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
session_id yes String The id of the session that you want the information.
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in connection_events array
connection_events Array Array of connection events resources matching the filters ordered by timestamp (DESC)

Connection events Object

Parameter Type Description
user_id String Id of the user
timestamp String Event Date and time ISO8601 standard.
event String Can be user_connect, user_disconnect or user_crashed

Error

Status Name Code Reason
400 invalid_request_error get_session_events_error Impossible get events for the given session, please retry
401 invalid_api_key invalid_api_key Apikey is not valid
404 invalid_request_error session_not_found Session not found

Get session uploads list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/session/:session_id/upload/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
        "upload_type" : "snapshot"
        "skip" : X,
        "limit" : Y
     }'

Example Response

{
  "skip": 0,
  "limit": 20,
  "has_more": true,
  "count": 20,
  "uploads": [
    {
      "key": "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:41:56.000Z",
      "user_id": "user_xxx",
      "session_id": "session_c1b5bc092ea2",
      "room_id": "room_5beecf8c0f29"
    },
    {
      "url": "sandbox/company/user_yyy/1585070036835-7eccda27957cf7b27d5c",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:13:57.000Z",
      "user_id": "user_yyy",
      "session_id": "session_c1b5bc092ea2",
      "room_id": "room_5beecf8c0f29"
    }
    ]
}

Returns a list uploaded resources of a specific company session’s matching the apikey with additional information including the key of the resource to collect it using the dedicated Get upload resource api. If no uploads are present an empty list will be returned.

It is possible to filter the returned list specifying upload_type, skip and limit filter values.

HTTP Request

GET https://sandbox.bandyer.com/rest/session/:session_id/upload/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
session_id yes String The id of the session that you want the upload list.

Query Parameters

Parameter Required Type Default Description
upload_type no String The upload_type can be one of file_upload, generic and snapshot
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in uploads array
uploads Array Array of uploaded resources matching the filters ordered by creation_date (DESC)

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Recording configuration

Configure how recordings are processed for the company. Recordings can have a prefixed storage retention, can be compressed to save storage space and can be encrypted using a public key of choice.

Get configuration

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/recording/config" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
   "retention_days": 15,
   "compression": true,
   "encryption_key_id": null
}

Get the current recording configuration. Note that if you have never set a recording configuration, a default one will be used.

HTTP Request

GET https://sandbox.bandyer.com/rest/recording/config

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Update configuration

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/recording/config" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d {
        "retention_days": 15,
        "compression": true,
        "encryption_key_id": "pk_xxxxxxxxxxxx"
      }

Example Response

{
   "retention_days": 15,
   "compression": true,
   "encryption_key_id": "pk_xxxxxxxxxxxx"
}

Update the recording config.

HTTP Request

POST https://sandbox.bandyer.com/rest/recording/config

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Required Default Description
retention_days no Specifies for how long (in days) the produced recordings are stored and are available to be collected. Allowed values are 0 <= retention <= 15 or 30, 60, 90, 120, 180, 365.
compression yes Specifies whether the recording files must be compressed. Additional charges applies.
encryption_key_id no Specifies whether the recording files must be encrypted with the specified key. You must specify a previously created and active key_id.

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
401 invalid_request_error update_config_error Impossible to update the config. Please retry
404 invalid_request_error invalid_key_error Key not found. Please check the encryption_key_id
422 invalid_request_error retention_not_allowed Invalid retention time. Allowed are 0 <= retention <= 15 or 30, 60, 90, 120, 180, 365

Encryption key

Create encryption key

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/key/create" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
         "public_key" : "-----BEGIN PUBLIC KEY-----YOUR-PEM-----END PUBLIC KEY-----"
     }'

Example Response

{
    "key_id": "pk_xxxxxxxxxxxx",
    "creation_date": "2020-09-10T07:17:42.000Z"
}

Create a public key the can be used to encrypt the recording(the encryption must be set in recording config). Use this API if you want to encrypt the files using your public key instead of a standard AWS key(AES256). Once created the key is identified by a key_id that can be used to refers to it.

The zip archive of the encrypted recording will contain:

HTTP Request

POST https://sandbox.bandyer.com/rest/key/create

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Required Default Description
public_key yes A valid PEM used to encrypt the recording

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_public_key_error Invalid public key. The public key must be a valid PEM.

Get encryption key

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/key/:key_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"

Example Response

{
    "key_id": "pk_xxxxxxxxxxxx",
    "creation_date": "2020-09-08T14:43:31.000Z"
}

Retrieves the details of the key.

HTTP Request

GET https://sandbox.bandyer.com/rest/key/:key_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
key_id yes The id of the key to retrieve

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
404 invalid_request_error invalid_key_error Key not found. Please check the key_id

Get encryption keys list

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/key/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
         "skip": X
         "limit": Y,
         "start_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
         "end_date" : "YYYY-MM-GGTHH:mm:ss.zzzZ"
     }'

Example Response

{
  "skip": 0,
  "limit": 2,
  "has_more": true,
  "count": 2,
  "keys": [
   {
       "key_id": "pk_xxxxxxxxxxxx",
       "creation_date": "2020-09-08T14:43:31.000Z"
   },
   {
       "key_id": "pk_yyyyyyyyyyyy",
       "creation_date": "2020-07-08T19:32:02.000Z"
   }
  ]
}

This end-point could be used to get basic information of all the keys a company.

The results are ordered by creation_date and can be filtered by skip, limit, start_date and end_date,

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/key/list

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Query Parameters

Parameter Required Type Default Description
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100
start_date no Date-Time Filter apply to a creation_date. creation_date greater then start_date
end_date no Date-Time Filter apply to a creation_date. creation_date lower then end_date

Error

Status Name Code Reason
400 invalid_request_error keys_list_error Impossible to retrieve keys information, please try again
401 invalid_api_key invalid_api_key Apikey is not valid

Token

As you can see in the example below, the end of the “call access link”, generated by fastcall, createroom, or broadcast, it is called “Token”. In this section, you can check the current status of the token or revoke its call access.

URL: https://xxx.bandyer.com/connect/rest-call-handler/90643787db1e7d3f

The bolded alphanumeric string is the Token.

Check token

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/token/check/:token_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

Valid token:

{
    "token": "234fds1243adada0",
    "code": "ACTIVE_TOKEN",
    "message": "token 234fds1243adada0 is valid"
}

Invalid Token:

{
    "token": "234fds1243adada0",
    "code": "NOT_ACTIVE_TOKEN",
    "message": "token 234fds1243adada0 is not valid"
}

This endpoint checks the validity of the token. Every request will reply with a code and a message that indicates the validity of the token.

HTTP Request

GET https://sandbox.bandyer.com/rest/token/check/:token_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
token_id yes “” Token to check

Delete token

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X DELETE "https://sandbox.bandyer.com/rest/token/delete/token_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "token": "234fds1243adada0",
    "message": "token 234fds1243adada0 deleted"
}

This endpoint deletes a specific token. The request will reply with a code and a message. In case of error, the message will explain the problem.

HTTP Request

DELETE https://sandbox.bandyer.com/rest/token/delete/:token_id

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Default Description
token_id yes “” Token to delete

Upload

Get upload resource

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/upload/resource" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
        "upload_key" : "sandbox/company_alias/usr_xxyyzz/1585071715613-xxxyyyzzzxxxyyyzzz"
      }'

Example Response

{
    "url": "https://upload.bandyer.com/sandbox/company_alias/usr_xxyyzz/1585071715613-xxxyyyzzzxxxyyyzzz.jpeg",
    "upload_type": "snapshot",
    "user_id": "usr_xxyyzz",
    "creation_date": "2020-01-31T15:05:49.000Z",
    "session_id": "session_a1n5bk022jg9",
    "room_id": "room_5beecf8c0f29"
}

Retrieves the details and the resource url of an existing uploaded object giving its upload_key to collect it.

upload_type can be one of file_upload, generic and snapshot

The response will be an Object containing information about the uploaded resource.

HTTP Request

GET https://sandbox.bandyer.com/rest/upload/resource

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Query Parameters

Parameter Required Type Default Description
upload_key yes String The key that identifies the uploaded resource

Error

Status Name Code Reason
404 invalid_request_error upload_key_not_exists There is no resource matching the upload_key :uploadKey.
401 invalid_api_key invalid_api_key Apikey is not valid

Get list of uploads

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/upload/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
        "upload_type" : "snapshot"
        "skip" : X,
        "limit" : Y
     }'

Example Response

{
  "skip": 0,
  "limit": 20,
  "has_more": true,
  "count": 20,
  "uploads": [
    {
      "key": "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:41:56.000Z",
      "user_id": "user_xxx",
      "session_id": "session_c1b5bc092ea2",
      "room_id": null
    },
    {
      "url": "sandbox/company/user_yyy/1585070036835-7eccda27957cf7b27d5c",
      "upload_type": "snapshot",
      "creation_date": "2020-03-24T17:13:57.000Z",
      "user_id": "user_yyy",
      "session_id": "session_a1n5bk022jg9",
      "room_id": "room_5beecf8c0f29"
    }
    ]
}

Returns a list uploaded resources for the company matching the apikey with additional information including the key of the resource to collect it using the dedicated Get upload resource api. If no uploads are present an empty list will be returned.

It is possible to filter the returned list specifying upload_type, skip and limit filter values.

HTTP Request

GET https://sandbox.bandyer.com/rest/upload/list

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Query Parameters

Parameter Required Type Default Description
upload_type no String The upload_type can be one of file_upload, generic and snapshot
skip no Number 0 Skips the first specified number items.
limit no Number 20 Limits the number of returned records to the specified number, or less if there aren’t enough. Max allowed value is 100

Response object

Parameter Type Description
skip Number The skip value passed as input
limit Number The limit value passed as input
has_more Boolean true if there are more items to fetch, false otherwise (useful to paginate results)
count Number Actual number of returned elements in uploads array
uploads Array Array of uploaded resources matching the filters ordered by creation_date (DESC)

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Delete upload

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X DELETE "https://sandbox.bandyer.com/rest/upload/resource" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
     -d '{
        "upload_key": : "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f"
     }'

Example Response

{
    "upload_key": "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f",
    "upload_type": "snapshot"
}

Delete a specific upload resource matching a key.

If the upload was not found on our systems, you will receive an error 404.

HTTP Request

DELETE "https://sandbox.bandyer.com/rest/upload/resource"

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body Parameters

Parameter Required Type Default Description
upload_key yes String The key of the upload that you want to delete

Response object

Parameter Type Description
upload_key String The key of the upload that you want to delete
upload_type String The type of the upload

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
404 invalid_request_error upload_not_found Unable to find the file specified

Tag

Get company tags

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/tag/list" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"

Example Response

{
    "tags": [
        { "tag": "tag1", "creation_date": "2019-07-16T11:06:26.000Z"},
        { "tag": "tag2", "creation_date": "2019-07-16T11:06:26.000Z"},
        { "tag": "tag3", "creation_date": "2019-07-16T11:06:26.000Z"}
    ]
}

Returns a list of the tags added for the company matching the apikey with the relative creation_date. If no tag is present an empty list will be returned.

The response will be an Object with a key tags containing an array of Objects (see the example).

HTTP Request

GET https://sandbox.bandyer.com/rest/tag/list

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Add company tags

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/tag/add"
     -H "apikey: COMPANY_APIKEY"
     -d '{
            "tags": ["tag1", "tag2", "tag3"],
        }'

Example Response

{
    "added_tags": [
        { "tag": "tag1", "creation_date": "2019-07-16T11:06:26.000Z"},
        { "tag": "tag2", "creation_date": "2019-07-16T11:06:26.000Z"},
        { "tag": "tag3", "creation_date": "2019-07-16T11:06:26.000Z"}
    ]
}

Add one or more tags to the list of company tags.

The allowed characters for tags are letters, numbers and -._ symbol. Each tag must be at least 1 character long.

Returns the list of successfully added tags. The response will be an Object with a key added_tags containing an array of Objects (see the example).

HTTP Request

POST https://sandbox.bandyer.com/rest/tag/add

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body Parameters

Parameter Required Type Default Description
tags yes Array The array of tags to add

Error

Status Name Code Reason
400 invalid_request_error invalid_tags One ore more tags contains invalid characters. Allowed characters are letters, numbers and .-_ symbols.
401 invalid_api_key invalid_api_key Apikey is not valid

Remove company tags

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/tag/remove"
     -H "apikey: COMPANY_APIKEY"
     -d '{
            "tags": ["tag1", "tag2", "tag3"],
        }'

Example Response

{
    "removed_tags": [
        { "tag": "tag1" },
        { "tag": "tag2" },
        { "tag": "tag3" }
    ]
}

Remove one or more tags from the list of company tags.

Returns the list of successfully removed tags. The response will be an Object with a key removed_tags containing an array of Objects (see the example).

HTTP Request

POST https://sandbox.bandyer.com/rest/tag/remove

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body Parameters

Parameter Required Type Default Description
tags yes Array The array of tags to remove

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

WebHooks

Configure

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X POST "https://sandbox.bandyer.com/rest/:version/hook/configure"
     -H "apikey: COMPANY_APIKEY"
     -d '
        {   "post_event_webhook_url": "https://hooks.yoursite.com/post-webhooks",
            "webhook_method": "POST"
            "webhook_filters": ["on_room_created", "on_room_deleted", "on_session_started", "on_session_ended"]
        }'

Example Response

{
    "active_webhooks": [
        {
            "post_event_webhook_url": "https://hooks.yoursite.com/post-webhooks",
            "webhook_method": "post",
            "event": "on_room_created",
            "creation_date": "2017-11-24T16:22:58.256Z"
        },
        {
            "post_event_webhook_url": "https://hooks.yoursite.com/post-webhooks",
            "webhook_method": "post",
            "event": "on_room_deleted",
            "creation_date": "2017-11-24T16:22:58.521Z"
        },
        {
            "post_event_webhook_url": "https://hooks.yoursite.com/post-webhooks",
            "webhook_method": "post",
            "event": "on_session_started",
            "creation_date": "2017-11-20T11:59:14.390Z"
        },
        {
            "post_event_webhook_url": "https://hooks.yoursite.com/post-webhooks",
            "webhook_method": "post",
            "event": "on_session_ended",
            "creation_date": "2017-11-24T16:23:00.182Z"
        }
    ]
}

The Bandyer programmable Webhooks are event callbacks that can be listened to enable the monitoring and interception of specific events happening on Bandyer through a backend service. When a callback is specified, Bandyer will make an HTTP request to the designated webhook URL. This request contains various relevant data that can be used, for example to collect statistics on usage, or to execute operations triggered by the usage of the platform.

The event type of Bandyer webhooks is “Post-Event”, which means that the event is notified after it happened on Bandyer systems. These events are notified through http requests fired from Bandyer system to the url specified during the configuration.

The event payload includes a set of relevant data depending on the event type that can be used in various ways to develop logics on the integrating system.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

POST https://sandbox.bandyer.com/rest/:version/hook/configure

Path Parameters

Parameter Required Default Description
version no v0 Version of the webhooks that you want to add (see table below for further information).

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Body Parameters

Parameter Required Type Default Description
post_event_webhook_url yes String The absolute URL where the callback should make an HTTP request for Post events.
webhook_method yes String The method for issuing the HTTP request - POST.
webhook_filters yes Array List of Webhooks to enable for this Service instance.

Post-Event Callback

Event Fired version Action that triggered
on_room_created v0 When a new room is created
on_room_disabled v0 When a room is disabled
on_room_deleted v0 When a room is deleted
on_room_new_feedback v0 When a new feedback has been left for a room
on_session_started v0, v1 When a session of a room starts
on_session_ended v0, v1 When a session of a room ends
on_session_paused v0, v1 When a session of a room is paused
on_session_resumed v0, v1 When a session of a room is resumed
on_user_connected v0 A user is connected
on_user_disconnected v0 A user is disconnected
on_call_incoming v0 When a call is created
on_call_ended v0 When a call is ended
on_recording_available v0 When a room session recording is available
on_broadcast_recording_available v0 When a broadcast session recording is available
on_broadcast_start v0 When a broadcast is started by publisher
on_broadcast_stop v0 When a broadcast stopped by publisher
on_broadcast_pub_connected v0 When the publisher is connected to a broadcast
on_broadcast_pub_disconnected v0 When the publisher is disconnected from a broadcast
on_broadcast_sub_connected v0 When a subscriber is connected to a broadcast
on_broadcast_sub_disconnected v0 When a subscriber is disconnected from a broadcast
on_broadcast_new_feedback v0 When a new feedback has been left for a broadcast
on_message_sent v1 When a new message is posted to a chat
on_upload_tag_added v1 When a new tag is added to a snapshot
on_upload_tag_removed v1 When a tag was removed from a snapshot

Webhook request parameters

Parse parameters

app.post("/hook", (req, res) => {
 // Responding 200, is important to avoid a retry logic from Bandyer system
  res.status(200).end()
  console.log(req.body) // Log the response if needed
  /*{
      event: "on_room_created",
      room_id: "room_52sdfg5sv6",
      data: '{
          "room_id": "room_52sdfg5sv6",
           "record": "false",
           "duration": 0,
           "directCall": true,
           "description": "your description",
           "user_urls": ["url1", "url2"]
      }'
  } */

  // Obtain an object representation of the data field
  const data = JSON.parse(req.body.data);
})

When Bandyer makes an HTTP request to your server, it will include contextual information related to the action that triggered the WebHook call to your backend.

In addition to the event-specific parameters, each request will also contain the following parameters and information:

Header Parameters

Room Events
Parameter Type Description
room-id-hmac String This is the HMAC base auth of Bandyer, this digest is a SHA256 of room_id cyphered by your api_key as shared secret.
Broadcast Events
Parameter Type Description
room-id-hmac String This is the HMAC base auth of Bandyer, this digest is a SHA256 of room_id cyphered by your api_key as shared secret.

Webhook payload

Parameter Type Description
event String The name of the event
room_id String The room (or broadcast) id of the event fired.
data String A stringified representation of the event data. It requires for example a JSON.parse() to transform the string in object representation

Information

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/:version/hook/"
     -H "apikey: COMPANY_APIKEY"

Example Response

{
    "active_webhooks": {
        "https://your_registered_domain.com" : [
                {
                    "webhook_method": "post",
                    "event": "on_recording_available",
                    "creation_date": "2020-09-28T09:29:59.836Z",
                    "event_version": "0"
                },
                {
                    "webhook_method": "post",
                    "event": "on_room_created",
                    "creation_date": "2020-09-28T09:29:59.838Z",
                    "event_version": "0"
                },
                {
                    "webhook_method": "post",
                    "event": "on_room_deleted",
                    "creation_date": "2020-09-28T09:29:59.839Z",
                    "event_version": "0"
                }
            ]
        }
}

This end-point could be used to get all the active webhooks on the company based on API version.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

GET https://sandbox.bandyer.com/rest/:version/hook

Header Parameters

Parameter Required Default Description
apikey yes Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
version no string v1 Version of the webhooks that you want to retrieve the information.

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

v0 - Room events

Room events data specification.

on_room_created

Data content:

Parameter Type Description
room_id String Room id of the room
record boolean Specify if the room is recorded or not
duration Number Max duration of the room
directCall boolean Specify if the url created are direct or not
description String description of the room
user_urls Array User urls of the room

on_room_disabled

Data content:

Parameter Type Description
room_id String Room id of the room
message String Room {room_id} and all user links associated disabled

on_room_deleted

Data content:

Parameter Type Description
room_id String Room id of the room
message String Room {room_id} and all user links associated deleted

on_room_new_feedback

Data content:

Parameter Type Description
room_id String Room id of the room
session_id String Session id of the room
user_id String Id of the user
rating Number Rating from 1 to 5
message String Feedback message

on_session_started

Data content:

Parameter Type Description
room_id String Room id of the room
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session started

on_session_ended

Data content:

Parameter Type Description
room_id String Room id of the room
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session ended

on_session_paused

Data content:

Parameter Type Description
room_id String Room id of the room
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session paused

on_session_resumed

Data content:

Parameter Type Description
room_id String Room id of the room
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session resumed

on_user_connected

Data content:

Parameter Type Description
user_id String Room id of the room
first_name String Firstname of the user
last_name String Lastname of the user
email String Email of the user
room.room_id String Room id of the room
room.connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of user connection

on_user_disconnected

Data content:

Parameter Type Description
user_id String Room id of the room
first_name String Firstname of the user
last_name String Lastname of the user
email String Email of the user
room.room_id String Room id of the room
room.connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of user connection

on_call_incoming

Data content:

Parameter Type Description
initiator String Id of the initiator of the call
users Array Participants of the call
room_id String Room id of the call
options.duration Number Max duration of the room
options.record boolean Specify if the room is recorded or not
options.creationDate String (ISO8601 time) Creation date of the call

on_call_ended

Data content:

Parameter Type Description
room_id String Room id of the call

on_recording_available

Data content:

Parameter Type Description
room_id String Room id of the call
session_id String Session id of the room
creationDate String (ISO8601 time) Creation date of the file

v0 - Broadcast events

Broadcast events data specification.

on_broadcast_recording_available

Data content:

Parameter Type Description
room_id String Room id of the call
session_id String Session id of the room
creationDate String (ISO8601 time) Creation date of the file

on_broadcast_start

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
session_id String Session id of the broadcast

on_broadcast_stop

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
session_id String Session id of the broadcast

on_broadcast_pub_connected

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
user_id String Id of the user

on_broadcast_pub_disconnected

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
user_id String Id of the user

on_broadcast_sub_connected

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
user_id String Id of the user

on_broadcast_sub_disconnected

Data content:

Parameter Type Description
broadcast_id String Broadcast Id of the broadcast
user_id String Id of the user

on_broadcast_new_feedback

Data content:

Parameter Type Description
broadcast_id String Broadcast id of the broadcast
session_id String Session id of the broadcast
user_id String Id of the user
rating Number Rating from 1 to 5
message String Feedback message

v1 - Sessions events

Sessions events data specification.

Security

We sign each web hook including a signature in each web hook bandyer-signature header. This allows to verify that the web hooks are sent by Bandyer and not by a third party.

The bandyer-signature header will be in the form: t=1554193902,v0=ComputedHMAC where v0 is the computed signature.

To compute the signature you must concatenate:

Example:

Input: 1554193902.{"event":"test"}

You then create an SHA256 HMAC using that string as input and the company apikey as secret key.

secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

// How to compute bandyer-signature using NodeJS

const crypto = require('crypto');

const data = {
  event: 'on_session_started',
  event_version: '1.0',
  namespace: 'session',
  data: {
    timestamp: '1554297626718',
    session_id: 'session_a1n5bk022jg9',
    room_id: 'room_5beecf8c0f29'
    connected_participants: [ // optional parameter, present for on_session_started and on_session_resumed
        'user_xxx',
        'user_yyy'
    ],
    duration: { // optional parameter, present if the call was created with the duration parameter
        total_duration: 8600
        elapsed_time: 300 // Elapsed time of the session
    }
    }
const secret = 'ak_fake_123456789';
const timestamp = '1554297654628';

const bandyerSignature = crypto.createHmac('sha256', secret).update(`${timestamp}.${JSON.stringify(data)}`).digest('hex'));

Header parameters

Parameter Type Description
bandyer-signature String example: t=1554193902,v0=ComputedHMAC

Payload

Parameter Type Description
event String Name of the event
event_version String Version of the webhook
namespace String Namespace of the webhook event
data Object The event data.

on_session_started

Data content:

Parameter Type Description
timestamp String (Unix Timestamp) Timestamp of the action performed in UTC
session_id String The session associated to the event
room_id String The room associated to the session
connected_participants String List of users that have started the session
duration String Optional parameters, present if the call was created with the duration parameter

on_session_resumed

Data content:

Parameter Type Description
timestamp String (Unix Timestamp) Timestamp of the action performed in UTC
session_id String The session associated to the event
room_id String The room associated to the session
connected_participants String List of users that have resumed the session
duration String Optional parameters, present if the call was created with the duration parameter

on_session_paused

Data content:

Parameter Type Description
timestamp String (Unix Timestamp) Timestamp of the action performed in UTC
session_id String The session associated to the event
room_id String The room associated to the session
duration String Optional parameters, present if the call was created with the duration parameter

on_session_ended

Data content:

Parameter Type Description
timestamp String (Unix Timestamp) Timestamp of the action performed in UTC
session_id String The session associated to the event
room_id String The room associated to the session
duration String Optional parameters, present if the call was created with the duration parameter

v1 - Chat events

Chat events data specification.

Security

We sign each web hook including a signature in each web hook bandyer-signature header. This allows to verify that the web hooks are sent by Bandyer and not by a third party.

The bandyer-signature header will be in the form: t=1554193902,v0=ComputedHMAC where v0 is the computed signature.

To compute the signature you must concatenate:

Example:

Input: 1554193902.{"event":"test"}

You then create an SHA256 HMAC using that string as input and the company apikey as secret key.

secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

// How to compute bandyer-signature using NodeJS

const crypto = require('crypto');

const data = {
  event: 'on_message_sent',
  event_version: '1.0',
  namespace: 'chat',
  data:
   {
        sender: 'user_xxx',
        body: 'test',
        id: 'IMzzzzzzzzzzzzzzzzzzzzzzz',
        channel_id: 'CHxxxxxxxxxxxxxxxxxxxxxxxxxx',
        participants: [ 'user_xxx', 'userr_yyy' ],
        creation_date: '2020-02-04T13:58:50.220Z',
        type: 'text',
        attributes: String
   }
const secret = 'ak_fake_123456789';
const timestamp = '1554297654628';

const bandyerSignature = crypto.createHmac('sha256', secret).update(`${timestamp}.${JSON.stringify(data)}`).digest('hex'));

Header parameters

Parameter Type Description
bandyer-signature String example: t=1554193902,v0=ComputedHMAC

Payload

Parameter Type Description
event String on_message_sent
event_version String Version of the webhook
namespace String Namespace of the webhook event
data Object The event data.

on_message_sent

Data content:

Parameter Type Description
id String Unique identifier of the message
channel_id String Unique identifier of the channel
participants Array Array of participants
body String Text of the message
type String Type of the message. Valid values: “text”
creation_date Date When message was created
sender String User alias of the creator of the message
index Number Index of the message
attributes Object Attributes of the message

v1 - Upload events

Upload events data specification.

Security

We sign each web hook including a signature in each web hook bandyer-signature header. This allows to verify that the web hooks are sent by Bandyer and not by a third party.

The bandyer-signature header will be in the form: t=1554193902,v0=ComputedHMAC where v0 is the computed signature.

To compute the signature you must concatenate:

Example:

Input: 1554193902.{"event":"test"}

You then create an SHA256 HMAC using that string as input and the company apikey as secret key.

secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

// How to compute bandyer-signature using NodeJS

const crypto = require('crypto');

const data = {
  event: 'on_upload_tag_added',
  event_version: '1.0',
  namespace: 'tag',
  data: {
    tag: 'tag1',
    upload_key: 'sandbox/cmpny_abcdefg/user_yyy/1585070036835-xxxyyyzzzxxxxyyyzzz',
    timestamp: '1554297626718',
    session_id: 'session_a1n5bk022jg9',
    room_id: 'room_5beecf8c0f29'
    }
const secret = 'ak_fake_123456789';
const timestamp = '1554297654628';

const bandyerSignature = crypto.createHmac('sha256', secret).update(`${timestamp}.${JSON.stringify(data)}`).digest('hex'));

Header parameters

Parameter Type Description
bandyer-signature String example: t=1554193902,v0=ComputedHMAC

Payload

Parameter Type Description
event String on_upload_tag_added
event_version String Version of the webhook
namespace String Namespace of the webhook event
data Object The event data.

on_upload_tag_added

Data content:

Parameter Type Description
tag String Name of the added tag
upload_key String Key of the uploaded resource that was tagged
timestamp String (Unix Timestamp) Timestamp of the action performed
session_id String The session associated to the uploaded resource
room_id String The room associated to the uploaded resource

on_upload_tag_removed

Data content:

Parameter Type Description
tag String Name of the removed tag
upload_key String Key of the uploaded resource that was un-tagged
timestamp String (Unix Timestamp) Timestamp of the action performed
session_id String The session associated to the uploaded resource
room_id String The room associated to the uploaded resource

Chat

Get chat messages

Example Request (change COMPANY_APIKEY with a valid API key and usr_xxx and usr_yyy with valid users):

curl -X GET "https://sandbox.bandyer.com/rest/chat/messages" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "users" : ["usr_xxx", "usr_yyy"],
        "order" : "asc",
        "page_number" : 1,
        "page_size" : 10,
        "page_token" : ""
     }'

Example Response

{
    "meta": {
        "page_number": 1,
        "page_size": 10,
        "page_token": "",
        "next": {
            "page_number": "2",
            "page_size": "10",
            "page_token": "PT10"
        },
        "previous": null
    },
    "messages": [
        {
            "index": 0,
            "body": "Hello",
            "from": "usr_xxx",
            "date": "2018-01-16T09:29:36.000Z",
            "type": "text"
        },
        {
            "index": 1,
            "body": "Hello",
            "from": "usr_yyy",
            "date": "2018-01-16T09:34:10.000Z",
            "type": "text"
        },
        {
            "index": 2,
            "body": "How are you doing?",
            "from": "usr_xxx",
            "date": "2018-01-16T09:40:47.000Z",
            "type": "text"
        },
        {
            "index": 3,
            "body": "Fine thanks",
            "from": "usr_yyy",
            "date": "2018-01-16T09:49:48.000Z",
            "type": "text"
        }
    ]
}

Get the chat messages exchanged between the users passed as input. The endpoint is paginated because the number of messages can increase indefinitely.

The response has a messages key containing an array of messages and a meta key that contains metadata to use to implement pagination. More specifically, there are a next and a previous keys containing the parameters to pass to obtain respectively the next and the previous page of messages.

HTTP Request

GET https://sandbox.bandyer.com/rest/chat/messages

Header Parameters

Parameter Required Description
apikey yes The API key of your company

Query Parameters

Parameter Required Default Description
users yes Array of valid user aliases.
order no “asc” The sort order of the returned messages. [asc
page_number no 0 This number is just a counter to keep track of the page number requested on the client.
page_size no 50 Max number of messages returned in a single request.
page_token no A token provided in each response to keep track of the page index requested so far. Include the token in the request obtain the subsequent page.

Error

Status Name Code Reason
400 invalid_request_error invalid_users_length Users array must contain at least two valid users.
400 invalid_request_error chat_service_disabled The chat service is not enabled for your company
400 invalid_request_error invalid_param One or more input parameters are invalid, check the error message
500 internal_server_error Something wrong happened fetching chat messages, please retry

Add chat

Example Request (change COMPANY_APIKEY with a valid API key and usr_xxx and usr_yyy with valid users):

curl -X POST "https://sandbox.bandyer.com/rest/chat/add" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "users" : ["usr_xxx", "usr_yyy"]
     }'

Example Response

{
  "chat": {
    "users": [
      "usr_xxx",
      "usr_yyy"
    ]
  },
  "message": "Chat added"
}

Create a chat between the users passed as input.

The response, specify the users passed in input, this means that the chat is created as reported in the message field with the “Chat_added” message

HTTP Request

POST https://sandbox.bandyer.com/rest/chat/add

Header Parameters

Parameter Required Description
apikey yes The API key of your company

Body Parameters

Parameter Required Default Description
users yes Array of valid user aliases.

Error

Status Name Code Reason
400 invalid_request_error invalid_users_length Users array must contain at least two valid users.
400 invalid_request_error chat_service_disabled The chat service is not enabled for your company
401 invalid_api_key invalid_api_key Apikey is not valid

Remove chat

Example Request (change COMPANY_APIKEY with a valid API key and usr_xxx and usr_yyy with valid users):

curl -X POST "https://sandbox.bandyer.com/rest/chat/remove" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "users" : ["usr_xxx", "usr_yyy"]
     }'

Example Response

{
  "chat": {
    "users": [
      "usr_xxx",
      "usr_yyy"
    ]
  },
  "message": "Chat removed"
}

Remove a chat between the users passed as input.

The response, specify the users passed in input, this means that the chat is removed as reported in the message field with the “Chat_removed” message

HTTP Request

POST https://sandbox.bandyer.com/rest/chat/remove

Header Parameters

Parameter Required Description
apikey yes The API key of your company

Body Parameters

Parameter Required Default Description
users yes Array of valid user aliases.

Error

Status Name Code Reason
400 invalid_request_error invalid_users_length Users array must contain at least two valid users.
400 invalid_request_error chat_service_disabled The chat service is not enabled for your company
400 invalid_request_error chat_not_found Chat not found for the given users.
400 invalid_request_error remove_chat_error Unable to remove the chat, check the users and retry
401 invalid_api_key invalid_api_key Apikey is not valid

Send message

Example Request (change COMPANY_APIKEY with a valid API key and usr_xxx and usr_yyy with valid users):

curl -X POST "https://sandbox.bandyer.com/rest/chat/add" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "users" : ["usr_xxx", "usr_yyy"],
        "sender" : "usr_xxx",
        "message" : "test message"
     }'

Example Response

{
  "users": [
    "usr_xxx",
    "usr_yyy"
  ],
  "sender": "usr_xxx",
  "index": 1,
  "message": "test message",
  "timestamp": "2020-01-21T11:42:22.000Z"
}

Send a message from a given user, in a specified channel

The response, specify the users passed in input, the sender who send the message, in addition to the text of the message there is the index and the timestamp

HTTP Request

POST https://sandbox.bandyer.com/rest/chat/messages

Header Parameters

Parameter Required Description
apikey yes The API key of your company

Body Parameters

Parameter Required Default Description
users yes Array of valid user aliases.
sender yes Who send the message.
message yes Text of the message.

Error

Status Name Code Reason
400 invalid_request_error invalid_users_length Users array must contain at least two valid users.
400 invalid_request_error user_not_a_member The given sender is not a member of the specified channel, please check the users.
400 invalid_request_error chat_service_disabled The chat service is not enabled for your company.
400 invalid_request_error send_message_error Chat service error, unable to send message, retry.
401 invalid_api_key invalid_api_key Apikey is not valid

Activities

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/activity" \
  -H "apikey: COMPANY_APIKEY" \
  -d '{
        "filter" : [
        {
            "limit": X,
            "skip" : Y,
            "date_from" : "YYYY-MM-DD:HH:mm:sssZ",
            "date_to" : "YYYY-MM-DD:HH:mm:sssZ",
            "activity_type" : "activity_type",
            "user_alias" : "user_id",
            "room_alias": "room_id"
        }
            ]
      }'

Example Response

{
    "activities": [
        {
            "activity_type": "user_connection",
            "creation_date": "2019-02-11T11:23:28.610Z",
            "user_alias": "usr_aaaaaaaaaaaa"
        },
        {
            "activity_type": "user_connection",
            "creation_date": "2019-02-11T11:23:21.223Z",
            "user_alias": "usr_bbbbbbbbbbbb"
        },
        {
            "activity_type": "user_start_call",
            "creation_date": "2019-02-11T11:01:11.415Z",
            "user_alias": "usr_aaaaaaaaaaaa",
            "room": {
                "room_alias": "room_xxxxxxxxxxx",
                "recording": false,
                "users": [
                    "usr_aaaaaaaaaaaa",
                    "usr_bbbbbbbbbbbb"
                ],
                "initiator": "usr_aaaaaaaaaaa",
                "call_type": "audio_video"
            }
        },
        {
            "activity_type": "user_dial_incoming",
            "creation_date": "2019-02-11T11:01:11.448Z",
            "user_alias": "usr_bbbbbbbbbbbb",
            "room": {
                "room_alias": "room_xxxxxxxxxxx",
                "recording": false,
                "users": [
                    "usr_aaaaaaaaaaaa",
                    "usr_bbbbbbbbbbbb"
                ],
                "initiator": "usr_aaaaaaaaaaa",
                "call_type": "audio_video"
            }
        },
        {
            "activity_type": "user_dial_timeout",
            "creation_date": "2019-02-11T11:32:32.465Z",
            "user_alias": "usr_bbbbbbbbbbbb",
            "room": {
                "room_alias": "room_xxxxxxxxxxx",
                "recording": false,
                "users": [
                    "usr_aaaaaaaaaaaa",
                    "usr_bbbbbbbbbbbb"
                ],
                "initiator": "usr_aaaaaaaaaaa",
                "call_type": "audio_video"
            }
        },
        {
            "activity_type": "user_room_ended",
            "creation_date": "2019-02-11T11:06:22.649Z",
            "user_alias": "usr_xxxxxxxxxxxx",
            "room": {
                "room_alias": "room_xxxxxxxxxxx",
                "recording": false,
                "users": [
                    "usr_aaaaaaaaaaaa",
                    "usr_bbbbbbbbbbbb"
                ],
                "initiator": "usr_aaaaaaaaaaa",
                "call_type": "audio_video"
            }
        }
    ]
}

This endpoint is used to retrieve the activities carried out in Bandyer SDK integration project. It returns a list of activities that can be filtered thanks to filter query param. The response, as you can see in sample response, will be an array of activity JSON object.

This endpoint is used to retrieve the activities carried out into the Bandyer SDK integration project. It returns a list of activities that can be filtered thanks to the filter query parameter. As you can see in sample response, it will be an array of activity JSON object.

Note: All date’s fields follow the ISO8601 standard.

HTTP Request

POST https://sandbox.bandyer.com/rest/activity

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Body Parameters

Parameter Required Default Description
filter[limit] no 0 The limit number of array elements as response.
filter[skip] no 0 The number of skipped elements.
filter[date_from] no 0 The activities date from
filter[date_to] no 0 The activities date to
filter[user_alias] no 0 The activities of the user alias specified
filter[room_alias] no 0 The activities of the room alias specified
filter[activity_type] no 0 The activities with type specified (look in the section below)

Available Activities

Activity Type Activity Description
user_connection When a user is connected to SDK server
user_disconnection When a user is disconnected from SDK server
user_start_call When a user is started a call
user_dial_incoming When a user is received a dial incoming event
user_dial_timeout When the max dialing timeout is fired from the server
user_answer When the user is answered an incoming call
user_hangup When the user is declined an incoming call
user_call_in When the user is joined a call after an answer action
user_call_out When the user left a call
user_room_ended When the room call is ended

Errors

Bandyer uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with Bandyer’s servers (these are rare).

Status Messagge Reason
400 Invalid Api Key The specified Api Key is not valid.
400 Invalid request error The request is malformed.
422 Validation error The request has invalid parameters.
500 General error Generic error.

Fast Call (@Deprecated)

This is the fastest way to make calls, a single REST is enough for each user who will be on the call.

Note: With this type of call, you cannot specify a maximum call duration and you cannot listen to related webhooks.

Note: These REST calls will generate links for users, to check the status of a generated link or to block the access, see the Token section.

IMPORTANT This endpoint will be deprecated very soon. Please refer to Room - Create.

Init a One To One

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/call/:caller" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
       "callee" : "callee_id",
       "record" : "0"
     }'

Example Response

{
  "url":"https://xxx.bandyer.com/connect/rest-call-handler/e09cada3684beb2b"
}

To start a videocall, the user needs to be redirect in a specific Bandyer page. In the request the user must specify the id of the user to call.

He could also choose whether to record or not the videocall session.

The response returns the url in which the user must be redirected. The user called (callee) must make the same specular request.

Note: Within the sandbox server, calls won’t be registered even if indicated in the REST parameters. If you would like to try the recording option in sandbox, please contact us at support.

E.G. : User with id usr_example_1 call user with id usr_example_2.

The usr_example_1 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_1?callee=usr_example_2&record=0);

The usr_example_2 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_2?callee=usr_example_1&record=0);

With the url given by the request they will be able to start the videocall.

HTTP Request

GET https://sandbox.bandyer.com/rest/call/:caller

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
caller yes String “” The id of the user who makes the call.

Query Parameters

Parameter Required Type Default Description
callee yes String “” The id of the user to call.
record no String “” 1 if the user wants to record the videocall, 0 otherwise.

Init a Conference

Example Request (change COMPANY_APIKEY with a valid API key):

curl -X GET "https://sandbox.bandyer.com/rest/call/:caller" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
       "callee" : "callee_id",
       "record" : "X"
     }'

Example Response

{
  "url":"https://xxx.bandyer.com/connect/rest-call-handler/e09casda3684beb2b"
}

To start a conference, the users need to be redirect in a specific Bandyer page.

In the request the user must specify the id of the users to call. The users’ id list must be comma separated. The order of the users’ id in not relevant.

The user could also choose whether to record or not the conference session. The response returns the url in which the users must be redirected. The other users must make the specular request.

Note: Within the sandbox server, calls won’t be registered even if indicated in the REST parameters. If you would like to try the recording option in sandbox, please contact us at support.

E.G. : Conference between usr_example_1 call, id usr_example_2, usr_example_3, usr_example_4.

The usr_example_1 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_1?callee=usr_example_2,usr_example_3,usr_example_4&record=0);

The usr_example_2 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_2?callee=usr_example_1,usr_example_3,usr_example_4&record=0);

The usr_example_3 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_3?callee=usr_example_1,usr_example_2,usr_example_4&record=0);

The usr_example_4 makes the request (https://sandbox.bandyer.com/rest/call/usr_example_4?callee=usr_example_1,usr_example_2,usr_example_3&record=0);

With the url given by the request they will be able to start the videocall.

HTTP Request

GET https://sandbox.bandyer.com/rest/call/:caller

Header Parameters

Parameter Required Default Description
apikey yes “” Every request must have the API Key.

Url Parameters

Parameter Required Type Default Description
caller yes String “” The id of the user who makes the call.

Query Parameters

Parameter Required Type Default Description
callee yes String “” An array of the users’ id to call.
record no String “” 1 if the user wants to record the videocall, 0 otherwise.