Announcements

Important configuration note: by default the APIO will only support as encoding format the format natively supported by the Application Server it is provisioning.

An optional transcoding module FFMPEG can be installed on APIO servers in order to support more input formats and the download as mp3. If not installed only the native format will be supported.

Retrieve the user’s announcement list

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/

Retrieve the user’s announcement list.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

or

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "addUsages": true
}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "announcements": [
      {
         "name": "APIO Group Test Announcement",
         "mediaType": "WAV",
         "fileSize": "78"
      }
   ],
   "totalFileSize": -1,
   "maxFileSize": -1
}

or

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "announcements": [
      {
         "name": "APIO Group Test Announcement",
         "mediaType": "WAV",
         "fileSize": "78",
         "usages": []
      }
   ],
   "totalFileSize": -1,
   "maxFileSize": -1
}
Request JSON Object:

  • addUsages (boolean) – if set it will retrieve also the usages of each announcement

Response JSON Object:
Status Codes:

Create a user’s announcement

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/

Create a user’s announcement.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "name": "Test announcement",
   "content": CONTENT_AUDIO_FILE,
   "description": "Test audio file"
}

or

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "repositoryAnnouncement": "default_busy_announcement",
   "name": "My Busy Announcement",
   "description": "Busy announcement file"
}
Request JSON Object:

Example response:

Response:

Similar to GET list method response.

Status Codes:

  • 201 Created – created

  • 400 Bad Request –

    failed to create, with possible main sub error codes:

    • 65 TOO_LARGE, ‘Audio file size is larger than the maximum size allowed’

Delete a user’s announcement

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/

Delete a user’s announcement.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "announcements": [
      {
         "name": "Test announcement"
      }
   ]
}
Request JSON Object:

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

Retrieve the user’s announcement instance

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/(string: instance_name)/

Retrieve the user’s announcement instance.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/Test%20announcement/ HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "description": "Test audio file",
   "fileSize": "64",
   "lastUploaded": "2018-01-17T15:06:59.913+01:00",
   "usages": [],
}
Response JSON Object:
Status Codes:

Retrieve the user’s announcement content

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/content/(string: instance_name)/

Retrieve the user’s announcement content.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/content/Test%20announcement/ HTTP/1.1
Host: example.com

or

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/content/Test%20announcement/ HTTP/1.1
Host: example.com

{
   "outputFormat": "mp3"
}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "content": CONTENT_AUDIO_FILE,
}
Request JSON Object:

  • outputFormat (string) – Specify the output format of the content. Supported formats: ‘wav’ (default), ‘mp3’

Response JSON Object:

  • content (string) – The announcement content itself encoded in base64

Status Codes:

Update a user’s announcement

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/(string: instance_name)/

Update a user’s announcement.

Example request:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/Test%20announcement/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "name": "New Test announcement",
   "content": CONTENT_AUDIO_FILE
}

or

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/Test%20announcement/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "repositoryAnnouncement": "default_busy_announcement_2",
   "name": "My New Busy Announcement",
   "description": "Busy announcement file"
}
Request JSON Object:

Example response:

Response:

Similar to GET instance method response.

Status Codes:

  • 200 OK – no error

  • 400 Bad Request –

    failed to update, with possible main sub error codes:

    • 65 TOO_LARGE, ‘Audio file size is larger than the maximum size allowed’

Delete a user’s announcement

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/announcements/(string: instance_name)/

Update a group’s announcement.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/announcements/Test%20announcement/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

Configuration Information

The APIO behaviour is controlled by the following settings:

"AUDIO_TOO_LARGE_FALLBACK_OLD_MODE": True
With following parameters:

  • AUDIO_TOO_LARGE_FALLBACK_OLD_MODE: If the AS rejects the file because it is too big, the system will try to upload it again using the legacy file format that has lower quality but is smaller. Default is true.