Platform app settings
Platform app settings allow you to centrally configure options affecting the behavior of Teamwire client applications on certain platforms only (e.g. desktop clients).
Manage Teamwire platform app settings
Return platform-specific app settings
GET /v<api_version>/admin/platformappsettings/<platform>/<organisation_id>/
This endpoint returns platform-specific app settings for one or all of the following currently defined platforms: - Mobile clients (i.e. Android, iOS) - Desktop client - Webclient - SDK-based clients.
Note 1: As these are “app settings” the backend mostly serves as a storage service and interpretation is
up to the Teamwire clients. There are some exceptions, however, for example the allowSessionClose setting
is not only interpreted client-side but also checked within the backend endpoint responsible for closing a
session.
Note 2: Not all settings are used on every platform, for example the Desktop client does not use the
allowAccessCamera permission.
Access restrictions
- Admins and Superadmins must have the allow_view_settings permission.
- Admins can request platform app settings of their own organisation only.
- Superadmins can request platform app settings of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| platform | String | No | All admins | The platform to retrieve the app settings for. One of Mobile, Desktop, Webclient, SDK or All if the settings for all platforms should be returned. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to retrieve the platform app settings for. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. Platform app settings are returned as a JSON object as described below. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because either a.) an invalid platform was specified or b.) the organisation could not be found or c.) organisation is federated from different backend. |
| 409 (Conflict) | The request failed because the organisation has been disabled. |
If the request was successful and a platform value other than all has been specified, a single JSON object
with the following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
allow_access_calendar |
Boolean | All admins | Whether access to the calendar is allowed. |
allow_access_camera |
Boolean | All admins | Whether access to the camera is allowed. |
allow_access_location |
Boolean | All admins | Whether access to the current location is allowed. |
allow_access_microphone |
Boolean | All admins | Whether access to the microphone is allowed. |
allow_access_photos |
Boolean | All admins | Whether access to photos is allowed. |
allow_access_videos |
Boolean | All admins | Whether access to videos is allowed. |
allow_attachments |
Boolean | All admins | Whether attachments are allowed. |
allow_auto_save_media |
Boolean | All admins | Whether auto-saving media is allowed. |
allow_blocking_users |
Boolean | All admins | Whether blocking users is allowed. |
allow_change_password |
Boolean | All admins | Whether users are allowed to change their login password. |
allow_close_chats |
Boolean | All admins | Whether chat admins are allowed to close chat. |
allow_close_sessions |
Boolean | All admins | Whether users are allowed to manage sessions. |
allow_copy_paste |
Boolean | All admins | Whether copy/paste is allowed. |
allow_delete_messages |
Boolean | All admins | Whether deleting messages by user is allowed. |
allow_email_conversation |
Boolean | All admins | Whether sending conversations by Email is allowed. |
allow_file_sharing |
Boolean | All admins | Whether file sharing is allowed. |
allow_interactive_attachments |
Boolean | All admins | Whether interactive attachments are allowed. |
allow_invite_members |
Boolean | All admins | Whether inviting members is allowed. |
allow_leave_conversation |
Boolean | All admins | Whether leaving conversations is allowed. |
allow_open_in |
Boolean | All admins | Whether access to “Open in…” is allowed. |
allow_notification_preview |
Boolean | All admins | Whether preview in notifications is allowed. |
allow_reply_from_notifications |
Boolean | All admins | Whether reply from notifications is allowed. |
enable_alerting |
Boolean | All admins | Whether alerting is enabled. |
enable_s_o_s_button |
Boolean | All admins | Whether the SOS button is enabled. |
require_pin |
Boolean | All admins | Whether an access code is enforced (mobile only). |
show_contact_data |
Number | All admins | Who can see user contacts data (0 - noone, 1 - only users from same organisations, 2 - everybody) |
pin_interval |
Number | All admins | Access code request interval in nanoseconds. |
messages_retention_period |
Number | All admins | Messages retention period in days (0=always retain). Note this setting applies to clients only, not the backend. |
If the request was successful and a platform value of all has been specified, a JSON object with the
following elements is returned:
| Name | Type | Visible to | Description |
|---|---|---|---|
Mobile |
Object | All admins | The platform-specific app settings for mobile clients as described above. |
Desktop |
Object | All admins | The platform-specific app settings for the desktop client as described above. |
Webclient |
Object | All admins | The platform-specific app settings for the Webclient as described above. |
SDK |
Object | All admins | The platform-specific app settings for SDK-based clients as described above. |
Set platform app settings
PUT /v<api_version>/admin/platformappsettings/<platform>/<organisation_id>/
Access restrictions
- Admins and Superadmins must have the allow_modify_settings permission.
- Admins can update platform app settings of their own organisation only.
- Superadmins can update platform app settings of any organisation.
URL parameters
The following parameters are specified as part of the URL, i.e. /<parameter>/:
| Name | Type | Optional | For use by | Description |
|---|---|---|---|---|
| api_version | String | No | All admins | The Enterprise API version targeted. |
| platform | String | No | All admins | The platform to set the app settings for. One of mobile, desktop, webclient or sdk. |
| organisation_id | Number | Yes | All admins | The ID of the organisation to set the platform app settings for. |
PUT data
Parameters are supplied as a JSON object with the following elements:
| Name | Type | Optional | Visible to | Description |
|---|---|---|---|---|
allow_access_calendar |
Boolean | Yes | All admins | Whether access to the calendar is allowed. |
allow_access_camera |
Boolean | Yes | All admins | Whether access to the camera is allowed. |
allow_access_location |
Boolean | Yes | All admins | Whether access to the current location is allowed. |
allow_access_microphone |
Boolean | Yes | All admins | Whether access to the microphone is allowed. |
allow_access_photos |
Boolean | Yes | All admins | Whether access to photos is allowed. |
allow_access_videos |
Boolean | Yes | All admins | Whether access to videos is allowed. |
allow_attachments |
Boolean | Yes | All admins | Whether attachments are allowed. |
allow_auto_save_media |
Boolean | Yes | All admins | Whether auto-saving media is allowed. |
allow_blocking_users |
Boolean | Yes | All admins | Whether blocking users is allowed. |
allow_change_password |
Boolean | Yes | All admins | Whether users are allowed to change their login password. |
allow_close_chats |
Boolean | Yes | All admins | Whether chat admins are allowed to close chat. |
allow_close_sessions |
Boolean | Yes | All admins | Whether users are allowed to manage sessions. |
allow_copy_paste |
Boolean | Yes | All admins | Whether copy/paste is allowed. |
allow_delete_messages |
Boolean | Yes | All admins | Whether deleting messages by user is allowed. |
allow_email_conversation |
Boolean | Yes | All admins | Whether sending conversations by Email is allowed. |
allow_file_sharing |
Boolean | Yes | All admins | Whether file sharing is allowed. |
allow_interactive_attachments |
Boolean | Yes | All admins | Whether interactive attachments are allowed. |
allow_invite_members |
Boolean | Yes | All admins | Whether inviting members is allowed. |
allow_leave_conversation |
Boolean | Yes | All admins | Whether leaving conversations is allowed. |
allow_notification_preview |
Boolean | Yes | All admins | Whether preview in notifications is allowed. |
allow_open_in |
Boolean | Yes | All admins | Whether access to “Open in…” is allowed. |
allow_push_to_talk |
Boolean | Yes | All admins | Whether access to “Push to talk” is allowed. |
allow_reply_from_notifications |
Boolean | Yes | All admins | Whether reply from notifications is allowed. |
enable_alerting |
Boolean | Yes | All admins | Whether alerting is enabled. |
enable_s_o_s_button |
Boolean | Yes | All admins | Whether the SOS button is enabled. |
require_pin |
Boolean | Yes | All admins | Whether an access code is enforced (mobile only). |
show_contact_data |
Number | Yes | All admins | Who can see user contacts data (0 - noone, 1 - only users from same organisations, 2 - everybody) |
pin_interval |
Number | Yes | All admins | Access code request interval in nanoseconds. |
messages_retention_period |
Number | Yes | All admins | Messages retention period in days (0=always retain). Note this setting applies to clients only, not the backend. |
Result
The following return values indicate the outcome of the API call:
| HTTP status code | Description |
|---|---|
| 200 (OK) | The request was successful. The updated platform app settings are returned as a JSON object as described for the GET request. |
| 401 (Unauthorized) | The request failed because the caller failed to first login to the Enterprise API or her session expired. Login to obtain a new session and repeat the request. |
| 403 (Forbidden) | The request failed because either a.) the calling admin’s organisation has been disabled or b.) an organisation ID was specified and the calling admin is not a Superadmin. |
| 404 (Not found) | The request failed because either a.) an invalid platform was specified or b.) the organisation could not be found or c.) organisation is federated from different backend. |
| 409 (Conflict) | The request failed because either a.) the organisation has been disabled or b.) enableSOSButton params was selected without selecting enableAlerting. |