KB112: The People Builder API

Use on a website

After you Publish your People Builder module, you use Get Embed Code to get a small snippet of html code that you place in your own website where you want your module to appear. In many cases the module is completely self-sufficient. For example a Slideshow module can be started and stopped using the navigation bar. Likewise, an Agent module can automatically greet the user on arrival to a page. You can also use JavaScript to control a module. This is especially useful with the Agent module. You can use the Messages tab to create messages, and you can trigger then using events on your page.

A typical embed tag for an Agent module looks like this:

<script src="https://www.mediasemantics.com/agent.min.js"></script>
<div id="myDiv" style="width:250px; height:200px;"></div>
<script>var myAgent; document.addEventListener("DOMContentLoaded", function() {myAgent = MSAgentModule.setupDiv("myDiv", "123456", "12345678")})</script>

You can invoke the module's API using the methods shown in the Agent preview pane. For example to trigger a message, you can use html such as:

<a href="javascript:test()">test</a>
<script>
function test() {
    myAgent.play("Message 1");
}
</script>

You can also stop a message with the stop() method.

An optional fourth parameter to setupDiv() is a parameters object that you can use to override several default behaviors. For example you can override the default module "fade in" behavior as follows:

MSAgentModule.setupDiv("myDiv", "123456", "12345678", {fade:false})})

You can register one or more event handlers to react to events in your module. Event handlers hould be attached to your containing div ('myDiv' in this case).

One important event is "moduleLoaded", which fires when enough resources have been loaded to begin showing your module. The event fires right before the contents of the div become visible and indicates that the module is ready to receive play() commands.

<script>
   document.getElementById("myDiv").addEventListener("moduleLoaded", function() {
      console.log("module loaded and about to become visible");
    });
</script>

Use in an iframe

The Get Embed Code screen also lets you get a URL for insertion in an iframe. This option is availabe for all modules, and is often used to insert a module into a content authoring tool. There is no API available when embedding a module using an iframe.

Use in React

The Agent module also has a React embed code using the npm component react-embodied-agent. The React embed code looks like this:

<ReactEmbodiedAgent ref={this.myAgentRef} style={{width:"250px", height:"200px"}} userid="12345678" moduleid="12345678" />

The parameters userid and moduleid are required, but will differ from the values shown above. You can also use the parameters described in this document. For example to make the module initially invisible, you would use:

<ReactEmbodiedAgent ref={this.myAgentRef} style={{width:"250px", height:"200px"}} userid="12345678" moduleid="12345678" 
    visible={false} />

Methods are available using the React "ref" syntax. For example to call play() you might use:

myAgentRef.current.play("Intro");

Finally, the events described in this document are available with the prefix "on" using the standard React syntax:

<ReactEmbodiedAgent ref={this.myAgentRef} style={{width:"250px", height:"200px"}} userid="12345678" moduleid="12345678" 
    onModuleLoaded={ () => console.log("module loaded") } />

API Common to all modules

Parameters

Methods

Events

API specific to Agent Module

Methods

myAgent.dynamicPlay({do:"look-up-right", say:"Let's take a look over here."});

Events

API specific to Chatbot Module

Methods

Events

API specific to Slideshow

Parameters

Methods

Events