Zello server API reference

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

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/deleteDeletes users.
user/addtoAdds users to the channel.
user/removefrom Removes users from the channel.
user/addcontactsto Adds users as direct contacts to the user.
user/removecontactsfrom Removes users from direct contacts of the user.
channel/getGets the list of the channels or detailed information regarding a particular channel.
channel/addAdds a new channel.
channel/deleteDeletes channels.

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:
NameType Description
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:
NameType Description
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:
NameType Description
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:
NameType Description
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:
NameType Description
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:
NameType Description
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:
NameType Description
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:
NameType Description
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      },{          "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:
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"
Response fields:
NameType Description
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:
NameType Description
statusStringStatus message — "OK" or error description.
codeStringStatus code — "200" or error code.
Successful response example:
{      "status":"OK",      "code":"200",    }          

Error codes

CodeDescription
301Unauthenticated. User credentials missing.
302 Unauthorized. 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.
504 Error communicating to Zello login server.
519Zello login server retuned an error.
520Server failed to update user's password.
605Missing required parameters.

0 Ulasan:

Related Posts Plugin for WordPress, Blogger...