Zebra Workforce Connect: Interworking Gateway Workforce Connect Announcer REST API Developer Guide (en)
Workforce Connect
Announcer REST API
Developer Guide
MN-003114-07EN
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.
© 2021 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
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 are
subject 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
November 15, 2021
2
Introduction
This document describes how to send an audio file to the WFC Announcer using the WFC Announcer
REST API.
The Workforce Connect Announcer (WFC Announcer) provides a method for applications to send an audio
file to one or more PTT Express channels, PTT Pro users/groups, or Land Mobile Radio (LMR) targets. For
example, a customer can press a help button on a kiosk in a retail store to send an audio announcement to
store associates via the WFC Announcer. The help button generates a request containing an audio file and
the destination target(s) to the WFC Announcer, which then broadcasts the audio to the requested
destination(s).
Figure 1 WFC Announcer
Announcer REST API Developer Guide
Use the WFC Announcer REST API to send announcements to the desired targets.
WFC Interworking Gateway
The WFC Messenger is a component in the WFC InterWorking Gateway (WFC IWG). There are two
versions of the WFC IWG, referred to in this document as IWG V1 and IWG V2. The WFC Messenger
functions similarly for both versions of WFC IWG, with the following exceptions.
• The request URLs are different.
• The response codes for listing endpoints and sending a message are different.
• Only the IWG V2 supports an optional parameter identifying the source of the announcement.
• For information on which version of WFC IWG you have, contact your system administrator.
• IWG V2 does not support LMR or PTT Express.
Authentication
The WFC Announcer API validates all requests using the following methods:
• HTTP requests must use SSL (
• The required
api_password parameter is used for authentication.
https://, not http://).
3
Listing Endpoints
Applications use the WFC Announcer API to retrieve a list of endpoints supported by the WFC
Interworking Gateway (IWG).
Request
The WFC Announcer expects GET requests in the following format:
Table 1 List Endpoints Request Format
IWG Version URL
IWG V1
Announcer REST API Developer Guide
GET https://<IWG_URL>/gw/announce/list?api_password=<token>
or
GET https://<IWG_URL>/announce/list?api_password=<token>
Table 2 Parameters
Response
When endpoints are successfully retrieved, the IWG sends the following response code:
Table 3 List Endpoints Success Response
IWG V2
Parameter Description
api_password Secure token found on Administration page of IWG Management Portal.
site Returns results only for the specified Site (PTT Pro department). This
IWG Version Response Codes
IWG V1
IWG V2
GET https://<IWG_URL>/api/v1/list?api_password=<token>
parameter is optional and for IWG V2 only.
It is highly recommended to use this parameter to filter results and avoid
retrieving huge amounts of data.
200 Success
200 Successfully retrieved list
The body contains a JSON object with the list of endpoints in the format:
{
"messenger": <true or false>,
"announcer": <true or false>,
"endpoints":
[
{ "eid" : <endpoint id>, "name" : <endpoint name>, "faudio" : <true or false>, "ftext":
<true or false>},
{ "eid" : <endpoint id>, "name" : <endpoint name>, "faudio" : <true or false>, "ftext":
<true or false>},
{ "eid" : <endpoint id>, "name" : <endpoint name>, "faudio" : <true or false>, "ftext":
4
Announcer REST API Developer Guide
<true or false>},
...
]
}
Table 4 Listing Endpoints Response Fields
Field Description
api_password Secure token found on Administration page of IWG Management Portal.
eid Identifies the target endpoints when sending an announcement. The EID can
be the endpoint number or the full endpoint name.
messenger If set to true, the IWG has a configured Messenger endpoint and can send text
messages.
announcer If set to true, the IWG has a configured Announcer endpoint and can send
audio announcements.
name The endpoint display name.
faudio If set to true, the endpoint can send audio.
If set to false, the endpoint cannot send audio
ftext If set to true, the endpoint can send text.
If set to false, the endpoint cannot send text.
If endpoints are not retrieved, the IWG sends a response with one of the following error codes and a
reason:
Table 5 List Endpoints Success Response
IWG Version Response Codes
IWG V1
IWG V2
400 Bad Request
500 Internal Error
401 You are not authorized to view the resource
403 Accessing the resource you were trying to reach is forbidden
404 The resource you were trying to reach is not found
5
Announcer REST API Developer Guide
Sending an Announcement
Use this request to send an audio announcement from an application.
Request
The WFC Announcer expects POST requests in the following format:
Table 6 List Endpoints Request Format
IWG Version URL
IWG V1
POST https://<IWG_URL>/gw/announce/file?api_password=<token>
or
POST https://<IWG_URL>/announce/file?api_password=<token>
IWG V2
Encode all parameters, except api_password, as multipart/form-data in the request body.
Table 7 Parameters
Parameter Description
api_password Secure token found on Administration page of IWG Management Portal.
file Audio files are encoded as multipart/form-data into the request body.
eid Target endpoint ID obtained from the IWG Administration Portal or when
src Optional string identifying the originator of the message. This is not sent to the
Audio Format
The Interworking Gateway (IWG) accepts a WAV audio file in raw PCM or compressed format.
Audio Format
PCM
POST https://<IWG_URL>/api/v1/announcement?api_password=<token>
retrieving the endpoint list. The EID may appear multiple times to identify
multiple endpoints for a message. The EID can be the endpoint number or the
full endpoint name.
recipients of the message. IWG V2 only.
Audio Sample Rate
8000/11025/16000/44100/48000
8000 is preferred to avoid re-sampling.
Audio Sample Size
16-Bit
Channels
Mono or Stereo
6
Response
The IWG sends a response with one of the following response codes and a reason.
Table 8 List Endpoints Success Response
Announcer REST API Developer Guide
IWG Version Response Codes
IWG V1
200 Success
400 Bad Request
500 Internal Error
IWG V2
The IWG sends errors as soon as they are encountered; success (200 OK) is not sent until the
announcement has finished broadcasting.
200 OK
201 Created
401 Unauthorized
403 Forbidden
404 Not found
7
www.zebra.com
Loading...