Zello server API reference

Version: 1.1.0

The Zello server API offers an easy way to interact with the Zello server in order to manipulate users and channels from your application. The API compliments the Zello push-to-talk SDK which allows you to seamlessly integrate push-to-talk into your Android, Windows or Windows Mobile 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, which you can use to accomplish that (use 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 ZelloWork admin console or in Zello Enterprise Server configuration file as follows:

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 server API client libraries

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

Notation

This document uses the following notation for requests description:

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

NameDescription
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.
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.

Authentication

user/gettoken

Gets security token — login first phase.
Request format:
GET /user/gettoken
        
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
tokenStringSecure token required for login API method.
sidStringSession ID. Pass this value as sid GET parameter to all successful API calls.
Successful response example:
{
    "status":"OK",
    "code":"200",
    "token":"rm7s6g1e3zfujs5fxzc095sw0dp04arl",
    "sid":"ad7e61e520fa4167b5ea1489c7e04f8d"
}
        

user/login

Authenticates the user and starts API session — login second phase.
Request format:
POST /user/login?sid={sid}

username={username}&password={password}
        
Request fields:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
usernamePOSTUsername of the administrative user accessing the app.
passwordPOSTAuthentication 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:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
loginGET(Optional) Username of the user to fetch. If omitted all users will be returned.
gatewayGET(Optional) Gateway users filter. Set to "true" for gateways, omit for normal users.
maxGET(Optional) Maximum number of results to fetch.
startGET(Optional) Index of the first result to fetch.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
usersArrayAn array containing user details objects. See response example below.
limitsObjectRestrictions on number of users and gateways imposed by your current service plan or license. See response example below.
canAddUsersBooleanIndicates, whether more users can be added.
canAddGatewaysBooleanIndicates, 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
namePOSTUsername of the user to be updated. If user doesn't exist the new one is created.
passwordPOST(Optional if user already exists) The md5 hash of the new user password.
emailPOST(Optional) User's e-mail address. Required for forgot password function.
full_namePOST(Optional) Alias used to display the user in contacts.
jobPOST(Optional) User position.
adminPOST(Optional) "true" or "false". Grant or not web-console (and API) access to that user. Default is "false".
limited_accessPOST(Optional) "true" or "false". Restrict or not user's ability to start one-on-one conversations. Default is "false".
gatewayPOST(Optional) "true" or "false". Defines whether the user a gateway. Default is "false".
addPOST(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:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
loginPOST arrayAn array of usernames of users to be deleted. Here is an example of logins array formatted as POST array.

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

represents the following array

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

Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
channelGETChannel name.
loginPOST arrayAn array of usernames of users to be added to the channel. See user/delete
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
usersPOST arrayAn array of usernames of users to be added to the channels.
channelsPOST arrayAn array of channel names for users to be added to.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
channelGETChannel name.
loginPOST arrayAn array of usernames of users to be removed from the channel. See user/delete
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
usersPOST arrayAn array of usernames of users to be removed from the channels.
channelsPOST arrayAn array of channel names for users to be removed from.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
usernameGETUsername of the user, where the contacts will be added.
loginPOST arrayAn array of usernames of users to be added to the contacts. See user/delete
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
usernameGETUsername of the user from who the contacts will be removed.
loginPOST arrayAn array of usernames of users to be removed from the direct contacts. See user/delete
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
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}]?sid={sid}
        
Request fields:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
nameGET(Optional) Name of the channel to fetch. If omitted all channels will be returned.
maxGET(Optional) Maximum number of results to fetch.
startGET(Optional) Index of the first result to fetch.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
channelsArrayAn array containing channel details objects. See response example below.
Successful response example:
{
    "status":"OK",
    "code":"200",
    "channels":[
    {
        "name":"Dynamic",
        "count":"0",
        "is_shared":0,
        "is_invisible":0
    },{
        "name":"Shared",
        "count":"1",
        "is_shared":1,
        "is_invisible":0
    },{
        "name":"Test",
        "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}]?sid={sid}
        
Request fields:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
nameGETChannel name. If channel with such name already exists the error will be returned.
sharedGET(Optional) "true" or "false". Set to "true" to create group channel, set to "false" to create dynamic channel. Default is "false"
invisibleGET(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"
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
namePOST arrayAn array of names of channels to be deleted. See user/delete
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
Successful response example:
{
    "status":"OK",
    "code":"200",

}
        

channel/roleslist

Get channel roles list.
Request format:
GET /channel/roleslsit/name/{name}?sid={sid}
        
Request fields:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
nameGETChannel name.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
rolesArrayAn 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
channelnameGETChannel name.
nameGETRole name. If role with this name already exists, it will be updated with new params.
settingsPOSTRole settings.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
channelnameGETChannel name.
nameGETRole name. If role name is empty, role assignments are being reset for these users.
loginPOST arrayAn array of usernames of users to be assigned to this role in this channel.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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:
NameTypeDescription
sidGETSession ID received in response to gettoken call.
channelnameGETChannel name.
rolesPOST arrayAn array of roles names to delete.
Response fields:
NameTypeDescription
statusStringStatus message — "OK" or error description.
codeStringStatus 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}][&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
sidGETSession 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
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 type. Supported values are:
  • voice
  • image
  • call_alert
ts Integer Epoch timestamp of when the message was sent
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
recipient_type String "user" or "channel"
media_key String Key, which can be used to download media associated with the message. Note: This field won't be present if type of the 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.
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
sidGETSession 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
}

Error codes

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