Beebotte provides a javascript library to allow a web page to interact with the platform in real time. This communication uses a websocket connection between the browser and Beebotte. In the following, we provide a description of this javascript client API.
This is the basic object that initiates and manages the websocket connection with Beebotte. It mantains as well the state of subscriptions and permission grants.
This Object must be created to use the client API. It has the API_KEY as a mandatory parameter.
var bbt = new BBT(API_KEY, options);
parameters:
API_KEY: API key associated with your Beebotte account
options: optional parameters for initializing beebotte
{
auth_endpoint: authentication endpoint URL
auth_method: HTTP method (Get or Post) to be used for authentication requests
server: URL to beebotte. default beebotte.com
ssl: boolean - indicates whether ssl should be used. default false.
userinfo: JSON object - assigns custom user defined information to the connection. This parameter will be passed to the authenticator (given by the auth_endpoint). Beebotte will completely ignore this parameter.
username: string - assigns a friendly username to the connection. Overrides username parameter when present in userinfo.
}
Example:
var bbt = new BBT('1234567890', {auth_endpoint: '//mysite.com/auth', server: 'beebotte.com', userinfo: {username: 'my name', token: 'user_token'});Connects this instance to the Beebotte platform if it is not connected. This method will be automatically called when creating a new instance of BBT.
bbt.connect();
Disconnets the websocket connection with beebotte. This will unsubscribe existing subscriptions and cancel granted permissions.
bbt.disconnect();
Adds a callback listener to the specified resource that will be called whenever a message associated with the resource is routed by Beebotte (through transient or persistent messages). If the 'channel' parameter is prefixed by 'private-' or 'presence-', this method will automatically trigger the authentication mechanism.
bbt.subscribe(args, callback);
Parameters:
args: {
{string, required} channel: name of the channel. It can be prefixed with 'private-' to indicate a private resource, or it can be prefixed with 'presence-' to indicate presence events.
{string, optional} resource: name of the resource.
{number, optional} ttl: time in milliseconds during which the subscription will be active. This option is for future support.
{boolean, optional} read: Indicates if a read permission is requested. Defaults to true.
{boolean, optional} write: write permission requested along the subscription. This gives the possibility to publish or write messages to the specified resource. Defaults to false.
{function, optional} callback: function to be called when a message is received.
}
callback: function to be called when a message is received. args.callback element will override this parameter if it is present.
Example:
bbt.subscribe({channel: 'dev', resource: 'res', read: true, write: true}, function(msg) {});Stops listenning to messages from the specified resource.
bbt.unsubscribe(args);
Parameters:
args: {
{string} channel: name of the channel. It can be prefixed with 'private-' to indicate a private resource, or it can be prefixed with 'presence-' to indicate presence events.
{string} resource: name of the resource.
{function, optional} callback: function to be called on return or to indicate an error.
}
Example:
bbt.unsubscribe({channel: 'dev', resource: 'res'});Sends a transient message to Beebotte. This method require prior 'write' permission on the specified resource (see BBT.subscribe method with write permission).
bbt.publish(args, data);
Parameters:
@param {Object} args: {
{string, required} channel name of the channel. It can be prefixed with 'private-' to indicate a private resource.
{string, required} resource name of the resource.
{Object, optional} data data message to publish to Bebotte.
{function, optional} callback: function to be called on return or to indicate an error.
}
@param {Object, optional} data data message to publish to Beebotte. If args.data is present, it will override this parameter.
Example:
bbt.publish({channel: 'dev', resource: 'res'}, 'Hello world');Sends a presistent message to Beebotte. This method require prior 'write' permission on the specified resource (see BBT.subscribe() method with write set to true). A resource with the specified parameters must exist for this method to succeed. In addition, the message will inherit the access level of the channel. As the access level is specified by the existing channel parameters, it is not necessary to add the 'private-' prefix.
bbt.write(args, data);
Parameters:
@param {Object} args: {
{string, required} channel name of the channel. It can be prefixed with 'private-' to indicate a private resource.
{string, required} resource name of the resource.
{Object, optional} data data message to publish to Bebotte.
{function, optional} callback: function to be called on return or to indicate an error.
}
@param {Object, optional} data data message to publish to Beebotte. If args.data is present, it will override this parameter.
Example:
bbt.write({channel: 'dev', resource: 'res'}, 'Hello world');Sends a REST read request to Beebotte. This is a convenient API call to access the history of public persistent resources. This method does not require prior authentication as it is limited to public resources. This requires specifying the owner of the channel to which the resource belongs.
bbt.read(args, callback);
Parameters:
{Object} args: {
{string, required} owner: username of the owner of the channel.
{string, required} channel: name of the channel.
{string, required} resource: name of the resource.
{string, optional} limit: number of records to be retrieved.
{function, optional} callback callback function to be called with the response data on return or to indicate an error.
}
{function, optional} callback callback function to be called with the response data on return or to indicate an error. args.callback element will override this parameter if it is present.
Example:
bbt.read({owner: 'username', channel: 'dev', resource: 'res', limit: 5}, function(err, msg) {});