API reference

Server API

Server side interface was designed as a RESTful style API. It provides methods for reading and writing messages.

Write

To write a message or flush messages in channel, you can make an HTTP/HTTPS GET or POST request to the endpoint. 

api.ezcomet.com/write
Arguments
Key Note
api_key This should be your API key given by EZComet.com. Do not expose the API key to public, anyone who has the API key can push messages to your channel. This argument is required.
qname This is a composed value by your username and the channel name as 
username + "-" + channel_name
form. For example, your username in EZComet.com is "john1012", and the channel you want to push is "mychatroom", then the qname should be 
john1012-mychatroom
This argument is required. The maximum length is 64 bytes.
msg The content of message to push. This argument is required. This argument is required when flush is not 1. In other word, when flush argument is 1, this argument will be ignored. The maximum length is 4096 bytes.
tick (optional) The unique ID of message. This argument is optional. If this value is not given, an UUID will be generated and be set as the tick. The maximum length is 64 bytes.
flush (optional) To flush all messages in the channel, set this argument to 1.
Return value

The return value will always be in json format, if the flush is not set, the result will be in 

{"code": "ok", "tick": TICK}
format. If flush is set, the result will be 
{"code": "ok"}
If the write operation failed, an error is returned as 
{"code": "error", "msg": ERROR_MSG, "status": ERROR_CODE}

Example

To write a message, for example, you can issue a POST request to api.ezcomet.com/write like this

POST /write HTTP/1.1
Host: api.ezcomet.com
Content-Type: application/x-www-form-urlencoded
Content-Length: 89

msg=hello+baby%21&api_key=35ac8728bd764e3c80afa2cfa17405cb&qname=john1012-chatroom.public

Read

Coming soon

Javscript API

To subscribe messages in a channel, you can call our Javascript API. First of all, you need to import our script in you page. For HTTP connection, you can use 

<script src="http://cdn.ezcomet.com/ezcomet.min.js"></script>

For HTTPS connection, you can use

<script src="https://d2qw156sj6bo4g.cloudfront.net/ezcomet.min.js"></script>

Please do not download the script file and serve it by yourself. We might update our script.

Once the script file is imported in your page, you can make a call to 

ezcomet.subscribe({
    args1: value1,
    args2: value2
    // ...
})
Arguments
Key Note
user_name Your registered username in EZComet.com.
channel Name of channel to subscribe
callback The callback function to handle received messages. The callback function will be called with one argument, which is the received message.
tick (optional) The begin tick to query messages. If the given tick does not exist in the channel queue, all messages will be returned. Otherwise, messages after the matched tick one will be returned. If the matched one is the last message in the queue, the call will wait until there is new message and return. For example, if you have messages in the queue like this 
tick=1, msg=msg1
tick=2, msg=msg2
tick=3, msg=msg3
tick=4, msg=msg4
tick=5, msg=msg5
When a tick 999 is given, all message will be returned immediately. When a tick 3 is given, msg4 and msg5 will be returned immediately. When a tick 5 is given, the reading operation will blocked and wait until new message pushed and returned. The default value is 'null'. If auto_tick is ture, the tick in cookie will be used automatically.
auto_tick (optional) Store tick in cookie and use it automatically. When this value is true, the last received tick will automatically be stored in cookie. And when the next call to ezcomet.subscribe with auto_tick as ture, the stored tick in cookie will be used as the tick argument for the same channel. In this manner, your page will always receive latest message even after the user refresh the page. If you want to receive old messages or set tick manually, please set this value to false.
msg_type (optional) How should the received message be processed. It could be one of "string", "json" and "raw". When "string" is given, the received message be passed to your callback will be message string. When "json" is given, the received message will be parsed as JSON object. When "raw" is given, a [tick, msg] object will be passed to your callback. The default value is "string".