Skip to content

Reference.md

Latest commit

 

History

History
558 lines (519 loc) · 21.3 KB

Reference.md

File metadata and controls

558 lines (519 loc) · 21.3 KB

7.0.x API Reference

XMPP.Client

new Client(options)

Creates a new XMPP client instance, with no plugins loaded.

  • options - An object with the client configuration as described in client options.
var XMPP = require('stanza.io');
var client = new XMPP.Client({
    jid: '[email protected]',
    password: 'hunter2'
});

createClient(options)

An alternative method for creating a client instance.

Instantiating a client via this function will load all built-in plugins.

  • options - An object with the client configuration as described in client options.
var XMPP = require('stanza.io');
var client = XMPP.createClient({
    jid: '[email protected]',
    password: 'hunter2'
});

Client Options

When creating a client instance, the following settings will configure its behaviour:

  • jid - (required) the requested bare JID for the client.
  • password - shortcut for setting credentials.password
  • server - specify the hostname of the server to initially connect to, if different from jid.domain.
  • resource - suggest a specific resource for this session.
  • credentials
    • username - username you're presenting for auth. Typically the local portion of the JID, but could be different
    • password - just like it sounds
    • host - the domain of the service
    • serverKey - cached credential created by SCRAM-SHA-1, that can be used without needing to know the password
    • clientKey - cached credential created by SCRAM-SHA-1, that can be used without needing to know the password
    • saltedPassword - cached credential created by SCRAM-SHA-1, that can be used without needing to know the password
    • serviceType - for most cases should be 'XMPP', the default
    • serviceName - for most cases should be the same as the 'host', the default
    • realm - for most cases should be the same as the 'host', the default
    • authzid -
  • transports - a strings array of transport methods that may be used.
  • wsURL - URL for the XMPP over WebSocket connection endpoint.
  • boshURL - URL for the BOSH connection endpoint.
  • sasl - a list of the SASL mechanisms that are acceptable for use by the client.
  • useStreamManagement - set to true to enable resuming the session after a disconnect.
  • rosterVer - version ID of cached roster data given by the server, typically saved from a previous session.
  • capsNode - a URL for identifying the client app.
  • softwareVersion
    • name - the name of the client software using stanza.io
    • version - the version of the client software using stanza.io
    • os - the operating system that the client is running on
  • timeout - number of seconds that IQ requests will wait for a response before generating a timeout error.
  • lang - preferred language used by the client, such as 'en' or 'de'.

Client Properties

Client Methods

client.use(plugin)

client.on(event, [group], handler)

client.connect([opts])

client.disconnect()

client.sendIq(opts)

client.sendMessage(opts)

client.sendPresence(opts)

client.sendStreamError(opts)

Keepalive

client.enableKeepAlive(opts)
client.disableKeepAlive()
client.ping(jid, [cb])

Roster Management

client.acceptSubscription(jid)
client.block(jid, [cb])
client.denySubscription(jid)
client.getBlocked([cb])
client.removeRosterItem(jid, [cb])
client.subscribe(jid)
client.getRoster([cb])
client.unblock(jid, [cb])
client.unsubscribe(jid)
client.updateRosterItem(item, [cb])

Service Discovery

client.getCurrentCaps()
client.getDiscoInfo(jid, node, [cb])
client.getDiscoItems(jid, node, [cb])

Fetch the jids of all available rooms Example:

client.getDiscoItems('conference.xxx.yyy.zz','', (err, data) => {
            //Get list of available rooms
        }
client.updateCaps()

Jingle

client.call(jid)
client.discoverICEServers([cb])
client.getServiceCredentials(jid, host, [cb])
client.getServices(jid, type, [cb])

Pubsub

client.createNode(jid, node, [cb])
client.deleteNode(jid, node, [cb])
client.getItem(jid, node, id, [cb])
client.getItems(jid, node, opts, [cb])
client.publish(jid, node, item, [cb])
client.purgeNode(jid, node, [cb])
client.retract(jid, node, id, notify, [cb])
client.subscribeToNode(jid, opts, [cb])
client.unsubscribeFromNode(jid, opts, [cb])

Multi-User Chat

client.ban(room, jid, reason, [cb])
client.changeNick(room, nick)
client.configureRoom(room, form, [cb])
client.destroyRoom(room, opts, [cb])
client.directInvite(room, sender, [reason])
client.discoverReservedNick(room, [cb])
client.getRoomConfig(jid, [cb])
client.getRoomMembers(room, opts, [cb])
client.getUniqueRoomName(jid, [cb])
client.invite(room, opts)
client.joinRoom(room, nick, opts)

Request to join a Multi-User Chat room.

  • room - The bare JID of the room to join
  • nick - The requested nickname to use in the room. Note: You are not guaranteed to be assigned this nick.
  • options - Additional presence information to attach to the join request, in particular:
    • joinMuc - A dictionary of options for how to join the room:
      • password - Optional password for entering the room
      • history - May be true to receive the room's default history replay, or may specify maxstanzas, seconds, or since to specify a history replay range in terms of number of messages, a given time range, or since a particular time.
client.joinRoom('[email protected]', 'User', {
    status: 'This will be my status in the MUC',
    joinMuc: {
        password: 'hunter2',
        history: {
            maxstanzas: 20
        }
    }
});
client.kick(room, nick, reason, [cb])
client.leaveRoom(room, nick, opts)
client.requestRoomVoice(room)
client.setRoomAffiliation(room, jid, affiliation, reason, [cb])
client.setRoomRole(room, nick, role, reason, [cb])
client.setSubject(room, subject)
client.addBookmark(bookmark, [cb])
client.getBookmarks([cb])
client.removeBookmark(jid, [cb])
client.setBookmarks(opts, [cb])

Message Syncing

client.enableCarbons([cb])

Enable carbon messages. This is useful if you want to receive a copy of a message that you sent from one device, and receive on all other logged devices.

client.disableCarbons([cb])
client.getHistorySearchForm(jid, [cb])
client.getHistoryPreferences([cb])
client.setHistoryPreferences(opts, [cb])
client.searchHistory(opts, [cb])

Fetch chat history for the specified jid. By default, you will receive all the messages. Optionally you can pass an object to get max number of messages. Example:

client.searchHistory({
            with: jid,
            rsm: {max: 50, before: true},  -- 
            complete: false
        }

Avatars

client.getAvatar(jid, id, [cb])
client.publishAvatar(id, data, [cb])
client.useAvatars(info, [cb])

Other

client.deleteAccount([jid, cb])
client.getAccountInfo([jid, cb])
client.getAttention(jid, [opts])
client.getCommands(jid, [cb])
client.getPrivateData(opts, [cb])
client.getSoftwareVersion(jid, [cb])
client.getTime(jid, [cb])
client.getVCard(jid, [cb])
client.goInvisible([cb])
client.goVisible([cb])
client.markActive()
client.markInactive()
client.publishGeoLoc(data, [cb])
client.publishNick(nick, [cb])
client.publishReachability(data, [cb])
client.publishTune(data, [cb])
client.publishVCard(vcard, [cb])
client.sendLog(jid, opts)
client.setPrivateData(opts, [cb])
client.updateAccount(jid, data, [cb])

XMPP.JID

new JID(jid)

Creates a new JID (Jabber IDentifier) object, which represents an address in the XMPP network.

  • jid - a string of the form [username@]domain[/resource] (or an existing JID object)
var someServer = new JID('somedomain.example.com');
var friendAddress = new JID('[email protected]');
var addressOfParticularConnection = new JID('[email protected]/laptopclient');

JID Properties

All JID objects expose the following properties:

  • local - If the JID is of the form '[email protected]', then the local value would be the 'user' portion
  • domain - If the JID is of the form '[email protected]' (or 'example.com'), then the domain value would be 'example.com'
  • resource - If the JID is of the form '[email protected]/res' (or even 'example.com/res'), then the resource value would be 'res'
  • bare - The bare JID contains only the local and domain sections, eg '[email protected]'
  • full - The full JID contains the local, domain, and resource sections, eg '[email protected]/res'

Message Stanzas

Presence Stanzas

IQ Stanzas

Events

attention

auth:failed

auth:success

avatar

available

block

bosh:terminate

carbon:received

carbon:sent

chat

Example:

{
    type: 'chat',
    to: JID,
    from: JID,
    body: 'this is a chat'
}

chat:state

Example:

{
    type: 'chat',
    to: JID,
    from: JID,
    chatState: 'composing'
}

connected

credentials:update

dataform

disco:caps

Example:

{
    to: JID,
    from: JID,
    caps: {
        hash: 'sha-1',
        node: 'https://stanza.io',
        ver: 'rs/tl9NCfXBpKoOYUy+JdBbPGDg='
    }
}

disconnected

geoloc

groupchat

id:ID

iq:get:NAME

iq:set:NAME

jingle:accepted

jingle:hold

jingle:incoming

jingle:localstream:added

jingle:localstream:removed

jingle:mute

jingle:outgoing

jingle:remotestream:added

jingle:remotestream:removed

jingle:resumed

jingle:ringing

jingle:terminated

jingle:unmute

message

message:error

message:sent

muc:available

muc:declined

muc:error

muc:invite

muc:join

muc:leave

muc:subject

muc:unavailable

muc:destroyed

nick

presence

presence:error

pubsub:event

raw:incoming

raw:outgoing

reachability

receipt[:ID]

replace[:ID]

roster:update

roster:ver

sasl:abort

sasl:challenge

sasl:failure

sasl:success

session:bound

session:end

session:error

session:started

stanza

stanza:acked

stream:data

stream:end

stream:error

stream:management:enabled

stream:management:failed

stream:management:resumed

stream:management:ack

subscribe

subscribed

tune

unavailable

unblock

unsubscribe

Example:

{
    type: 'subscribe',
    to: JID,
    from: JID
}

unsubscribed

Example:

{
    type: 'unsubscribed',
    to: JID,
    from: JID
}