ZEBRA MN-003114-10EN Workcloud Communication Announcer User Guide
- June 14, 2024
- ZEBRA
Table of Contents
ZEBRA MN-003114-10EN Workcloud Communication Announcer
Specifications
- Product Name: Announcer REST API
- Developer Guide: MN-003114-10EN
- Publication Date: April 8, 2024
Product Usage Instructions
Authentication
To authenticate and access the Announcer API, applications need to use the provided secure token API_password.
List Endpoints
Applications can retrieve a list of endpoints using the following request:
Parameters:
- api_password: Secure token found in ZEMS Customer Administrator Portal
- site: Returns results for the specified Site(PTT Pro department)
Response: The response contains a JSON object with the list of endpoints.
Sending an Announcement
To send an audio announcement from an application, use the following request:
Request: POST
Parameters:
- api_password: Secure token found in ZEMS Customer Administrator Portal
- file: Audio file encoded as multipart/form-data in the request body
- eid: Target endpoint ID obtained from retrieving the endpoint list
- src: Optional string identifying the message originator
FAQ
- What should I do if I encounter error codes while retrieving endpoints?
- If you encounter error codes such as 400, 401, 404, or 503 while retrieving endpoints, please refer to the corresponding descriptions provided in the manual and ensure correct parameter values are used.
- Can I send multiple announcements simultaneously?
- No, only a single EID can be specified for each announcement when sending audio announcements.
Product Information
ZEBRA and the stylized Zebra head are trademarks of Zebra Technologies
Corporation, registered in many jurisdictions worldwide. All other trademarks
are the property of their respective owners. © 2024 Zebra Technologies
Corporation and/or its affiliates. All rights reserved. Information in this
document is subject to change without notice. The software described in this
document is furnished under a license agreement or nondisclosure agreement.
The software may be used or copied only in accordance with the terms of those
agreements.
For further information regarding legal and proprietary statements, please go
to:
- SOFTWARE: zebra.com/linkoslegal
- COPYRIGHTS: zebra.com/copyright
- PATENTS: zebra.com/patents
- WARRANTY: zebra.com/warranty
- END USER LICENSE AGREEMENT: zebra.com/eula
Terms of Use
Proprietary Statement
This manual contains proprietary information of Zebra Technologies Corporation and its subsidiaries (“Zebra Technologies”). It is intended solely for the information and use of parties operating and maintaining the equipment described herein. Such proprietary information may not be used, reproduced, or disclosed to any other parties for any other purpose without the express, written permission of Zebra Technologies.
Product Improvements
Continuous improvement of products is a policy of Zebra Technologies. All specifications and designs aresubject to change without notice.
Liability Disclaimer
Zebra Technologies takes steps to ensure that its published Engineering specifications and manuals are correct; however, errors do occur. Zebra Technologies reserves the right to correct any such errors and disclaims liability resulting therefrom.
Limitation of Liability
In no event shall Zebra Technologies or anyone else involved in the creation, production, or delivery of the accompanying product (including hardware and software) be liable for any damages whatsoever (including, without limitation, consequential damages including loss of business profits, business interruption, or loss of business information) arising out of the use of, the results of use of, or inability to use such product, even if Zebra Technologies has been advised of the possibility of such damages. Some jurisdictions do not allow the exclusion or limitation of incidental or consequential damages, so the above limitation or exclusion may not apply to you. Publication Date April 8, 2024
Introduction
This document describes how to send an audio file through the Zebra Enterprise Messaging Service (ZEMS) Announcer REST API. The ZEMS provides a method for applications to send an audio file to one or more PTT Pro users or groups. For example, a customer can press a help button on a kiosk in a retail store to send an audio announcement to store associates through the Announcer API. The help button generates a request containing an audio file and the destination target(s) to the Announcer API, which then broadcasts the audio to the requested destination(s).
Authentication
The Announcer API validates all requests using the following methods:
- HTTP requests must use SSL (https://, not http://).
- The required api_password parameter is used for authentication.
Announcer Endpoints
Applications can use the Announcer API to retrieve a list of endpoints.
List Endpoints Request
- Use the following format for a GET request:
- GET https://
/iwg/api/v1/list?api_password=
Table 1 List Endpoints Parameters
| Parameter | Description |
|---|---|
| api_password | Secure token found on Customer Details dialog in the ZEMS |
Customer Administrator Portal.
site| Returns results for the specified Site (PTT Pro department).
All parameters are query parameters.
List Endpoints Response
When endpoints are successfully retrieved, the IWG sends the following response code: 200 Successfully retrieved list
The body contains a JSON object with the list of endpoints in the format
Table 2 List Endpoints Response Fields
| Field | Description |
|---|---|
| site | Name of the site in ZEMS and the department in PTT Pro. |
| name | Name of the endpoint |
| proxy | Name of the proxy |
| target | Name of the recipient. This is a PTT Pro user or a PTT Pro group. |
| contact | If true, the target is a user. |
If false, the target is a group.
If endpoints are not retrieved, the API sends one of the following error codes:
Table 3 List Endpoints Success Response
| Response Codes | Description |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized access. |
| 404 | Record not found. |
| 503 | Server error. |
Sending an Announcement
Use this request to send an audio announcement from an application.
Request
Send a POST request in the following format:
POST https://
Table 4 Request Parameters
| Parameter | Description |
|---|---|
| api_password | Secure token found on Customer Details dialog in the ZEMS |
Customer Administrator Portal.
file| Audio files are encoded as multipart/form-data into the request body.
eid| Target endpoint ID obtained when retrieving the endpoint list. Only a
single EID can be specified for each announcement.
src| Optional string identifying the originator of the message. This is not
sent to the recipients of the message.
All parameters are query parameters except for file, which is sent as multipart/form data in the request body.
Audio Format
The Announcer API accepts any audio format. ZEMS converts the audio file to WAV by ZEMS. Audio announcements should be 30 seconds or less and less than 100Mb.
Response
The Announcer API sends a response with one of the following response codes and a reason.
Table 5 Announcer Endpoints Responses
| Response Codes | Description |
|---|---|
| 200 | OK |
| 400 | Bad request |
| 401 | Unauthorized access |
| 404 | Record not found |
| 503 | Server error. |
The API returns an error when it occurs; a success response (200 OK) is not sent until the announcement finishes broadcasting