Zebra Workforce Connect: Interworking Gateway Workforce Connect Messenger REST API Developer Guide
Workforce Connect
Messenger REST API
Developer Guide
MN-003113-09EN
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 text messages to the Workforce Connect Messenger (WFC
Messenger) using the WFC Messenger REST API.
The WFC Messenger provides a method for applications to send text messages to one or more text
enabled PTT Pro channels. The WFC Messenger formats the text message and then forwards it to the
specified PTT Pro endpoint(s). The message can include an embedded image file, or link to a video or
audio file.
Figure 1 WFC Messenger
Use the WFC Messenger REST API to:
• List endpoints
Messenger REST API Developer Guide
• Send a message
• Upload a video or audio file.
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 V1 supports upload and storage of content for later retrieval, also referred to Message of
the Day (MOTD).
• Only the IWG V1 supports an optional parameter identifying the source of the message.
• For information on which version of WFC IWG you have, contact your system administrator.
Authentication
The WFC Messenger 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.
3
Listing Endpoints
Applications use the WFC Messenger API to retrieve a list of endpoints supported by the WFC
Interworking Gateway (IWG).
Listing Endpoints Request
The WFC Messenger expects GET requests in the following format:
Table 1 List Endpoints Request Format
IWG Version URL
IWG V1
Messenger REST API Developer Guide
GET https://<IWG_URL>/gw/announce/list?api_password=<token>
or
GET https://<IWG_URL>/announce/list?api_password=<token>
IWG V2
Table 2 List Endpoints Parameters
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 parameter is
GET https://<IWG_URL>/api/v1/list?api_password=<token>
optional and for IWG V2 only.
It is highly recommended to use this parameter to filter results and avoid retrieving
huge amounts of data.
Listing Endpoints Response
When endpoints are successfully retrieved, the IWG sends the following response code:
Table 3 List Endpoints Success Response
IWG Version Response Codes
IWG V1
IWG V2
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
Messenger 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 a message. 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
Sending a Message
Applications can send text messages that include an image. Image files are encoded and sent as part of
the message. Supported image file types are PNG and JPEG. Images larger 1500 by 1000 pixels are
scaled down to 1500 by 1000 pixels.
IWG V1 also supports text messages that include an audio or video attachment.
Sending a Message Request
The WFC Messenger expects POST requests in the following format:
Table 6 List Endpoints Request Format
IWG Version URL
IWG V1
POST https://<IWG_URL>/gw/announce/msg?api_password=<token>
or
POST https://<IWG_URL>/announce/msg?api_password=<token>
Messenger REST API Developer Guide
IWG V2
Encode all parameters, except
Table 7 Send Message Parameters
Parameter Description
api_password Secure token found on Administration page of IWG Management Portal.
file Media files are encoded as multipart/form-data into the request body. Video or
Attachment The file type. IWG V1 supports image, audio, and video attachments.
message Text of the message.
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
POST https://<IWG_URL>/api/v1/message?api_password=<token>
api_password, as multipart/form-data in the request body.
audio files are hosted on the IWG and a playback link is added to the text
message. Image files are encoded and sent as part of the message.
IWG V2 supports image attachments only.
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.
Sending a Message Response
The IWG sends a response with one of the following error codes and a reason:
6
Messenger REST API Developer Guide
Table 8 List Endpoints Success Response
IWG Version Response Codes
IWG V1
200 Success
400 Bad Request
500 Internal Error
IWG V2
200 OK
201 Created
401 Unauthorized
403 Forbidden
404 Not found
Uploading a Media File
NOTE: Uploading media files is only supported on IWG V1.
Applications can upload a video or audio file to the IWG host. A successful upload returns a link to the
media file, used for playback by text enabled PTT Pro endpoints.
Media Format
The WFC Messenger supports the following media formats:
Video Format
H.263 video codec (3GP file format)
Audio Format
Advanced Audio Coding (AAC file format)
Uploading a Media File Request
The WFC Messenger expects POST requests in the following format:
Table 9 List Endpoints Request Format
IWG Version URL
IWG V1
IWG V2
Encode all parameters, except
POST https://<IWG_URL>/gw/upload/media?api_password=<token>
or
POST https://<IWG_URL>/upload/media?api_password=<token>
Not supported.
api_password, as multipart/form-data in the request body.
7
Messenger REST API Developer Guide
Uploading a Media File Response
When the upload is successful, the IWG sends the following response code:
200 Success
The body contains a JSON object with the media details in the format:
[
{"status" : 0, "fileName" : <uploaded file name>, "url" : <url for file playback>}
]
If the upload is not successful, the IWG sends a response with one of the following error codes and a
reason:
400 Bad Request
500 Internal Error
Table 10 Uploading a Media File Parameters
Parameter Description
api_password Secure token found on Administration page of IWG Management Portal.
file Media files are encoded as multipart/form-data into the request body. Video or
Attachment The file type (image, video or audio).
Use Cases
Use the WFC Messenger API to:
• Send text messages
• Upload content
• Access content.
Sending Text Messages
In this example, a source application uses the WFC Messenger API to retrieve a list of PTT Pro endpoints
configured for text messaging, and then send a text message.
List Endpoints Request (optional)
audio files are hosted on the IWG and a playback link is added to the text
message. Image files are encoded and sent as part of the message.
The source application sends a GET request to the IWG and retrieves a list of configured PTT Pro
endpoint names and corresponding endpoint IDs (EID). The list is used to send messages to all configured
endpoints, or is displayed to users as a contact list.
8
Messenger REST API Developer Guide
Send Message Request
The source application sends a POST request containing a text message, and one or more EIDs to the
IWG. The IWG sends the text message to the specified PTT Pro endpoints using the proxy client. The PTT
Pro server sends the text message to the recipient list.
If an image is attached, it is sent to the recipients as part of the text message.
Figure 2 Send Text Message
Content Sharing with Automatic Notification
NOTE: Not supported on IWG V2.
In this example, a source application uses the WFC Messenger API to upload a video or audio file to the
IWG. The IWG then sends the media file location in a text message to PTT Pro groups or individuals.
To share content with automatic notifications, the following are required:
• Licensed and configured Messenger endpoint
• Licensed and configured PTT Pro Text endpoint
• Licensed streaming feature.
List Endpoints Request (optional)
The source application sends a GET request to the IWG and retrieves a list of configured PTT Pro
endpoint names and corresponding EIDs. The list is used to send messages to all configured endpoints, or
displays to users as a contact list.
Send Message Request with Content Attachment
The source application sends a text message, media content, and the endpoint IDs of one or more
configured PTT Pro Text endpoints. The IWG stores the content locally and generates a URL to the media
file location, which is inserted into the text message. The IWG forwards the text message to the PTT Pro
server, which sends it to the recipient list.
Message Retrieval
PTT Pro users receive a text message, with the media file URL, through the PTT Pro client application.
When users select the URL, the PTT Pro client accesses the shared content.
9
Messenger REST API Developer Guide
Figure 3 Send Media File with Automatic Notification
Content Sharing with Direct Notification
NOTE: Not supported on IWG V2.
In this example, a source application uses the WFC Messenger API to upload video or audio files to the
IWG and retrieve the media file URL. The source application, or another messaging service, sends the
URL to recipients.
To share content with direct notification, a licensed streaming feature is required.
Upload Request with Content Attachment
The source application uploads an audio or video file to the IWG. The IWG stores the content locally,
generates a URL to the media file location, and returns the URL to the source application.
Forward URL
The source application, or another messaging service, sends the media file URL to recipients.
Message Retrieval
PTT Pro users receive a text message, with the media file URL, through the PTT Pro client application.
When users select the URL, the PTT Pro client accesses the shared content.
10
Messenger REST API Developer Guide
Figure 4 Send Media File with Manual Notification
11
www.zebra.com
Loading...