Table of Contents
  1. JSON
  2. XML
  3. Input Parameters
  4. Response Parameters
  5. Javascript Library

/Xmpp/RegisterEventHandler

Registers (or unregisters) an event handler on the client, that gets called when the account receives an XMPP message of a given type. When such a message is received that matches a registered event handler, the message is pushed as a client event to the client, instead of being stored on the broker, as an offline message.

Note: For client events to be received on the client, you need to include the /Events.js javascript file on the page. This javascript file will register the current tab with the server, and enable it to receive asynchronous events from the server. If you are hosting the page on one server, and use the Agent API and Events API from another server, you need to include a meta header on the page, information the /Events.js javascript file where it will register itself to receive client events. To use this neuron, add the following to the HTML header of your page:

<meta name="NEURON" content="lab.tagroot.io"/>

You also need to inform the AgentAPI that you want to use another host, than the server used to host the page. You do this by making a call to AgentAPI.IO.SetHost(Host,Secure) as follows:

AgentAPI.IO.SetHost("lab.tagroot.io",true)

JSON

Request
{
	"localName":Optional(Str(PLocalName)),
	"namespace":Optional(Str(PNamespace)),
	"type":Optional(Str(PType)),
	"function":Optional(Str(PFunction)),
	"tabId":Required(Str(PTabId))
}
Response (if successful)
{
}

XML

Request
<RegisterEventHandler xmlns="https://waher.se/Schema/BrokerAgent.xsd"
                      localName=(Optional(Str(PLocalName)))
                      namespace=(Optional(Str(PNamespace)))
                      type=(Optional(Str(PType)))
                      function=(Optional(Str(PFunction)))
                      tabId=(Required(Str(PTabId))) />
Response (if successful)
<EventHandlerRegistered xmlns="https://waher.se/Schema/BrokerAgent.xsd"/>

Input Parameters

Parameter Description
PLocalName Optional local name of content in message. If not provided, event handler is used for all messages of the same type and namespace that lack specific event handlers.
PNamespace Optional Namespace of content in message. If not provided, event handler is used for all messages of the same type that lack more specific event handlers.
PType Optional type of message stanza. If not provided, event handler is used for all messages that lack more specific event handlers.
PFunction Function on client that gets called when a message of the corresponding local name, namespace and/or type is received. If left empty, the corresponding event handler is unregistered.
TabId The Tab ID to which events are sent when corresponding messages are received.

Response Parameters

No response parameters are returned.

Javascript Library

Use the following asynchronous method in the Javascript Library, to call this resource. 

var Response = await AgentAPI.Xmpp.RegisterEventHandler(LocalName,Namespace,Type,Function);

A function also exists for unregistering an event handler:

var Response = await AgentAPI.Xmpp.UnregisterEventHandler(LocalName,Namespace,Type);

Note: You need to include /Events.js as well as /Agent.js for event handlers to be called. The TabId argument is not provided, as it is taken from the context of the page from which the call is made.

Test





Request Payload:

Response Payload: