Version: 0.9.77
Zello server API offers an easy way to interact with Zello server in order to manipulate users and channels from your application. The API compliments Zello (Loudtalks) 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" andstatus 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 (useurlencode() 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 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 server API client libraries
To simplify the use of the API we offer the following client libraries:
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
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" } 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:
| 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. |
| 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". |
| 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. |
| login | POST array | An 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:
| 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/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", } 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", } 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", } 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:
| 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. |
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", "count":"0", "is_shared":0 },{ "name":"Shared", "count":"1", "is_shared":1 },{ "name":"Test", "count":"2", "is_shared":1 } ] } channel/add
Adds a new channel. Request format:
GET /channel/add/name/{name}[/shared/{shared}]?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" |
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", } 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. |
0 Comments