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

Get company information

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

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

Example Response

{
    "company": {
        "name": "Test Company",
        "default_language": "it",
        "logos": {
            "light_url": "https://static.bandyer.com/corporate/logos/logo_company_pittogramma_white.png",
            "dark_url": "https://static.bandyer.com/corporate/logos/logo_company_pittogramma_dark.png"
        },
        "default_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"
    }
}

Retrieve information of the company related to the given api_key;

HTTP Request

GET https://api.sandbox.eu.bandyer.com/rest/company

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 or inactive

Update company

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

curl -X POST "https://api.sandbox.eu.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":{
            "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://api.sandbox.eu.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

Update company logo

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

curl -X POST "https://api.sandbox.eu.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://api.sandbox.eu.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
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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/company/virtual-background" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d "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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/company/theme" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"

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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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.

Sdk

Generate credentials

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

curl -X POST "https://api.sandbox.eu.bandyer.com/rest/sdk/credentials" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -d '{
        "user_id": "user_xxx",
        "expires_in": 3600
     }'

Example Response

{
    "access_token": "valid jwt for the user",
    "expires_at": "2022-01-10T11:41:19.000Z",
    "user_id": "user_xxx"
}

Return a valid accessToken to provide to the clients that needs a sdk authentication, please DO NOT request the token client side in order to not expose the api_key. If you expose the api_key the credential’s generation for your company became unsafe.

HTTP Request

POST https://api.sandbox.eu.bandyer.com/rest/sdk/credentials

Header Parameters

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

Body Parameters

Parameter	Required	Default	Description
user_id	yes	“”	User that you want to authenticate
expires_in	no	3600	Seconds after that the token expires

Error

Status	Name	Code	Reason
401	invalid_api_key	invalid_api_key	Apikey is not valid
422	validation_error	invalid_token_expirations	The expires_in must be between 360 (6 minutes) and 86400 (24 hours)

User

Create User

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

curl -X POST "https://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/user/create

Header Parameters

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

Body Parameters

Parameter	Required	Type	Default	Description
id	no	string	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-Z0-9] and . _ - symbols. If the param is not specified, Bandyer will generate a random ID automatically (Max 128 characters).
role	yes	string	“”	Roles of the user. Available options are “basic” or “plus”
can_video	no	string or boolean	true	Allow the user to publish your own video. Available options are “1”, “0”, true or false.
language	no	string	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://api.sandbox.eu.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.

HTTP Request

PUT https://api.sandbox.eu.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	Type	Default	Description
can_video	no	string or boolean		Allow the user to publish your own video. Available options are “1”, “0”, true or false.
language	no	string		Language of the user. Available options are “en”, “it”, “de”, “fr” or “pl”.
role	no	string		Role of the user. Available option are “basic” or “plus”
active	no	boolean		Disable or enable a user

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://api.sandbox.eu.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://api.sandbox.eu.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	Type Default	Description
can_video	yes	string or boolean	true

Update user avatar

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

curl -X PUT "https://api.sandbox.eu.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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	The id of the user to update

Body Parameters (form-data)

Parameter	Required	Type	Default	Description
avatar	yes	File	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://api.sandbox.eu.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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	The id of the user to delete

Retrieve user

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

curl -X GET "https://api.sandbox.eu.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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	The id of the user to retrieve room IDs.

Query Parameters

Parameter	Required	Type	Default	Description
filter[limit]	no	number	0	The limit number of array elements as response.
filter[skip]	no	number	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://api.sandbox.eu.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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	The id of the user to retrieve broadcast IDs.

Query Parameters

Parameter	Required	Type	Default	Description
filter[limit]	no	number	0	The limit number of array elements as response.
filter[skip]	no	number	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://api.sandbox.eu.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"],
          "channel_id": "ch_174573edpo8d",
          "unread_messages_count": 1,
          "last_message": {
            "message_id": "msg_sdfs5dfg",
            "body": "message",
            "from": "usr_xxx",
            "date": "2020-01-15T11:57:43.000Z",
            "type": "text"
          }
        },
        {
          "users": ["usr_xxx","user_zzz"],
          "channel_id": "ch_234971edpo8d",
          "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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string	“”	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	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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/:user_id/session/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,
  "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://api.sandbox.eu.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	Type	Default	Description
user_id	yes	string		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://api.sandbox.eu.bandyer.com/rest/room/create" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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": true,
        "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/direct-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/direct-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://api.sandbox.eu.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.
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

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”.
directCall	no	Boolean	true	Setting this param to false allow to show the pre call summary.	08/11/21

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	✅	✅	✅	✅
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://api.sandbox.eu.bandyer.com/rest/room/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/room/info/:room_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

Example Response

{
    "room": {
        "room_id": "room_b571df8d8h3d",
        "record": 1,
        "recording_type": "automatic",
        "recording_status": "started",
        "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/connect/direct-rest-call-handler/aaaaaaaaaaaaaaaaaaaaa"
            },
            {
                "user": "usr_yyy",
                "url": "https://sandbox.bandyer.com/connect/direct-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://api.sandbox.eu.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
recording_type	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.
recording_status	Started if the recording is automatic or if a manual recording action was triggered, stopped otherwise
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://api.sandbox.eu.bandyer.com/rest/room/recording/:session_id" \
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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

Body Parameters

Parameter	Required	Type	Default	Description
disconnect_participants	no	boolean	false	Allow to disconnect the participants from the current room

Delete room

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

curl -X DELETE "https://api.sandbox.eu.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://api.sandbox.eu.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

Body Parameters

Parameter	Required	Type	Default	Description
disconnect_participants	no	boolean	false	Allow to disconnect the participants from the current room

Get room uploads list

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

curl -X GET "https://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/room/:room_id/envelope/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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

Start room recording

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

curl -X POST "https://api.sandbox.eu.bandyer.com/rest/room/:room_id/start-recording" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

Example Response

 204 No Content

This end-point allow to start the recording when a room is running and was created with the 'manual’ recording feature

HTTP Request

POST https://api.sandbox.eu.bandyer.com/rest/room/:room_id/start-recording

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.

Error

Status	Name	Code	Reason
401	invalid_api_key	invalid_api_key	Apikey is not valid
400	invalid_request_error	invalid_request_error	Room not found
412	invalid_request_error	room_not_running	The current room is not running
412	invalid_request_error	invalid_recording_type	The recording type of the room is automatic
412	invalid_request_error	invalid_recording_type	The recording is not recording
412	invalid_request_error	invalid_recording_status	The recording is already started

Stop room recording

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

curl -X POST "https://api.sandbox.eu.bandyer.com/rest/room/:room_id/stop-recording" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

Example Response

 204 No Content

This end-point allow to stop the recording when a room is running and was created with the 'manual’ recording feature

HTTP Request

POST https://api.sandbox.eu.bandyer.com/rest/room/:room_id/stop-recording

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.

Error

Status	Name	Code	Reason
401	invalid_api_key	invalid_api_key	Apikey is not valid
400	invalid_request_error	invalid_request_error	Room not found
412	invalid_request_error	room_not_running	The current room is not running
412	invalid_request_error	invalid_recording_type	The recording type of the room is automatic
412	invalid_request_error	invalid_recording_type	The recording is not recording
412	invalid_request_error	invalid_recording_status	The recording is already stopped

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
new_ui	new_ui	String	Allow to use the new ui, please contact us if you want the new ui as default

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 POST 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: { users_ids: ['user_xxx’, 'user_yyy’] } }

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	String or null	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

New UI

We have developed a new user interface to improve usability and have a new look and feel by introducing a complete theme restyling for all our tools.

The new UI will soon become the default for our platform but before doing so we decided to allow our customers to try out the new UI before it becomes the standard.

If you want to try the new interface you can add the ?new_ui parameter at the end of your links, if you want to make the new user interface the default behavior for all your rooms, please contact us

Call and chat UI

Screenshare UI

Upload file UI

Notification UI

Settings and toggle between theme modes

IFrame integration

Our call links can be integrated in an IFrame in order to make the experience more immersive and branded.

IFrame html tags have different capabilities and must be properly configured for all of our tools to work.

Aside you can find a little snippet of a complete integration

<iframe width="100%" height="100% "src="https://sandbox.bandyer.com/connect/call/token"
allowfullscreen mozallowfullscreen webkitallowfullscreen
allow="camera *;microphone *; display-capture *; picture-in-picture *; autoplay *; fullscreen *"
sandbox ="allow-scripts allow-downloads allow-same-origin allow-forms">

Attributes

Name	Description
allowfullscreen, mozallowfullscreen, webkitallowfullscreen	Set to true if the iframe can activate fullscreen mode (legacy, now allow=“fullscreen”)
allow	Specifies a feature policy for the iframe. The policy defines what features are available to the iframe based on the origin of the request
sandbox	Applies extra restrictions or permission to the content in the frame.

Allow attribute (Feature-Policy)

Name	Description
camera	Camera directive controls whether the current document is allowed to use video input devices.
microphone	Microphone directive controls whether the current document is allowed to use audio input devices.
display-capture	Display-capture directive controls whether or not the document is permitted to acquire your screen.
picture-in-picture	Picture-in-picture directive controls whether the current document is allowed to play a video in a Picture-in-Picture mode. (only one-to-one and one-to-many)
autoplay	Allow to automatically reproduce audio and video content without a user interaction, otherwise our page request a user interaction in order to play contents
fullscreen	Set to true if the iframe can activate fullscreen mode

Sandbox attribute

Name	Description
allow-forms	Allows the resource to submit forms. If this keyword is not used, form submission is blocked.(we used form in sign tools)
allow-scripts	Lets the resource run scripts (but not create popup windows).
allow-downloads	Allows for downloads to occur with a gesture from the user. (necessary in fileShare and snapshot tools)
allow-same-origin	If this token is not used, the resource is treated as being from a special origin that always fails the same-origin policy (need for the localstorage used)

Following some useful resources that can explain better all the feature and attributes

Attributes info

Feature-Policy

Broadcast

Create broadcast

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

curl -X POST "https://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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/direct-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://api.sandbox.eu.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

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

Parameter	Required	Type	Default	Description	Deprecation date
callee	no	String		The array of the user alias that will participate to the room.	20/10/20
direct	no	Boolean	true	Setting this param to false allow to show the pre call summary.	08/11/21

Get Broadcasts List

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

curl -X GET "https://api.sandbox.eu.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://api.sandbox.eu.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

• One of the parameter in the response is status, this parameter explains the status of the broadcast as you can see in the table below.

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://api.sandbox.eu.bandyer.com/rest/broadcast/info/:broadcast_id"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json"

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://api.sandbox.eu.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

• One of the parameter in the response is status, this parameter explains the status of the broadcast as you can see in the table below.

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

• Another particular parameter is totalDurationTime that explains for how many time the broadcast was in RUNNING state.
• The dialInfo section contains informations about all broadcast sessions: room total time, detail for each sesssion (with partial time) and every information about subscribers connected for each session. And creation the creation date for each session.

Get broadcast session recording

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

curl -X GET "https://api.sandbox.eu.bandyer.com/rest/broadcast/recording/:session_id"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/session/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,
  "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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/session/:session_id" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/session/:session_id/connection/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/session/:session_id/envelope/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/recording/configuration" \
     -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://api.sandbox.eu.bandyer.com/rest/recording/configuration

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://api.sandbox.eu.bandyer.com/rest/recording/configuration" \
     -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://api.sandbox.eu.bandyer.com/rest/recording/configuration

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(Unlimited) <= retention <= 15 or 30, 60, 90, 120, 180, 365, 730, 1095, 1460, 1825, 2190, 2555, 2920, 3285, 3650
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(Unlimited) <= retention <= 15 or 30, 60, 90, 120, 180, 365, 730, 1095, 1460, 1825, 2190, 2555, 2920, 3285, 3650

Encryption key

Create encryption key

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

curl -X POST "https://api.sandbox.eu.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:

• key.txt.enc: Contain a symmetric key encrypted with the given public key

• iv.txt: initialisation vector, necessary fot the decrypt phase

• README.txt: contains all the information for decrypt the files

HTTP Request

POST https://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/sign/template" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -d '{
        "friendly_name": "Contract ABC",
        "type": "contract",
        "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",
         "type": "contract",
         "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://api.sandbox.eu.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
type	yes	String (FEA_adhesion, contract)		Allow to specify if the template is a fea adhesion or a contract

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
422	validation_error	invalid_template_type	The template type must be one of the following FEA_adhesion, contract

Get document template

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

curl -X GET "https://api.sandbox.eu.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract ABC",
         "type": "contract",
         "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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY' /
     -H "Content-Type: application/json" \
     -d '{
         "friendly_name": "Contract 123"
         "type": "contract",
         "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",
         "type": "contract",
         "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://api.sandbox.eu.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
type	yes	String (FEA_adhesion, contract)		Allow to specify if the template is a fea adhesion or a contract

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

| 422 | validation_error | invalid_template_type | The template type must be one of the following FEA_adhesion, contract

Delete document template

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

curl -X DELETE "https://api.sandbox.eu.bandyer.com/rest/sign/template/:template_id" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

Example Response

{
 "template": {
         "id": "template_60c34fd1f866",
         "friendly_name": "Contract 123",
         "type": "contract",
         "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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/sign/template/list" \
     -H 'apikey: COMPANY_APIKEY' /
     -H "Content-Type: application/json" \
     -d '{
        "skip": 1
        "limit": 2
        }'

Example Response

{
     "skip": 1,
     "limit": 2,
     "has_more": true,
     "count": 2,
     "templates": [
         {
             "id": "template_60c34fd1f866",
             "friendly_name": "Template ABC",
             "type": "contract",
             "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",
              "type": "contract",
             "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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/sign/envelope/:envelope_id" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json"

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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/sign/envelope/list" \
     -H 'apikey: COMPANY_APIKEY' \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/tag/add"
     -H "apikey: COMPANY_APIKEY"
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/tag/remove"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/:version/hook/configure"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \
     -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://api.sandbox.eu.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_missed_call	v1	When a call is not answered or is canceled by the initiator
on_recording_started	v1	When a recording is triggered from the user, from rest api or if the room have the ‘automatic’ recording
on_recording_stopped	v1	When a recording is stopped from the user, from rest api or the call ends
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, v2	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://api.sandbox.eu.bandyer.com/rest/:version/hook/"
     -H "apikey: COMPANY_APIKEY" \
     -H "Content-Type: application/json" \

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://api.sandbox.eu.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

Verify Hook signature

v0 hooks

When we send a web hook v0 we add a room-id-hmac parameter in the header, this digest is a SHA256 of room_id cyphered by your api_key as shared secret.

v1 hooks

// 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'));

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:

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

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

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,
               "recording": "automatic"
               "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
roomAlias	String	Room id of the call
options	Object	Additional information of the call

user object

Parameter	Type	Description
user	Object	contains userAlias
status	string	status of the user in the call

Options object

Parameter	Type	Description
duration	Number	Max duration of the room
recording	string	Simplification of the mixed record nad recordingType, can be 'none’, 'automatic’ or 'manual’
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 - Call events

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_missed_call",
      event_version: "1.0"
      namespace: "call",
      timestamp: 1554193902,
      data: {
           room_id: "room_52sdfg5sv6",
           caller_id: "user_12sdc2",
           reason: "timeout",
           called_users: [{user_id: "user_3435fv", status: "not_answered"}]
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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.

Call events data specification.

on_missed_call

Data content:

Parameter	Type	Description
room_id	String	The room that the caller has started
caller_id	string	This param defines the user_id of the caller
reason	String	Timeout when after 60 seconds one or more users have not answered, canceled if the caller hangUp the call
called_users	Array of objects	Array of users, for each user the status indicate if it is in call or not

Called users objects

Parameter	Type	Description
user_id	String	Id of the user who join the call
status	String	Calling if the user have join the call, not_answered otherwise

v1 - Room events

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_new_feedback",
      event_version: "1.0"
      namespace: "room",
      timestamp: 1554193902,
      data: {
           room_id: "room_04f97fd1k0b6",
           session_id: "session_a1n5bk022jg9",
           user_id: "user_12sdc2",
           rating: 5,
           message: "My fantastic feedback"
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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

Disabled_links object

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

Deleted_links object

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

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_session_started",
      event_version: "1.0"
      namespace: "session",
      timestamp: 1554193902,
      data: {
          room_id: "room_04f97fd1k0b6",
          session_id: "session_a1n5bk022jg9",
          connected_participants: ["user_12sdc2", "user_3435fv"],
          timestamp: "2021-08-23T12:55:31.587Z"
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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.

v1 - Recording events

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_started",
      event_version: "1.0"
      namespace: "recording",
      timestamp: 1554193902,
      data: {
          room_id: "room_04f97fd1k0b6",
          session_id: "session_a1n5bk022jg9"
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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_started

Data content:

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

on_recording_stopped

Data content:

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

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

v1 - Users events

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_user_connected",
      event_version: "1.0"
      namespace: "user",
      timestamp: 1554193902,
      data: {
          room_id: "room_04f97fd1k0b6",
          session_id: "session_a1n5bk022jg9",
          user_id: "user_3435fv",
          connected_users_count: 1
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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

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",
      event_version: "1.0"
      namespace: "broadcast",
      timestamp: 1554193902,
      data: {
          broadcast_id: "bro_04f97fd1k0b6",
          session_id: "session_a1n5bk022jg9"
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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

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_message_sent",
      event_version: "1.0"
      namespace: "chat",
      timestamp: 1554193902,
      data: {
         id: "IMf80194a5e3c74bau8328ae74ec708c47",
         channel_id: "CH12c0d87860c04ac1bgb6a3448e5bf6d97",
         participants: ["user_12sdc2", "user_3435fv"],
         body: "message",
         type: "text",
         creation_date: "2021-08-24T07:18:18.508Z",
         sender: "user_12sdc2",
         index: 0,
         attributes: '{}'
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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

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_upload_tag_added",
      event_version: "1.0"
      namespace: "upload",
      timestamp: 1554193902,
      data: {
          tag: "tag_name",
          upload_key: "sandbox/company/user_xxx/1585071715613-c8a493a0217fcbd69c7f",
          timestamp: "2021-08-24T07:18:18.508Z",
          room_id: "room_04f97fd1k0b6",
          session_id: "session_a1n5bk022jg9"
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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

v2 - Chat events

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_message_sent",
      event_version: "2.0"
      namespace: "chat",
      timestamp: 1554193902,
      data: {
          message_id: "msg_865ety1305sd",
          channel_id: "ch_94063a09f3a8",
          message_body: "Message",
          participants: ["user_3435fv", "user_12sdc2"],
          created_at: "2018-01-16T09:34:10.000Z",
          sender_id: "user_3435fv",
          updated_at: "2018-01-16T09:34:10.000Z",
          attributes: {}
      }
  } */

  // Obtain the data object
  const { data } = req.body
})

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
message_id	String	Unique identifier of the message
channel_id	String	Unique identifier of the channel
message_body	String	Text of the message
participants	Array of strings	List of participants in the channel
created_at	Date	When message was created
sender_id	String	User alias of the creator of the message
updated_at	Date	Last update date
attributes	Object	Custom object used internally

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://api.sandbox.eu.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": [
        {
            "message_id": "msg_055e8d1305cd",
            "body": "Hello",
            "from": "usr_xxx",
            "date": "2018-01-16T09:29:36.000Z",
            "type": "text"
        },
        {
            "message_id": "msg_865ety1305sd",
            "body": "Hello",
            "from": "usr_yyy",
            "date": "2018-01-16T09:34:10.000Z",
            "type": "text"
        },
        {
            "message_id": "msg_963e8d130uy",
            "body": "How are you doing?",
            "from": "usr_xxx",
            "date": "2018-01-16T09:40:47.000Z",
            "type": "text"
        },
        {
            "message_id": "msg_605e8d13kjcd",
            "body": "Fine thanks",
            "from": "usr_yyy",
            "date": "2018-01-16T09:49:48.000Z",
            "type": "text"
        }
    ]
}

Get the chat messages exchanged in the channel (channel_id reference) or 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://api.sandbox.eu.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	no		Array of valid user aliases.
channel_id	no		Channel reference.
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_arguments	Please specify at least 2 participants or a channelId.
400	invalid_request_error	chat_not_found	Chat not found for the given users.
400	invalid_request_error	invalid_users_length	Users array must contain at least two valid users.
400	invalid_request_error	invalid_param	One or more input parameters are invalid, check the error message.

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://api.sandbox.eu.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"
    ],
    "channel_id": "ch_94063a09f3a8"
  },
  "message": "Chat added"
}

Create a chat between the users passed as input.

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

HTTP Request

POST https://api.sandbox.eu.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.
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://api.sandbox.eu.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"
    ],
    "channel_id": "ch_94063a09f3a8"
  },
  "message": "Chat removed"
}

Remove a chat between using the channel_id reference or 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://api.sandbox.eu.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	no		Array of valid user aliases.
channel_id	no		Channel reference.

Error

Status	Name	Code	Reason
400	invalid_request_error	invalid_arguments	Please specify at least 2 participants or a channelId.
400	invalid_request_error	invalid_users_length	Users array must contain at least two valid users.
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://api.sandbox.eu.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"
  ],
  "channel_id": "ch_94063a09f3a8",
  "sender": "usr_xxx",
  "message_id": "msg_344393a3a085",
  "message": "test message",
  "timestamp": "2020-01-21T11:42:22.000Z"
}

Send a message in a specified channel using channel id reference or the users,

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://api.sandbox.eu.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	no		Array of valid user aliases.
channel_id	no		Channel reference.
sender	yes		Who send the message.
message	yes		Text of the message.

Error

Status	Name	Code	Reason
400	invalid_request_error	invalid_arguments	Please specify at least 2 participants or a channelId.
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	send_message_error	Chat service error, unable to send message, retry.
401	invalid_api_key	invalid_api_key	Apikey is not valid.

Channel details

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

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

Example Response

{
  "channel_id": "ch_94063a09f3a8",
  "users": [
    "usr_xxx",
    "usr_yyy"
  ],
  "last_message": {
                  "message_id": "msg_344633a3a085",
                  "body": "Message",
                  "from": "user_xxx",
                  "date": "2020-01-21T11:42:22.000Z",
                  "type": "text"
              },
  "last_read_users_messages": [
            {
                "user_id": "user_xxx",
                "message_id": "msg_344633a3a085"
            },
            {
                "user_id": "user_yyy",
                "message_id": "msg_986393a3a753"
            }
    ]
}

Retrieve all the details of a specific channel

HTTP Request

GET https://api.sandbox.eu.bandyer.com/rest/chat

Header Parameters

Parameter	Required	Description
apikey	yes	The API key of your company

Query Parameters

Parameter	Required	Default	Description
users	no		Array of valid user aliases.
channel_id	no		Channel reference.

Error

Status	Name	Code	Reason
400	invalid_request_error	invalid_arguments	Please specify at least 2 participants or a channelId.
400	invalid_request_error	invalid_users_length	Users array must contain at least two valid users.
401	invalid_api_key	invalid_api_key	Apikey is not valid.

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://api.sandbox.eu.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://api.sandbox.eu.bandyer.com/rest/call/usr_example_1?callee=usr_example_2&record=0);

The usr_example_2 makes the request (https://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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://api.sandbox.eu.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.

Activities (@Deprecated)

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

curl -X GET "https://api.sandbox.eu.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

GET https://api.sandbox.eu.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