ZEBRA MN-003113-12EN Workcloud Communication Messenger User Guide
- June 13, 2024
- ZEBRA
Table of Contents
Workcloud
Communication
Messenger REST API
Developer Guide
MN-003113-12EN Workcloud Communication Messenger
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 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
April 8, 2024
Introduction
This document describes how to send text messages to the Zebra Enterprise
Messaging Service (ZEMS) using the REST API.
The ZEMS provides a method for third-party applications to send text messages
to PTT Pro client. The ZEMS formats the text message and then forwards it to
the specified PTT Pro endpoint(s). The message can include an image file.
Use the Messenger REST API to:
- List endpoints
- Send a message
- Include an image with the message.
Authentication
The 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.
Messenger Endpoints
Applications use the ZEMS Messenger API to retrieve a list of endpoints.
List Endpoints Request
Send a GET request in the following format:
GET https://
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, ZEMS sends the following response
code:
Table 2 List Endpoints Success Response
Response Codes
200 Successfully retrieved list
{
“site”: “IwgDept1”,
“name”: “EP.test.1”,
“proxy”: “EP.test.1.proxy1”,
“target”: “test.user.01”,
“contact”: true
}
Table 3 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 ZEMS sends a response with one of the
following error codes:
Table 4 List Endpoints Error Responses
| Response Codes | Description |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized access. |
| 404 | Record not found. |
| 503 | Server error. |
Sending a Message
Applications can send text messages that include an image. Image files are
encoded and sent as part of the message. Any image type is supported. ZEMS
converts the image to PNG and proportionally resizes the image to a maximum
width of 640 pixels.
Sending a Message Request
Send a POST request in the following format:
POST https://
Table 5 Send Message Parameters
| Parameter | Description |
|---|---|
| api_password | Secure token. |
| file | Image files are encoded into the request body. |
| message | Text of the message. |
| eid | Target endpoint ID or from retrieving the endpoint list. Only a single |
EID can be specified for each message.
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 a
multipart/form-data in the request body.
Sending a Message Response
The API sends a response with one of the following error codes and a reason:
Table 6 Send Message Responses
| Response Codes | Description |
|---|---|
| 200 | OK |
| 400 | Bad request. |
| 401 | Unauthorized access. |
| 404 | Record not found. |
| 503 | Server error |