Zello Work API Reference

Version: 1.1.0

The Zello Work API offers an easy way to interact with Zello servers in order to manipulate users and channels from your application. The API complements the Zello push-to-talk SDK which allows you to seamlessly integrate push-to-talk into your Android, or Windows application.

Overview

The API is based on JSON over HTTP protocol. Requests are sent using GET and POST HTTP requests, server responses are returned in HTTP response body and presented in JSON. Each response includes "status" and "code" fields, indicating the response success status or error details. In the case of success, code is "200" and status is "OK". Successful response example:

{
    "status":"OK",
    "code":"200"
}

Error response example:

{
    "status":"Unauthorized",
    "code":"301"
}

The list of possible error codes.

All values you send to the server as GET parameters must be url-encoded. Most programming languages offer functions to accomplish this, such as urlencode() in PHP, encodeURIComponent() in JavaScript, and URLEncoder.encode() in Java).

Security model

API key

To access the API you need to enable API access in your Zello Work admin console or in the Zello Enterprise Server configuration file as follows:

Zello Work: Log in to the admin console. On the Dashboard under Account section click Get API key
Zello Enterprise Server: Set API_KEY define in common_params.cfg.php to any alpha-numeric sequence.

Application authentication

Before accessing the API functions the application must authenticate using API key and administrative user username and password. If authentication was successful the Session ID returned should be use for all future API calls. See authentication methods description for details. When the application ends working with the API (for example the user logs out) it should use logout API method to end the session and clear the Session ID.

Zello Work API client libraries

To simplify the use of the API we offer client libraries for PHP, Java, C#, Objective C, and Swift:

View at Github

Notation

This document uses the following notation for requests description:

Curly brackets "{}" denote parameter values. When using the API replace them with the actual values i.e GET user/get/login/{username} becomes GET user/get/login/Test1, where Test1 is the username of the user for which you want to get the details.
Square brackets "[]" denote optional parameters. I.e. in GET user/get[/login/{username}] request specifying /login/{username} part of the URL is optional.

Responses format is JSON, where "{", "}", "[", and "]" are part of the syntax.

POST methods format uses two lines, separated by an empty line:

POST /something		<- Request URL

foo=bar&a=b		<- Request data

API methods

Name	Description
user/gettoken	Gets security token — login first phase.
user/login	Authenticates the user and starts API session — login second phase.
user/get	Gets the list of the users or detailed information regarding a particular user.
user/save	Adds or updates the user.
user/delete	Deletes users.
user/addto	Adds users to the channel.
user/addtochannels	Adds users to channels.
user/removefrom	Removes users from the channel.
user/removefromchannels	Removes users from channels.
user/addcontactsto	Adds users as direct contacts to the user.
user/removecontactsfrom	Removes users from direct contacts of the user.
user/assigntemplate	Assigns a template to a set of users.
channel/get	Gets the list of the channels or detailed information regarding a particular channel.
channel/add	Adds a new channel.
channel/delete	Deletes channels.
channel/roleslist	Returns list of channel roles.
channel/saverole	Create or update role.
channel/addtorole	Assign channel role to users in channel.
channel/deleterole	Delete channel role.
history/getmetadata	Returns metadata for saved history messages based on filtering criteria, specified in the request.
history/getmedia	Requests media by media key from the recording server.
location/get	Retrieves current location data for users in your network.
location/getuser	Retrieves current or historical location data for a specific user.

Authentication

user/gettoken

Gets security token — login first phase.

Request format:

GET /user/gettoken

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
token	String	Secure token required for login API method.
sid	String	Session ID. Pass this value as sid GET parameter to all successful API calls.

Successful response example:

{
    "status":"OK",
    "code":"200",
    "token":"rm7s6g1e3zfujs5fxzc095sw0dp04arl",
    "sid":"ad7e61e520fa4167b5ea1489c7e04f8d"
}

Authenticates the user and starts API session — login second phase.

Request format:

POST /user/login?sid={sid}

username={username}&password={password}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
username	POST	Username of the administrative user accessing the app.
password	POST	Authentication passphrase constructed as md5(md5({password}) + {token} + {api_key}). That is md5 hash of md5 of user's password concatenated with the token received in response to gettoken and concatenated with API key.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/logout

Logs user out and ends the session.

Request format:

GET /user/logout?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

Users management

user/get

Gets the list of the users or detailed information regarding a particular user.

Request format:

GET /user/get[/login/{login}][/gateway/{gateway}][/max/{max}][/start/{start}]?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
login	GET	(Optional) Username of the user to fetch. If omitted all users will be returned.
gateway	GET	(Optional) Gateway users filter. Set to "true" for gateways, omit for normal users.
max	GET	(Optional) Maximum number of results to fetch.
start	GET	(Optional) Index of the first result to fetch.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
users	Array	An array containing user details objects. See response example below.
limits	Object	Restrictions on number of users and gateways imposed by your current service plan or license. See response example below.
canAddUsers	Boolean	Indicates, whether more users can be added.
canAddGateways	Boolean	Indicates, whether more gateways can be added.

Successful response example:

{
    "status":"OK",
    "code":"200",
    "users":[
	{
	    "name":"A very long user name",
	    "email":"",
	    "admin":true,
	    "limited_access":false,
	    "job":"",
	    "full_name":"",
	    "channels":[]
	},{
	    "name":"john",
	    "email":"",
	    "admin":true,
	    "limited_access":false,
	    "job":"",
	    "full_name":"John",
	    "channels":["Shared"]
	},{
	    "name":"alex",
	    "email":"alex@zello.com",
	    "admin":false,
	    "limited_access":false,
	    "job":"",
	    "full_name":"Алексей Гаврилов",
	    "channels":["Test", "Shared"]
	}
    ],
    "limits":{
        "maxUsers":"10",
        "maxGateways":"2"
    },
    "canAddUsers":true,
    "canAddGateways":true
}

user/save

Adds or updates the user. If username exists, the user is updated, otherwise new user is created.

Request format:

POST /user/save?sid={sid}

name={name}&password={password}&email={email}&full_name={full_name}&job={job}&admin={admin}&limited_access={limited_access}&gateway={gateway}&add={add}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
name	POST	Username of the user to be updated. If user doesn't exist the new one is created.
password	POST	(Optional if user already exists) The md5 hash of the new user password.
email	POST	(Optional) User's e-mail address. Required for forgot password function.
profile_phone	POST	(Optional) User's phone number in international format, country code required ( + sign at the beginning is not required).
full_name	POST	(Optional) Alias used to display the user in contacts.
job	POST	(Optional) User position.
admin	POST	(Optional) "true" or "false". Grant or not web-console (and API) access to that user. Default is "false".
limited_access	POST	(Optional) "true" or "false". Restrict or not user's ability to start one-on-one conversations. Default is "false".
gateway	POST	(Optional) "true" or "false". Defines whether the user a gateway. Default is "false".
tags	POST	(Optional) A comma separated list of tag names to assign to the user, like "tag1,tag2". Default is empty (no tags assigned).
add	POST	(Optional) "true" or "false". Force adding a user. If this parameter is set to "true" the method will give an error when trying to update existing user. Default is "false".

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/delete

Deletes users.

Request format:

POST /user/delete?sid={sid}

{login}

Request fields:

Name

Type

Description

sid

GET

Session ID received in response to gettoken call.

POST array

An array of usernames of users to be deleted. Here is an example of logins array formatted as POST array.

represents the following array

["test", "test 2", "test3"]

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Request example:

POST /user/delete?sid=cf48c88ac8732da3bc88bf9b6858ec85

login[]=test&login[]=test%202&login[]=test3

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/addto

Adds users to the channel.

Request format:

POST /user/addto/{channel}?sid={sid}

{login}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
channel	GET	Channel name.
login	POST array	An array of usernames of users to be added to the channel. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/addtochannels

Adds users to channels.

Request format:

  POST /user/addtochannels?sid={sid}
  
  {users}{channels}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
users	POST array	An array of usernames of users to be added to the channels.
channels	POST array	An array of channel names for users to be added to.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"  
}

user/removefrom

Removes users from the channel.

Request format:

POST /user/removefrom/{channel}?sid={sid}

{login}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
channel	GET	Channel name.
login	POST array	An array of usernames of users to be removed from the channel. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/removefromchannels

Removes users from channels.

Request format:

  POST /user/removefromchannels?sid={sid}
  
  {users}{channels}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
users	POST array	An array of usernames of users to be removed from the channels.
channels	POST array	An array of channel names for users to be removed from.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/addcontactsto

Adds users to the user's direct contacts.

Request format:

POST /user/addcontactsto/{username}?sid={sid}

{login}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
username	GET	Username of the user, where the contacts will be added.
login	POST array	An array of usernames of users to be added to the contacts. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/removecontactsfrom

Removes users from direct contacts of the user.

Request format:

POST /user/removecontactsfrom/{username}?sid={sid}

{login}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
username	GET	Username of the user from who the contacts will be removed.
login	POST array	An array of usernames of users to be removed from the direct contacts. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

user/assigntemplate

Assigns a template to a set of users.

Request format:

POST /user/assigntemplate/name/{template}?sid={sid}

{users}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to the gettoken call.
template	GET	The name of the template that will be assigned. Use empty string to reset template assignment.
users	POST array	An array of usernames of users to assign the template. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Request example:

POST /user/assigntemplate/name/drivers?sid=cf48c88ac8732da3bc88bf9b6858ec85

users[]=driverA&users[]=driverB&users[]=driverC

Successful response example:


{
    "status":"OK",
    "code":"200"
}

Channels management

channel/get

Gets the list of the channels or detailed information regarding a particular channel.

Request format:

GET /channel/get[/name/{name}][/max/{max}][/start/{start}][/tags/{tags}][/search/{search}]?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
name	GET	(Optional) Name of the channel to fetch. If omitted all channels will be returned.
max	GET	(Optional) Maximum number of results to fetch.
start	GET	(Optional) Index of the first result to fetch.
tags	GET	(Optional) A comma separated list of tag names to filter returned channels, e.g. "tag1,tag2".
search	GET	(Optional) Text to filter the returned list by partial, case-insensitive match of the channel name, e.g. "zello" could return channels "Zello", "Zello 1", "Zello 2".

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
channels	Array	An array containing channel details objects. See response example below.

Successful response example:

{
    "status":"OK",
    "code":"200",
    "channels":[
    {
        "name":"Dynamic",
        "created": "2024-05-08 12:36:19",
        "count":"0",
        "is_shared":0,
        "is_invisible":0
    },{
        "name":"Shared",
        "created": "2024-05-08 12:36:19",
        "count":"1",
        "is_shared":1,
        "is_invisible":0
    },{
        "name":"Test",
        "created": "2024-05-08 12:36:19",
        "count":"2",
        "is_shared":1,
        "is_invisible":1
    }
    ]
}

channel/add

Adds a new channel.

Request format:

GET /channel/add/name/{name}[/shared/{shared}][/invisible/{invisible}][/tags/{tags}]?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
name	GET	Channel name. If channel with such name already exists the error will be returned.
shared	GET	(Optional) "true" or "false". Set to "true" to create group channel, set to "false" to create dynamic channel. Default is "false"
invisible	GET	(Optional) "true" or "false". Set to "true" in combination with shared=true to create a hidden group channel. When combined with shared=false the behavior is not defined. Default is "false"
tags	GET	(Optional) A comma separated list of tag names to assign to the channel, like "tag1,tag2". Default is empty (no tags assigned).

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

channel/delete

Deletes channels.

Request format:

POST /channel/delete?sid={sid}

{name}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
name	POST array	An array of names of channels to be deleted. See user/delete

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Successful response example:

{
    "status":"OK",
    "code":"200"
}

channel/roleslist

Get channel roles list.

Request format:

GET /channel/roleslist/name/{name}?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
name	GET	Channel name.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
roles	Array	An array containing channel roles objects list. See response example below.

Successful response example:

{
    "status":"OK",
    "code":"200",
	"roles": [{
		"name": "dispatchers",
		"settings": {
			"listen_only": false,
			"no_disconnect": true,
			"allow_alerts": true,
			"to": ["dispatchers", "dispatchers", "drivers", "security"]
		}
	}, {
		"name": "drivers",
		"settings": {
			"listen_only": false,
			"no_disconnect": true,
			"allow_alerts": false,
			"to": ["dispatchers"]
		}
	}, {
		"name": "security",
		"settings": {
			"listen_only": true,
			"no_disconnect": true,
			"allow_alerts": true,
			"to": []
		}
	}, {
		"name": "superusers",
		"settings": {
			"listen_only": false,
			"no_disconnect": false,
			"allow_alerts": true,
			"to": []
		}
	}]
}

channel/saverole

Create or update channel role.

Request format:

POST /channel/saverole/channel/{channelname}/name/{name}?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
channelname	GET	Channel name.
name	GET	Role name. If role with this name already exists, it will be updated with new params.
settings	POST	Role settings.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Request example:

POST /channel/saverole/channel/Everyone/name/drivers?sid=cf48c88ac8732da3bc88bf9b6858ec85

settings={"listen_only": false, "no_disconnect": true, "allow_alerts": false, "to": ["dispatchers"]}

Successful response example:

{
    "status":"OK",
    "code":"200"
}

channel/addtorole

Assign users to a channel role (or reset assignments).

Request format:

POST /channel/addtorole/channel/{channelname}/name/[{rolename}]/?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
channelname	GET	Channel name.
name	GET	Role name. If role name is empty, role assignments are being reset for these users.
login	POST array	An array of usernames of users to be assigned to this role in this channel.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Request example:

POST /channel/addtorole/channel/Everyone/name/drivers?sid=cf48c88ac8732da3bc88bf9b6858ec85

login[]=driverA&login[]=driverB&login[]=driverC

Successful response example:

{
    "status":"OK",
    "code":"200"
}

channel/deleterole

Delete channel role(s). When channel role is deleted, role assignments are being reset to users who was assigned to this tole.

Request format:

POST /channel/deleterole/channel/{channelname}/?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
channelname	GET	Channel name.
roles	POST array	An array of roles names to delete.

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.

Request example:

POST /channel/deleterole/channel/Everyone?sid=cf48c88ac8732da3bc88bf9b6858ec85

roles[]=drivers&roles[]=testRole

Successful response example:

{
    "status":"OK",
    "code":"200"
}

Zello recordings access

history/getmetadata

Returns metadata for saved history messages based on filtering criteria, specified in the request. All filters are optional, the last 100 messages from the network are returned by default.

Request format:

POST /history/getmetadata?sid={sid}

[sender={sender}][&recipient={recipient}][&via_channel={via_channel}][&is_channel={is_channel}][&type={type}]
[&text={text}][&eid={eid}][&call_id={call_id}][&start_ts={start_ts}][&end_ts={end_ts}][&start_id={start_id}]
[&end_id={end_id}][&max={max}][&start={start}][&sort={sort}][&sort_order={sort_order}]

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
sender	POST String	(Optional) Username of the user, who sent the messages. If omitted messages from all senders will be included.
recipient	POST String	(Optional) Username of the user, who received the messages (either directly or through a channel). If omitted the messages to all recipients will be included.
via_channel	POST String	(Optional) If provided, limit messages returned to the messages, delivered through specified channel. Setting this filter automatically overrides is_channel filter to true.
is_channel	POST Boolean	(Optional) If set to true, only messages sent through channels will be included. If set to false only direct messages will be included. If omitted all messages will be included.
type	POST String	(Optional) Filter by media type. Supported values are: voice image call_alert If omitted all media types will be included.
text	POST String	(Optional) Text to search in call alerts text
call_id	POST Integer	(Optional) Filter by dispatch call id. If provided, only messages associated with the specified call will be returned.
eid	POST String	(Optional) Filter by external id. If provided, only messages associated with the specified id will be returned. eid will not be set by default. SDK consumers can optionally specify it when sending a message through the SDK.
start_ts	POST Integer	(Optional) Epoch timestamp. If provided only messages sent after the specified time will be returned.
end_ts	POST Integer	(Optional) Epoch timestamp. If provided only messages sent before the specified time will be returned. Must be greater than start_ts.
start_id	POST Integer	(Optional) If provided, only messages with id equal or greater than start_id will be included in the response.
end_id	POST Integer	(Optional) If provided, only messages with id equal or less than end_id will be included in the response. Must be greater or equal to start_id.
max	POST Integer	(Optional) Maximum number of messages to include in the response. Used for pagination of results.
start	POST Integer	(Optional) The index of the first message to include in the response. Used for pagination of results.
sort	POST String	(Optional) Field that result messages will be sorted by. By default results are sorted by id field. All fields from message object can be used for sorting except channel_users and text
sort_order	POST String	(Optional) Sort direction. Supported values are: desc and asc. Default is desc

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
total	Integer	Total number of messages matching the query
returned	Integer	Number of messages returned. It may be less than total due to effect of max attribute and also limitations set by the API.
messages	Array	An array of JSON objects, representing history metadata. The results are sorted in reverse chronological order (newest first).

message object fields

Name	Type	Description
id	Integer	Message id. Message id is auto-increment field uniquely identifying messages.
type	String	Message media or event type. Supported values are: voice image call_alert start_call take_call end_call
ts	Integer	Epoch timestamp of when the message was sent
call_id	Integer	Dispatch call ID associated with the message.
call_id_short	Integer	An abbreviated form of the dispatch call ID associated with the message (may NOT be unique across pages)
eid	String	External ID of the message. Note: This field will only be present if original message had it.
sender	String	Username of the sender of the message
recipient ^[1]	String	Username or channel name
dispatch_call_recipient	String	The username of the receiver of a call message
recipient_type	String	The type of recipient associated with the message. Values are: user channel dispatch_call
media_key	String	Key which can be used to download media associated with the message. Note: This field won't be present if the type of message is `call_alert`
duration	Integer	Voice message duration in milliseconds. Note: This field will only be present if type of the message is voice
channel_users	Array	An array of strings, representing usernames of users, who received the message through a channel. Note: This field will only be present recipient_type is channel.
image_ts	Integer	Epoch timestamp of when the image was taken Note: This field may only be present if type of the message is image. In some cases this timestamp will be unavailable.
image_source	String	"camera" or "library" Note: This field will only be present if type of the message is image.
text	String	Call alert text as sent in the message. It could be empty. Note: This field will only be present if type of the message is call_alert.
transcription	String	Voice message transcription. It could be empty. Note: This field will only be present if type of the message is voice.
transcription_inaccurate	String	"yes" is transcription is inaccurate and "no" otherwise.

Successful response example:

{
    "status": "OK",
    "code": "200",
    "total": 532,
    "returned": 20,
    "messages": [
        {
            "id": 5634258,
            "type": "voice",
            "ts": 1418944471,
            "sender":"alex",
            "recipient":"Everyone",
            "recipient_type": "channel",
            "media_key":"8417df672fff10c141e36c9778cde2fa",
            "duration": 9200,
            "channel_users": ["john","chris","molly","admin"]
        },
        {
            "id": 5634257,
            "type": "voice",
            "ts": 1418904471,
            "sender":"admin",
            "recipient":"Everyone",
            "recipient_type": "channel",
            "media_key":"8417df672fff10c141e36c9778cde2fa",
            "duration": 12100,
            "channel_users": ["john","chris","molly","alex"]
        },
        {
            "id": 5634256,
            "type": "image",
            "ts": 1418844400,
            "sender":"alex",
            "recipient":"admin",
            "recipient_type": "user",
            "media_key":"8417df672fff10c141e36c9778cde2fa",
            "image_ts": 1418840400,
            "image_source": "camera"
        },
        {
            "id": 5634255,
            "type": "call_alert",
            "ts": 1418834000,
            "sender":"alex",
            "recipient":"molly",
            "recipient_type": "user",
            "text":"Zello me!"
        }
    ]
}

history/getmedia

Requests media by media key from the recording server.

Depending on media type it may require additional time on conversion. The client must use long-poll method and keep the connection open until it receives server response, or there is a timeout.

The timeout should be set to at least 30 seconds. If the request was terminated on timeout without server returning any error, it needs to be repeated.

Since the operation is CPU intensive and potentially long running there will be throttling limiting the maximum number of concurrent requests per network and API key.

Request format:

GET /history/getmedia/key/{key}?sid={sid}

Request fields:

Name	Type	Description
sid	GET	Session ID received in response to gettoken call.
key	GET String	Media key extracted from metadata, retrieved using history/getmetadata call.

Response fields:

Name	Type	Description
status	String	Status message — "OK", "Waiting", "Working" or error description.
code	String	Status code — "200", "201", "202" or error code.
type	String	Media type. Supported media types are: voice image
url	String	Use this URL to download the media. Note that the URL may be https and may include redirects.
expires	Integer	Epoch timestamp when the cached media expires. If you try to download it after, you'll get 404 Not Found error.
progress	Integer	Current operation progress in %. Will be sent by server periodically if operation taking longer than 20 seconds to complete. The status will be set to "Waiting" (then progress reflects operation place in execution queue) or "Working" (then progress will reflect conversion progress).

Successful response examples

Voice media is ready

{
    "status": "OK",
    "code": "200",
    "type": "voice",
    "url": "https://mesh.zellowork.com/media/8417df672fff10c141e36c97.mp3",
    "expires": 1418834000
}

Image media is ready

{
    "status": "OK",
    "code": "200",
    "type": "image",
    "url": "https://mesh.zellowork.com/media/8417df672fff10c141e36c97.jpg",
    "expires": 1418834060
}

Conversion is in progress

{
    "status": "Waiting",
    "code": "200",
    "type": "voice",
    "progress": 0
}

Location Services

location/get

Retrieves current location data for users in your network based on given query criteria.

Request format:

GET /location/get?sid={sid}

Request fields:

Name

Request Type

Field Type

Description

sid

GET

String

Session ID received in response to gettoken call.

northeast

GET

Float Array

The latitude/longitude pair of the top right corner of a bounding box. These should be passed as a tuple, ie

northeast%5B%5D=32.872653601619405&northeast%5B%5D=-96.70730593579101

southwest

GET

Float Array

The latitude/longitude pair of the bottom left corner of a bounding box. These should be passed as a tuple, ie

southwest%5B%5D=32.79563084997798&southwest%5B%5D=-96.89785006420898

name

GET

String

(Optional) Text to match specific usernames or display names

filter

GET

String

(Optional) Filter criteria to apply to results. By default, only active users (reports within the last 20 minutes) within the given geographic bounds will be returned.

Value	Description
active	Returns all active users, not just those within the given bounding box
none	Returns all users regardless of status and geography

start

GET

Integer

(Optional) The starting index of results to return, 0-based. Defaults to 0

max

GET

Integer

(Optional) The maximum number of results to return. Defaults to a system page size, usually 100

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
total	Integer	The total number of users with locations
returned	Integer	The number of users returned in this response
locations	Array of Objects	Contains location data for qualifying users.

locations object fields

Name	Type	Description
username	String	The name of the user
displayName	String	The display name of the user
latitude	Float	The latitude of the user's last reported location
longitude	Float	The longitude of the user's last reported location
speed	Float	The speed, in km/h (or miles/hr if requested by the `speedUnits` parameter), at the time of the user's last report
heading	Float	The heading, or bearing, of the location at the time of the last report
altitude	Float	The elevation in meters of the last report
batteryLevel	Integer	The battery level of the device at the time of the last report, on a scale from 0-100
chargingStatus	Integer	The charging status of the device, 0 = unknown, 1 = charging, 2 = plugged in
signalStrength	Float	The cellular signal strength at the time of the last report
accuracy	Float	The accuracy, in meters, of the positional fix from the last report
visible	Boolean	Whether the user is within the bounds of the box specified on the request
status	String	The application status at the time of the last report - 'standby', 'online'
geoTrackingDisabled	Boolean	Whether location reporting is administratively disabled for this user
lastReport	Integer	The epoch time (seconds) of the last report
lastReportDelay	Integer	The age of the report, in seconds

Successful response example:

{
	"status":"OK",
	"code":"200",
	"total":1,
	"returned":1,
	"locations":
		[
			{
				"username":"chris",
				"displayName":"Topher",
				"latitude":38.889227,
				"longitude":-76.991157,
				"speed":11.089269508799,
				"heading":0,
				"altitude":11.936082696983,
				"batteryLevel":0,
				"chargingStatus":0,
				"signalStrength":0.39600170068742,
				"visible":false,
				"geotrackingDisabled":false,
				"accuracy":33.430532395357,
				"status":"standby",
				"lastReport":1502569992,
				"lastReportDelay":248764
			}
		]
}

location/getuser

Retrieves current location data for users in your network based on given query criteria.

Request format:

GET /location/getuser/{username}[/history]?sid={sid}

Request fields:

Name	Request Type	Field Type	Description
username	Path	String	Username of the user whose location data to retrieve
history	Path	String	(Optional) If present and enabled for your network, will retrieve historical location data
sid	GET	String	Session ID received in response to gettoken call.
start_ts	GET	Integer	For history, the unix timestamp of the start date and time to retrieve history
end_ts	GET	Integer	For history, the unix timestamp of the end date and time to retrieve history
format	GET	String	(Optional) For history, the response format. The only supported value is `geojson`, which will return locations as a GeoJson feature collection.
speedUnits	GET	String	(Optional) For history, the units for speed values. Supported values are `mph` (miles per hour) and `kmh` (kilometers per hour). If no units are specified, kilometers per hour is the default.
start	GET	Integer	(Optional) The starting index of results to return, 0-based. Defaults to 0
max	GET	Integer	(Optional) The maximum number of results to return. Defaults to a system page size, usually 100

Response fields:

Name	Type	Description
status	String	Status message — "OK" or error description.
code	String	Status code — "200" or error code.
total	Integer	The total number of locations in the given time period
returned	Integer	The number of locations returned in this response
locations	Array of Locations	Location records with a subset of the fields described above. The following fields will not be present: username, displayName, visible, geoTrackingDisabled, status, and lastReportDelay. An additional id field of type GUID will represent the unique ID of the report.

Successful response example:

{
	"status":"OK",
	"code":"200",
	"total":305,
	"returned":305,
	"locations":
		[
			{
				"latitude":32.804057,
				"longitude":-96.787544,
				"batteryLevel":11,
				"chargingStatus":0,
				"speed":17.41948729151,
				"lastReport":1501172077,
				"accuracy":67.529829624052,
				"id":"6fe852717f4317d4f4ee1db4f5c73e29"
			}
		]
}

Error codes

Code	Description
301	Unauthenticated. User credentials missing.
302	Unauthorized. Login is OK but the user doesn't have admin rights.
303	Invalid username or password.
305	Missing auth token.
400	Bad request. Most likely a typo in the method name.
404	Resource not found. User or channel requested doesn't exist
405	Resource already exists.
407	Limits reached. The license or service plan doesn't allow to add more users.
501	Database error.
504	Error communicating to Zello login server.
519	Zello login server retuned an error.
520	Server failed to update user's password.
605	Missing required parameters.

^[1] Multi-recipient messages (supported in Windows only), are a client-side feature and will be saved separately for each recipient despite having the same content.