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",
            "background_alias":"bhh6e578edda35kj9d0fa8bb5876a524",
            "end_call_redirect_url" : "https://bandyer.com",
            "end_call_redirect_timeout_ms": 5000,
            "user_details_provider_url": "https://yourcustom.endpoint.com"
        }'

Example Response

{
    "company": {
        "name": "Test Company",
        "default_language": "it",
        "default_background":{
            "background_alias": "bhh6e578edda35kj9d0fa8bb5876a524",
            "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/bhh6e578edda35kj9d0fa8bb5876a524.jpeg",
            "creation_date": "2020-12-23T15:14:16.000"
        },
         "end_call_redirect_url" : "https://bandyer.com",
         "end_call_redirect_timeout_ms": 5000,
         "user_details_provider_url": "https://yourcustom.endpoint.com"
    }
}

Update name and/or the default language and/or default background 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”, “it”, “de”, “fr” or “pl”.
background_alias String no Default background of the company. You can get one using the upload company background API
end_call_redirect_url String no The url to redirect the user to at the end a call. It must be a valid url or null to disable the functionality. N.B: it applies only in browser integrations
end_call_redirect_timeout_ms Number no The delay in milliseconds after which redirect the user to the end_call_redirect_url if defined.
user_details_provider_url string no The endpoint called by Bandyer to obtain the details of the users. More Here

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 company name. Allowed chars are alphanumeric and #&@’.,?!
422 validation_error invalid_language Invalid language. The allowed languages are “en”, “it”, “de” “fr” or “pl”
422 validation_error invalid_background_alias Invalid background. The background inserted was not found
422 validation_error invalid_end_call_redirect_url Invalid end_call_redirect_url. The parameter is not a valid URL
422 validation_error invalid_end_call_redirect_timeout_ms The end_call_redirect_timeout_ms must be between 0 and 60000 ms (60 seconds)
422 validation_error invalid_user_details_provider_url Invalid user_details_provider_url. The parameter is not a valid URL

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"|
     -F "theme='dark'"

Example Response

{
    "logo_url": "https://static.bandyer.com/corporate/logos/logo_company_light.png",
    "logo_dark_url": "https://static.bandyer.com/corporate/logos/logo_company_dark.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 300x300 pixels.
theme String no ‘all’ The theme to which the provided logo will be associated. Allowed params are light, dark, all.

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
422 validation_error invalid_company_logo_theme Allowed values for theme are: all, light and dark

Upload company background

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

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

Example Response

{
    "virtual_background": {
        "background_alias": "bhh6e578edda35kj9d0fa8bb5876a524",
        "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/bhh6e578edda35kj9d0fa8bb5876a524.jpeg",
        "creation_date": "2020-12-23T15:14:16.000"
    }
}

Upload a virtual background for a company that ypu can use in call (Call page or Widget). There is a maximum of 10 per company.

You can set your default background using Update company

The image provided must have a minimum size of 1280x1280. The max size allowed is 16MB per file. The request will return the company virtual background image URL, the alias and the creation date.

HTTP Request

POST https://sandbox.bandyer.com/rest/company/virtual-background

Header Parameters

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

Body Parameters (form-data)

Parameter Type Required Default Description
virtual_background File yes The company background image. The mime-type must be image/jpg or image/jpeg.
Max file size is 16MB. Suggested dimensions are 1280x1280 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
400 invalid_request_error exceeded_background_limit The company reached the maximum background limit of 10
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 'virtual_background’ param and the file validity (allowed extensions are jpeg/jpg).
422 validation_error wrong_file_dimension Wrong dimensions, the file must be at least 1280 x 1280
422 validation_error error_processing_image Error while processing the image, check the logo and retry

Delete company background

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

curl -X DELETE "https://sandbox.bandyer.com/rest/company/virtual-background" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -F "background_alias=bhh6e578edda35kj9d0fa8bb5876a524"

Example Response

{
    "virtual_background": {
        "background_alias": "bhh6e578edda35kj9d0fa8bb5876a524",
        "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/bhh6e578edda35kj9d0fa8bb5876a524.jpeg",
        "creation_date": "2020-12-23T15:14:16.000"
    }
}

Delete a virtual background for a company.

The background alias provided must belong to the company. The request will return the alias of the background deleted.

HTTP Request

DELETE https://sandbox.bandyer.com/rest/company/virtual-background

Header Parameters

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

Body Parameters

Parameter Type Required Default Description
background_alias File yes The company background alias. This will be available after a successful upload.

Error

Status Name Code Reason
400 invalid_request_error error_background_alias Invalid background. The background alias provided belongs to a different company
401 invalid_api_key invalid_api_key Apikey is not valid.
404 invalid_request_error company_not_found Company not found
404 invalid_request_error background_not_found Background not found

Get company backgrounds

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

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

Example Response

{
    "virtual_backgrounds": {
        "default_background": {
            "background_alias": "bhh6e578edda35kj9d0fa8bb5876a524",
            "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/bhh6e578edda35kj9d0fa8bb5876a524.jpeg",
            "creation_date": "2020-12-23T15:14:16.000"
        },
        "backgrounds": [
            {
                "background_alias": "bhh6e578edda35kj9d0fa8bb5876a524",
                "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/bhh6e578edda35kj9d0fa8bb5876a524.jpeg",
                "creation_date": "2020-12-23T15:14:16.000"
            },
            {
                "background_alias": "olp6e578edda98lo9d0fa5ll5876a012",
                "url": "https://static.bandyer.com/corporate/virtual_backgrounds/sandbox/company_alias/olp6e578edda98lo9d0fa5ll5876a012.jpeg",
                "creation_date": "2020-12-23T15:14:16.000"
            }
        ]
    }
}

Get all virtual backgrounds for a company.

The request will return an object containing all the backgrounds and the default background.

HTTP Request

GET https://sandbox.bandyer.com/rest/company/virtual-backgrounds

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.
404 invalid_request_error company_not_found Company not found

Get company theme

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

curl -X GET "https://sandbox.bandyer.com/rest/company/theme" \
     -H "apikey: COMPANY_APIKEY"

Example Response

{
    "theme": {
        "light": {
            "primary_color": "#009fe3",
            "accent_color": "#009fe3"
        },
        "dark": {
            "primary_color": "#009fe3",
            "accent_color": "#009fe3"
        }
    }
}

List the current configured theme colors.

HTTP Request

GET https://sandbox.bandyer.com/rest/company/theme

Header Parameters

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

Response Object

Parameter Type Description
light Object the theme object specifying the primary_color and the accent_color for the light mode
dark Object the theme object specifying the primary_color and the accent_color for the dark mode

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

Update company theme

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

curl -X POST "https://sandbox.bandyer.com/rest/company/theme" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
           "light": {
                "primary_color": "#009fe3",
                "accent_color": "#009fe3"
           },
           "dark": {
                 "primary_color": "#009fe3",
                 "accent_color": "#009fe3"
           }
        }'

Example Response

{
    "theme": {
        "light": {
            "primary_color": "#009fe3",
            "accent_color": "#009fe3"
        },
        "dark": {
            "primary_color": "#009fe3",
            "accent_color": "#009fe3"
        }
    }
}

Update the theme colors configuration.

HTTP Request

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

Header Parameters

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

Body Parameters

Parameter Type Required Default Description
light Object or null no the theme object specifying the primary_color and the accent_color for the light mode. If null, the light mode configuration is reset to the default values.
dark Object or null no the theme object specifying the primary_color and the accent_color for the dark mode. If null, the dark mode configuration is reset to the default values.

Light and dark object parameters

Parameter Type Required Default Description
primary_color String no The primary color expressed in HEX format (e.g. #CCCCCC).
accent_color String no The accent color expressed in HEX format (e.g. #CCCCCC).

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 missing_theme Please forward at least one theme object(light/dark)
422 validation_error invalid_end_call_redirect_url One of the required colors are missing in the light or dark object
422 validation_error invalid_theme_color Invalid color format in the light or dark object. Please specify a color like #CCCCCC

Update company translation

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

curl -X POST "https://sandbox.bandyer.com/rest/company/translation" \
        -H "apikey: COMPANY_APIKEY" \
          -H "Content-Type: multipart/form-data" \
          -F "translation=@/YOUR_LOCAL_TRANSLATION_PATH/en.json;type=application/json"|
          -F "language='en'"

Example Response

{
    "translation": {
        "url": "https://static.bandyer.com/corporate/translations/sandbox/company_alias/en.json",
        "language": "en"
    }
}

Update a specific language translation in the call page.

You can modify all the translations or only few of them, please take care about the 'keys’, different keys will not be managed.

HTTP Request

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

Header Parameters

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

Body Parameters (form-data)

Parameter Type Required Default Description
translation json file yes JSON file contains the key:value pair of the translations
language string yes specify the translations language, allowed languages are 'en’, 'it’, 'de’, 'fr’, 'pl’

Error

Status Name Code Reason
400 invalid_request_error file_not_found The file provided must be a multipart file.
400 invalid_request_error upload_error Unable to upload your file, please retry.
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_file Please check the file.
422 validation_error invalid_language Invalid language. The allowed languages are it, en, de or pl.

List company translation

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

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

Example Response

{
    "translations": [
        {
            "url": "https://static.bandyer.com/corporate/translations/sandbox/company_alias/en.json",
            "language": "en"
        },
        {
            "url": "https://static.bandyer.com/corporate/translations/sandbox/company_alias/it.json",
            "language": "it"
         }
    ]
}

Get all the uploaded translations.

HTTP Request

GET https://sandbox.bandyer.com/rest/company/translation/list

Header Parameters

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

Error

Status Name Code Reason
400 invalid_request_error translations_error Error in getting the translations file, please retry
401 invalid_api_key invalid_api_key Apikey is not valid

Delete company translation

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

curl -X DELETE "https://sandbox.bandyer.com/rest/company/translation" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"
       -d '{
             "language" : "en",
            }'

Example Response

{
    "translation":
        {
            "language": "en"
        }
}

Delete a specific language translation

HTTP Request

DELETE https://sandbox.bandyer.com/rest/company/translation

Header Parameters

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

Body Parameters

Parameter Type Required Default Description
language string yes specify the translations language, allowed languages are 'en’, 'it’, 'de’, 'fr’, 'pl’

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_language Invalid language. The allowed languages are it, en, de or pl.

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",
    "creation_date": "2019-10-21T11:09:00.000Z"
  },
  "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”, “it”, “de”, “fr” or “pl”.

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",
          "role": "basic"
     }'

Example Response

{
  "user": {
    "id": "usr_5b63a42e7ec2",
    "role": "basic",
    "active": true,
    "can_video": true,
    "language": "it",
    "firstName": "Jane",
    "lastName": "Doe",
    "nickname": "jane.doe",
    "email": "john@doe.com",
    "creation_date": "2019-10-21T11:09:00.000Z"
  }
}

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 The user’ video publishing permission.
language no Language of the user. Available options are “en”, “it”, “de”, “fr” or “pl”.
role no Role of the user. Available option are “basic” or “plus”
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

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",
    "creation_date": "2019-10-21T11:09:00.000Z"
  }
}

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 in seconds 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"}],
         "recording": true,
         "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/connect/rest-call-handler/aaaaaaaaaa",
                "tools": {
                    "screen_sharing": false,
                    "whiteboard": false,
                    "chat": true,
                    "file_upload": false,
                    "live_edit": false,
                    "snapshot": false,
                    "live_pointer": false,
                    "present_to_everyone": false,
                    "sign": false
                    },
                "is_admin": true
            },
            {
                "user": "usr_yyy",
                "url": "https://sandbox.bandyer.com/connect/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,
                    "present_to_everyone": true,
                    "sign": 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 seconds.

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
recording no Boolean false This param defines whether the room should be recorded or not.
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 seconds. 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

Parameter Deprecation date Required Type Default Description
user_list_in_call 07/04/20 no Array The array of the user alias that will participate to the room.
record 01/07/21 no String “0” This param defines whether the room should be recorded “1” or not “0”.

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,
            "present_to_everyone": true,
            "sign": 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)
present_to_everyone Enable the capability to force your own video to be featured for other participants
sign If the user have the capability enabled, this flag allow to create a new sign process. Visit digital signature section for more information. (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

Get room envelopes list

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

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

Example Response

{
      "skip": 1,
      "limit": 2,
      "has_more": true,
      "count": 2,
      "envelopes": [
          {
              "id": "envelope_2f541b80acce",
              "friendly_name": "Envelope 1",
              "room_id": "room_c54a05293287",
              "session_id": "session_46b875303b96",
              "status": "failed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-23T12:55:31.587Z",
              "updated_at": "2021-08-23T12:55:31.587Z"
          },
          {
              "id": "envelope_9c7cb9bdff7f",
              "friendly_name": "Envelope 2",
              "room_id": "room_c54a05293287",
              "session_id": "session_d3106e6291b2",
              "status": "completed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-24T07:05:14.764Z",
              "updated_at": "2021-08-24T07:05:14.764Z"
          }
      ]
  }

This end-point return a list of envelopes for a specific room, each envelope contains all the information about the room and session during which an envelope has been signed and the users involved in the process. The id of the envelope can be used later to retrieve more information related to the document and the signed document also.

HTTP Request

GET https://sandbox.bandyer.com/rest/room/:room_id/envelope/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
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

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Customization

Query strings

// How to use the query strings
https://sandbox.bandyer.com/connect/direct-rest-call-handler/aaaaaaaaaa?ad=true&vd=true&dn=My%20Custom%20name

Query string can be used to customise various options for a given link

Parameter Short form Type Description
audio_disabled ad Boolean Start the call with the audio disabled.
video_disabled vd Boolean Start the call with the video disabled.
swapped_local_camera slc Boolean Start the call with the local video featured.
mobile_back_camera mbc Boolean tart the call with the back camera selected as default video device on mobile browsers.
display_name dn String Set the name to display in the call. The name is also forwarded to the other participants.
virtual_background vb String tart the call with the virtual background enabled as default. Allowed parameters are blur or image.
language l String Set the language of the UI. Allowed parameters are en, it, pl, fr and de
theme t String Allow to start the call with the chosen theme (if specified here), allowed parameters are light, dark

Remote user details provider

The user details provider allows to customize the name of the participants to display during the call instead of the user_id. To enable this functionality you must specify a valid user_details_provider_url through the company update rest API This url, if defined, is used by Bandyer as an endpoint to request the details of the participants of the call through an http post request.

Bandyer signature

When Bandyer makes the HTTP requests to your server, it will also include a signature, computed using the company apikey as secret, that allows you to verify that the content of the request comes from a legitimate source and that hasn’t been tampered in any way. Such signature is included in the bandyer-signature header specified in each request sent by Bandyer to the user_details_provider_url.

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

To check the signature to validate the request on you side you must compute the signature by concatenating:

t value (as a string) the character . The actual JSON payload (i.e the request body) Example:

Input: 1554193902.{event: ‘provider’, event_version: '1.0’, namespace: 'provider’, data: { usersAlias: […'alias’] } }

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

e.g secret key: ak_live_123456 → SHA256 HMAC: 6841e55cb12f2d9d1216c47097c75fd737a22a3a00c8d8f8d3d35fb2b613ce5b

// How to compute bandyer-signature using NodeJS

const crypto = require('crypto');

const requestBody = {
  event: 'user_details_request',
  event_version: '1.0',
  namespace: 'user_details_provider',
  data: {
    users_id: ['user_xxx', 'user_yyy'],
  }
}

const secret = 'ak_fake_123456789'; // you secret apikey
const timestamp = '1554297654628'; // extracted from the request header

const bandyerSignature = crypto.createHmac('sha256', secret).update(`${timestamp}.${JSON.stringify(requestBody)}`).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 (in this case: user_details_request)
event_version String Version of the request payload (In this case: 1.0)
namespace String Namespace of the webhook event (In this case: user_details_provider)
data Object The event data

data

Parameter Type Description
user_ids Array of string list of user_id that participate to the call

The request expects a response structured as follow:

Response

Example Response

{
    "user_ids": [
            {
                "user_id": "user_xxx",
                "display_name": "Custom display name",
                "user_avatar": "https://customurl.com/customImage.jpg"

            },
            {
                "user_id": "user_yyy",
                "display_name": "Custom display name 2",
                "user_avatar": "https://customurl.com/customImage2.jpg"
            }
    ]
}
Parameter Type Description
user_ids Array of object Array of user objects containing the information obtained from your server

user_ids object

Parameter Type Description
user_id string the user_id passed in the request identifying the user
display_name String the name to display instead of the user_id during the call
user_avatar Array of object the url of the image to use as avatar for the user during the call. NB: the link must be publicly accessible to work

Priority system

The user details provider feature is fully integrated with the other logics that allow to specify a custom name or a custom avatar for the user. The following list shows the priority of the logics applied to display the user name from the highest to the lowest. The first logic that applies is order is the one that will be used to display the user name.

Priority System
3 The display_name quesy parameter. NB: this logic allows to specify only the name of the owner of the link, and not those of the other participants.
2 Provider and formatter for the SDKs and the widget (it is strongly suggested to centralize the provider for both the SDK and the links).
1 Remote user provider (seen above).
0 Information stored on the user, specified using the /rest/user/create or the /rest/user/update APIs (Deprecated).

Theme customization

With the update company theme API is possible to specify custom colors for the two theme modes of the call page.

Following there are some guidelines that show you where the colors are applied so that you can choose the ones that best represent your business

Call and chat UI

Screenshare UI

Upload file UI

Notification UI

Toggle between theme modes

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 15), 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 15 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 15.

Add panelists

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

curl -X POST "https://sandbox.bandyer.com/rest/broadcast/:broadcast_id/panelists/add" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "panelists": [{"user_id" : "usr_yyy"}, {"user_id" : "usr_zzz"}]
     }'

Example Response

{
  "broadcast_id": "bro_beefa9f45545",
  "panelists": [
      {
          "user_id": "usr_xxx"
      },
      {
          "user_id": "usr_yyy"
      },
      {
          "user_id": "usr_zzz"
      }
  ]
}

The panelists are the co-presenters of the events (Up to 15), each of them can be broadcasted by the publisher.

The endpoint accepts a list of panelists in ingress and returns a list of all the panelists for the broadcast.

For each of them you need to call the link generation method

HTTP Request

POST https://sandbox.bandyer.com/rest/broadcast/:broadcast_id/panelists/add

Header Parameters

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

Body parameters

Parameter Required Type Default Description
panelists yes Array Lists of co-presenters that can be broadcasted by the publisher. Up to 15 panelists.

Error

Status Name Code Reason
400 invalid_request_error broadcast_not_found Check the broadcast id
400 invalid_request_error invalid_user_id Invalid user id for panelists
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_panelist One of the user is already a publisher, cannot change the role to panelist
422 validation_error invalid_panelists_count Unable to add more panelists. Max allowed panelists count is 15.

Remove panelists

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

curl -X POST "https://sandbox.bandyer.com/rest/broadcast/:broadcast_id/panelists/remove" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "panelists": ["user_zzz", "user_yyy"]
     }'

Example Response

{
  "broadcast_id": "bro_beefa9f45545",
  "panelists": [
      {
          "user_id": "usr_xxx"
      }
  ]
}

The panelists are the co-presenters of the events (Up to 15), each of them can be broadcasted by the publisher.

The endpoint accepts a list of panelists in ingress and returns a list of the current panelists for the broadcast.

HTTP Request

POST https://sandbox.bandyer.com/rest/broadcast/:broadcast_id/panelists/remove

Header Parameters

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

Body parameters

Parameter Required Type Default Description
panelists yes Array Lists of co-presenters that can be broadcasted by the publisher. Up to 15 panelists.

Error

Status Name Code Reason
400 invalid_request_error broadcast_not_found Check the broadcast id
400 invalid_request_error invalid_user_id Invalid user id for panelists
401 invalid_api_key invalid_api_key Apikey is not valid

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"
        },
        "panelists": [{ "user_id": "usr_123bnm79c987"}],
        "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 in seconds 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 in seconds 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

Get session envelopes list

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

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

Example Response

{
      "skip": 1,
      "limit": 2,
      "has_more": true,
      "count": 2,
      "envelopes": [
          {
              "id": "envelope_2f541b80acce",
              "friendly_name": "Envelope 1",
              "room_id": "room_c54a05293287",
              "session_id": "session_46b875303b96",
              "status": "failed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-23T12:55:31.587Z",
              "updated_at": "2021-08-23T12:55:31.587Z"
          },
          {
              "id": "envelope_9344-9c7cb9bdff7f",
              "friendly_name": "Envelope 2",
              "room_id": "room_c54a05293287",
              "session_id": "session_46b875303b96",
              "status": "completed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-24T07:05:14.764Z",
              "updated_at": "2021-08-24T07:05:14.764Z"
          }
      ]
  }

This end-point return a list of envelopes for a specific session, each envelope contains all the information about the room and session during which an envelope has been signed and the users involved in the process. The id of the envelope can be used later to retrieve more information related to the document and the signed document also.

HTTP Request

GET https://sandbox.bandyer.com/rest/session/:session_id/envelope/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
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

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

Digital signature

This section is dedicated to the configuration of the digital signature integrated inside a Bandyer’s call.

The following APIs allow you to create/update/delete and list the document templates that you can use in the call. You can fetch all the envelopes already created and check its status.

Create document template

A document template describe what are the tags that the signature system will search on the document to apply the signing markers that the signer can then check to apply the signature during the call.

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

curl -X POST "https://sandbox.bandyer.com/rest/sign/template" \
     -H 'apikey: COMPANY_APIKEY' \
     -d '{
        "friendly_name": "Contract ABC"
        "sign_coordinates": [
                {"start_tag_pattern": "$$BandyerSignature1", "x_offset": -100, "y_offset": -150},
                {"start_tag_pattern": "$$BandyerSignature2", "x_offset": 100, "y_offset": -50},
                {"start_tag_pattern": "$$BandyerSignature3", "x_offset": 50, "y_offset": -150}]
     }'

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract ABC",
         "sign_coordinates": [
             {
                 "start_tag_pattern": "$$BandyerSignature1",
                 "x_offset": 0,
                 "y_offset": 0
             },
             {
                 "start_tag_pattern": "$$BandyerSignature2",
                 "x_offset": 100,
                 "y_offset": -50
             },
             {
                 "start_tag_pattern": "$$BandyerSignature3",
                 "x_offset": 50,
                 "y_offset": -150
             }
         ],
         "creation_date": "2021-08-24T07:18:18.508Z",
         "updated_at": "2021-08-24T07:18:18.508Z"
     }
}

This end-point can be used to create a template for a document to sign. The sign_coordinates array contains the list of tags that must be in the pdf uploaded during the call.

The x and y offsets allow to align the signature in the final signed document.

HTTP Request

POST https://sandbox.bandyer.com/rest/sign/template

Header Parameters

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

Query Parameters

Parameter Required Type Default Description
friendly_name yes String Defines the name of the template that is shown during the call
sign_coordinates yes Array Defines the list of tags that must mach the tags contained in the uploaded file

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_sign_coordinates_format One or more objects in the sign_coordinates array have invalid format

Get document template

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

curl -X GET "https://sandbox.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY'

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract ABC",
         "sign_coordinates": [
             {
                 "start_tag_pattern": "$$BandyerSignature1",
                 "x_offset": 0,
                 "y_offset": 0
             },
             {
                 "start_tag_pattern": "$$BandyerSignature2",
                 "x_offset": 100,
                 "y_offset": -50
             },
             {
                 "start_tag_pattern": "$$BandyerSignature3",
                 "x_offset": 50,
                 "y_offset": -150
             }
         ],
         "creation_date": "2021-08-24T07:18:18.508Z",
         "updated_at": "2021-08-24T07:18:18.508Z"
     }
}

This end-point returns the template matching a valid template_id.

HTTP Request

GET https://sandbox.bandyer.com/rest/sign/template/:template_id

Header Parameters

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

Url Parameters

Parameter Required Type Default Description
template_id yes String Id of a valid template

Error

Status Name Code Reason
400 invalid_request_error template_not_found Template not found. Check your template id
401 invalid_api_key invalid_api_key Apikey is not valid

Update document template

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

curl -X POST "https://sandbox.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY' /
     -d '{
         "friendly_name": "Contract 123"
         "sign_coordinates": [
                 {"start_tag_pattern": "$$BandyerSignature1", "x_offset": -100, "y_offset": -150},
                 {"start_tag_pattern": "$$BandyerSignature2", "x_offset": 100, "y_offset": -50},
                 {"start_tag_pattern": "$$BandyerSignature3", "x_offset": 50, "y_offset": -150}]
         }'

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract 123",
         "sign_coordinates": [
             {
                 "start_tag_pattern": "$$BandyerSignature1",
                 "x_offset": 0,
                 "y_offset": 0
             },
             {
                 "start_tag_pattern": "$$BandyerSignature2",
                 "x_offset": 100,
                 "y_offset": -50
             },
             {
                 "start_tag_pattern": "$$BandyerSignature3",
                 "x_offset": 50,
                 "y_offset": -150
             }
         ],
         "creation_date": "2021-08-24T07:18:18.508Z",
         "updated_at": "2021-08-24T07:18:18.508Z"
     }
}

This end-point allows to update a specific template matching the template_id.

HTTP Request

POST https://sandbox.bandyer.com/rest/sign/template/:template_id

Header Parameters

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

Url Parameters

Parameter Required Type Default Description
template_id yes String Id of a valid template

Query Parameters

Parameter Required Type Default Description
friendly_name no String Defines the name of the template that is shown during the call
sign_coordinates no Array Defines the list of tags that must mach the tags contained in the uploaded file

Error

Status Name Code Reason
400 invalid_request_error template_not_found Template not found. Check your template id
401 invalid_api_key invalid_api_key Apikey is not valid
422 validation_error invalid_sign_coordinates_format One or more objects in the sign_coordinates array have invalid format

Delete document template

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

curl -X DELETE "https://sandbox.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY'

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract 123",
         "sign_coordinates": [
             {
                 "start_tag_pattern": "$$BandyerSignature1",
                 "x_offset": 0,
                 "y_offset": 0
             },
             {
                 "start_tag_pattern": "$$BandyerSignature2",
                 "x_offset": 100,
                 "y_offset": -50
             },
             {
                 "start_tag_pattern": "$$BandyerSignature3",
                 "x_offset": 50,
                 "y_offset": -150
             }
         ],
         "creation_date": "2021-08-24T07:18:18.508Z",
         "updated_at": "2021-08-24T07:18:18.508Z"
     }
}

This end-point allow to remove a specific template that match the template_id.

HTTP Request

DELETE https://sandbox.bandyer.com/rest/sign/template/:template_id

Header Parameters

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

Url Parameters

Parameter Required Type Default Description
template_id yes String Id of a valid template

Error

Status Name Code Reason
400 invalid_request_error template_not_found Template not found. Check your template id
401 invalid_api_key invalid_api_key Apikey is not valid

List document templates

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

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

Example Response

{
     "skip": 1,
     "limit": 2,
     "has_more": true,
     "count": 2,
     "templates": [
         {
             "id": "template_60c34fd1f866",
             "friendly_name": "Template ABC",
             "sign_coordinates": [
                 {
                     "start_tag_pattern": "$$BandyerSignature1",
                     "x_offset": -100,
                     "y_offset": -150
                 },
                 {
                     "start_tag_pattern": "$$BandyerSignature2",
                     "x_offset": 100,
                     "y_offset": -50
                 },
                 {
                     "start_tag_pattern": "$$BandyerSignature3",
                     "x_offset": 50,
                     "y_offset": -150
                 }
             ],
             "creation_date": "2021-07-28T07:09:02.899Z",
             "updated_at": "2021-07-28T07:09:02.899Z"
         },
         {
             "id": "template_90j34fd1f888",
             "friendly_name": "Template 123",
             "sign_coordinates": [
                 {
                     "start_tag_pattern": "$$BandyerSignature1",
                     "x_offset": -100,
                     "y_offset": -150
                 },
                 {
                     "start_tag_pattern": "$$BandyerSignature2",
                     "x_offset": 100,
                     "y_offset": -50
                 },
                 {
                     "start_tag_pattern": "$$BandyerSignature3",
                     "x_offset": 50,
                     "y_offset": -150
                 }
             ],
             "creation_date": "2021-07-28T07:19:00.566Z",
             "updated_at": "2021-07-28T07:19:00.566Z"
         }
     ]
 }

This end-point return all the templates created for the company

HTTP Request

GET https://sandbox.bandyer.com/rest/sign/template/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

Error

Status Name Code Reason
401 invalid_api_key invalid_api_key Apikey is not valid

Get envelope

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

curl -X GET "https://sandbox.bandyer.com/rest/sign/envelope/:envelope_id" \
     -H 'apikey: COMPANY_APIKEY'

Example Response

{
  "envelope": {
         "id": "envelope_2f541b80acce",
         "friendly_name": "Envelope 1",
         "room_id": "room_c54a05293287",
         "session_id": "session_46b875303b96",
         "status": "pending",
         "sender": "user_xxx",
         "signer": "user_yyy",
         "creation_date": "2021-08-23T12:55:31.587Z",
         "updated_at": "2021-08-23T12:55:31.587Z"
     }
}

This end-point return a specific envelope that contains all the information about the room and session during which an envelope has been signed and the users involved in the process. The id of the envelope can be used later to retrieve more information related to the document and the signed document also.

HTTP Request

GET https://sandbox.bandyer.com/rest/sign/envelope/:envelope_id

Header Parameters

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

Url Parameters

Parameter Required Type Default Description
envelope_id yes String The id of the envelope obtained form the list API

Error

Status Name Code Reason
400 invalid_request_error envelope_not_found Envelope not found. Check your envelope id
401 invalid_api_key invalid_api_key Apikey is not valid

Get envelope list

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

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

Example Response

{
      "skip": 1,
      "limit": 2,
      "has_more": true,
      "count": 2,
      "envelopes": [
          {
              "id": "envelope_2f541b80acce",
              "friendly_name": "Envelope 1",
              "room_id": "room_c54a05293287",
              "session_id": "session_46b875303b96",
              "status": "failed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-23T12:55:31.587Z",
              "updated_at": "2021-08-23T12:55:31.587Z"
          },
          {
              "id": "envelope_9c7cb9bdff7f",
              "friendly_name": "Envelope 2",
              "room_id": "room_c54a05293287",
              "session_id": "session_d3106e6291b2",
              "status": "completed",
              "sender": "user_xxx",
              "signer": "user_yyy",
              "creation_date": "2021-08-24T07:05:14.764Z",
              "updated_at": "2021-08-24T07:05:14.764Z"
          }
      ]
  }

This end-point return a list of envelopes, each envelope contains all the information about the room and session during which an envelope has been signed and the users involved in the process. The id of the envelope can be used later to retrieve more information related to the document and the signed document also.

HTTP Request

GET https://sandbox.bandyer.com/rest/sign/envelope/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

Error

Status Name Code Reason
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_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_room_created v0, v1 When a new room is created
on_room_disabled v0, v1 When a room is disabled
on_room_deleted v0, v1 When a room is deleted
on_room_new_feedback v0, v1 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, v1 A user is connected
on_user_disconnected v0, v1 A user is disconnected
on_broadcast_start v0, v1 When a broadcast is started by publisher
on_broadcast_stop v0, v1 When a broadcast stopped by publisher
on_broadcast_pub_connected v0, v1 When the publisher is connected to a broadcast
on_broadcast_pub_disconnected v0, v1 When the publisher is disconnected from a broadcast
on_broadcast_sub_connected v0, v1 When a subscriber is connected to a broadcast
on_broadcast_sub_disconnected v0, v1 When a subscriber is disconnected from a broadcast
on_broadcast_new_feedback v0, v1 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

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 - Call events

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_call_incoming",
       "room_id": "room_04f97fd1k0b6",
       "data": {
           "initiator": "user_xxx",
           "users": [
               {
                   "user": {
                       "userAlias": "user_yyy"
                   },
                   "status": "invited"
               },
               {
                   "user": {
                       "userAlias": "user_xxx"
                   },
                   "status": "invited"
               }
           ],
           "roomAlias": "room_04f97fd1k0b6",
           "options": {
               "duration": 0,
               "record": false,
               "recordingType": "automatic",
               "creationDate": "2021-02-18T17:12:34.537Z",
               "callType": "audio_video",
               "live": true
           }
       }
   }
  } */

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

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

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 Object Object representation of the event data.

Call events data specification.

on_call_incoming

Data content:

Parameter Type Description
initiator String Id of the initiator of the call
users Array of user object Participants of the call
room_id String Room id of the call
options Object Additional information of the call

Options object

Parameter Type Description
duration Number Max duration of the room
Record Boolean Specify if the room is recorded or not
RecordingType String Can be automatic or manual
CallType String Can be audio_only, audio_upgradable or audio_video
Live Boolean Specify if the call trigger a ringing in the SDK integrations
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

v0 - Room events

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

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 String representation of object the event data.

Room events data specification.

on_room_created

Data content:

Parameter Type Description
room_id String Room id of the room
record Number Specify if the room is recorded or not
recording_type String 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.
duration Number Maximum value expressed in seconds of effective calling time allowed for the room. The minimum value is 60 seconds. If not specified, the call duration is unlimited.
live Boolean 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.
directCall Boolean Specify if the url created is direct or not
description String Description of the room
user_urls Array of objects User urls of the room

User_urls objects

Parameter Type Description
user String Id of the user who join the call
url String Url that allow the user to join the call
tools String Available tools for the user in call
is_admin String If the user have the admin functionality in call

on_room_disabled

Data content:

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

on_room_deleted

Data content:

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

on_room_new_feedback

Data content:

Parameter Type Description
room_id String Id of the room that have received the feedback
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 Id of the room that have received the session_started
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session started
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
duration_remained Number Number of call seconds left

on_session_ended

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_ended
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session ended
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
duration_remained Number Number of call seconds left

on_session_paused

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_paused
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session paused
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
duration_remained Number Number of call seconds left

on_session_resumed

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_resumed
connected_users Number Number of connected users
timestamp String (ISO8601 time) Timestamp of session resumed
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
duration_remained Number Number of call seconds left

on_user_connected

Data content:

Parameter Type Description
user_id String Id of the user connected
first_name String Firstname of the user
last_name String Lastname of the user
email String Email of the user
room Object Room information
timestamp String (ISO8601 time) Timestamp of user connection

Room object

Parameter Type Description
room_id String Id of the room the user connected to
connected_users Number Count of the user connected

on_user_disconnected

Data content:

Parameter Type Description
user_id String Id of the user disconnected
first_name String Firstname of the user
last_name String Lastname of the user
email String Email of the user
room Object Room information
timestamp String (ISO8601 time) Timestamp of user disconnection

Room object

Parameter Type Description
room_id String Id of the room the user disconnected to
connected_users Number Count of the user connected

v0 - Broadcast events

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_broadcast_start",
      room_id: "bro_52sdfg5sv6",
      data: '{
          "broadcast_id": "bro_52sdfg5sv6",
          "session_id": "session_a1n5bk022jg9"
      }'
  } */

  // 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

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 Broadcast id of the event fired.
data string Object representation of the event data.

Broadcast events data specification.

on_broadcast_start

Data content:

Parameter Type Description
broadcast_id String Broadcast id that has started
session_id String Session id of the broadcast

on_broadcast_stop

Data content:

Parameter Type Description
broadcast_id String Broadcast id that has stopped
session_id String Session id of the broadcast

on_broadcast_pub_connected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the publisher connected to
user_id String Id of the publisher

on_broadcast_pub_disconnected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the publisher disconnected to
user_id String Id of the publisher

on_broadcast_sub_connected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the subscriber connected to
user_id String Id of the subscriber

on_broadcast_sub_disconnected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the subscriber disconnected to
user_id String Id of the subscriber

on_broadcast_new_feedback

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast that have received the feedback
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

v0 - Recording events

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_recording_available",
      room_id: "room_52sdfg5sv6",
      data: '{
          "room_id": "bro_52sdfg5sv6",
          "session_id": "session_a1n5bk022jg9",
          "creationDate": ""2021-02-18T17:12:34.537Z"
      }'
  } */

  // 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

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 Object Object representation of the event data.

Recording events data specification.

on_recording_available

Data content:

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

on_broadcast_recording_available

Data content:

Parameter Type Description
room_id String Broadcast id of the call
session_id String Session id of which registration is ready
creationDate String (ISO8601 time) Creation date of the file

v1 - Room events

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_room_deleted',
  event_version: '1.0',
  namespace: 'room',
  timestamp: 1624605171921,
  data: {
     room_id: 'room_5beecf8c0f29',
     deleted_links: [
         { user_id: 'user_1', link: '"https://sandbox.bandyer.com/connect/rest-call-handler/aaaaaaaaaa"' },
         { user_id: 'user_2', link: '"https://sandbox.bandyer.com/connect/rest-call-handler/bbbbbbbbbb"' }
     ]
  }
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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Room events data specification.

on_room_created

Data content:

Parameter Type Description
room_id String The room associated to the session
recording Number This param defines whether the room should be recorded(1) or not (0).
recording_type String 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.
duration Number Maximum value expressed in seconds of effective calling time allowed for the room. The minimum value is 60 seconds. If not specified, the call duration is unlimited.
call_type String This param defines type of the call. Allowed values are audio_only, audio_upgradable or audio_video.
live Boolean 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.
description String A textual description of the room.
participants Array of objects Array of users who will participate in the call.

Participants object

Parameter Type Description
user String Id of the user who join the call
url String Url that allow the user to join the call
tools String Available tools for the user in call
is_admin String If the user have the admin functionality in call

on_room_disabled

Data content:

Parameter Type Description
room_id String The room associated to the session
disabled_links Array of objects Pair of user_id and link that are disabled
Parameter Type Description
user_id String Id of the user
link String Call link that is disabled

on_room_deleted

Data content:

Parameter Type Description
room_id String The room associated to the session
deleted_links Array of objects Pair of user_id and link that are deleted
Parameter Type Description
user_id String Id of the user
link String Call link that is deleted

on_room_new_feedback

Data content:

Parameter Type Description
room_id String Id of the room that have received the feedback
session_id String Session id of the room
user_id String Id of the user who created the feedback
rating Number Rating from 1 to 5
message String Optional text message about the feedback

v1 - Sessions events

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',
  timestamp: 1624605171921,
  data: {
    timestamp: '2021-06-25T07:37:24.363Z',
    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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Sessions events data specification.

on_session_started

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_started
session_id String Id of the started session
connected_participants Array of string List of users that have started the session
timestamp String (ISO8601 Timestamp) Timestamp of the action performed in UTC
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
elapsed_time Number How many seconds the room was in RUNNING state.

on_session_resumed

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_resumed
session_id String Id of the resumed session
connected_participants Array of string List of users that have started the session
timestamp String (ISO8601 Timestamp) Timestamp of the action performed in UTC
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
elapsed_time Number How many seconds the room was in RUNNING state.

on_session_paused

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_resumed
session_id String Id of the paused session
timestamp String (ISO8601 Timestamp) Timestamp of the action performed in UTC
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
elapsed_time Number How many seconds the room was in RUNNING state.

on_session_ended

Data content:

Parameter Type Description
room_id String Id of the room that have received the session_ended
session_id String Id of the ended session
timestamp String (ISO8601 Timestamp) Timestamp of the action performed in UTC
duration Object Optional parameters, present if the call was created with the duration parameter

Duration object

Parameter Type Description
total_duration Number Max duration limit of the room, if 0 is unlimited
elapsed_time Number How many seconds the room was in RUNNING state.

=begin

v1 - Recording events

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_recording_available',
  event_version: '1.0',
  namespace: 'recording',
  timestamp: 1624605171921,
  data: {
     room_id: 'room_5beecf8c0f29',
    session_id: 'session_a1n5bk022jg9'
  }
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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Recording events data specification.

on_recording_available

Data content:

Parameter Type Description
room_id String Room id of the call
session_id String Session id of which registration is ready

on_broadcast_recording_available

Data content:

Parameter Type Description
broadcast_id String Broadcast id of the call
session_id String Session id of which registration is ready

=end

v1 - Users events

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_user_connected',
  event_version: '1.0',
  namespace: 'user',
  timestamp: 1624605171921,
  data: {
    room_id: 'room_5beecf8c0f29'
    session_id: 'session_a1n5bk022jg9',
    user_id: "user_xxx",
    connected_users_count: 2
   }
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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

User events data specification.

on_user_connected

Data content:

Parameter Type Description
room_id String Id of the room the user connected to
session_id String The session associated to the event
user_id String Id of the connected user
connected_users_count Number Count of the user connected

on_user_disconnected

Data content:

Parameter Type Description
room_id String Id of the room the user disconnected to
session_id String The session associated to the event
user_id String Id of the disconnected user
connected_users_count Number Count of the user connected to the room

v1 - Broadcast events

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_broadcast_start',
  event_version: '1.0',
  namespace: 'broadcast',
  timestamp: 1624605171921,
  data: {
    broadcast_id: 'room_5beecf8c0f29'
    session_id: 'session_a1n5bk022jg9'
   }
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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Broadcast events data specification.

on_broadcast_start

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast that has started
session_id String The session associated to the event

on_broadcast_stop

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast that has started
session_id String The session associated to the event

on_broadcast_pub_connected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the publisher connected to
session_id String The session associated to the event
user_id String Id of the publisher

on_broadcast_pub_disconnected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the publisher disconnected to
session_id String The session associated to the event
user_id String Id of the publisher

on_broadcast_sub_connected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the subscriber connected to
session_id String The session associated to the event
user_id String Id of the subscriber or panelist

on_broadcast_sub_disconnected

Data content:

Parameter Type Description
broadcast_id String Id of the broadcast the subscriber disconnected to
session_id String The session associated to the event
user_id String Id of the subscriber or panelist

v1 - Chat events

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',
  timestamp: 1624605171921,
  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: '{}'
   }
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
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Chat events data specification.

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 String String representation of valid attributes JSON

v1 - Upload events

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',
  timestamp: 1624605171921,
  data: {
    tag: 'tag1',
    upload_key: 'sandbox/cmpny_abcdefg/user_yyy/1585070036835-xxxyyyzzzxxxxyyyzzz',
    timestamp: '2020-02-04T13:58:50.220Z',,
    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 Name of the event
event_version String Version of the webhook
namespace String Namespace of the webhook event
timestamp Number Time at which the object was created. Measured in seconds since the Unix epoch.
data Object The event data.

Upload events data specification.

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 (ISO8601 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.