Select Page

Javascript API Reference

Everything you need to build on top of Yonyx. Sign Up for a 30-day Free-Trial

Introduction

Yonxy Javascript API enables communication between “Embedded Yonyx” and your “Container website”.
If you have any problems or requests please contact us.

What is Embedded Yonyx Website?

Embedded Yonyx is any Yonyx page like Yonyx Guide or Yonxy Landing Page that is embedded into your Container Website.

What is Container website?

Container website is your website that embeds Yonyx.

How to enable Javascript API?

Yonyx Javascript API is enabled per Line of Business.
Please send us a request at feedback@yonyx.com with the following details:
1. Line of Business name you want it enabled for.
2. You Container website URL where you plan to embed Yonyx.

Live Demo

Please click here to access the live demo. This page demonstrates a Container Website hosted at “rackcdn.com” communicating with Yonyx Guide hosted at testisp.yonyx.com.

This page can be used to understand items listed below:
1. Communication between the Container Website and Embedded Yonyx Guide.
2. As-you-type-search triggered by “Subject” field in the Container Website results in Embedded Yonyx landing page listing keyword search results.
3. Automatically pasting Yonyx Transcript Summary into the “Description” field in the Container Website.
4. Force the end user to fill out a form during the traversal.

Supported Messages

Messages supported by this API.

  guidance-step-loaded
  select-user-response
  user-response-selected
  disable-user-responses
  enable-user-responses
  traversal-completed
  traversal-reference-id-submitted
  dimension
  invoke-feedback
  invoke-compliment
  complete-traversal
  replace-placeholders
  return-command-result
  get-dimension
  go-back

Guidance Step Loaded

This message is published to the Container Website when a guidance step is loaded by an embedded Yonyx Guide.

Structure of the message:
{
   "messageName":"guidance-step-loaded",
   "id":"222f46b0-9d59-11e2-bfd4-40406ab12aa1",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "title":"My TV Doesn't work",
   "body":"

Please check if your TV is plugged into the wall socket.

\n

", "question":"Is your TV plugged into the wall socket?", "notes":"", "commandInternalName":"command-name", "responses":[ { "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1", "body":" No it is not.", "nextGuidanceFamily":"3133cb50-9d62-11e2-bfd4-40406ab12aa2", "nextGuidanceFamilyUrl":"https://your-subdomain.yonyx.com/y/conversation/?id=3133cb50-9d62-11e2-bfd4-40406ab12aa1&did=f9e71980-3de7-11e5-9862-0800271a7174" }, { "id":"2bd80770-9d62-11e2-acbc-404089ef33c3", "body":" Yes it is", "nextGuidanceFamily":"2bd80770-9d62-11e2-acbc-404089ef33c4", "nextGuidanceFamilyUrl":"https://your-subdomain.yonyx.com/y/conversation/?id=2bd80770-9d62-11e2-acbc-404089ef33c3&did=f9e71980-3de7-11e5-9862-0800271a7174" } ] }

Select User Response

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it selects the specific User Response and traverses further.

{
Structure of the message:
{
   "messageName":"select-user-response",
   "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1"
}

User Response Selected

This message is published to the Container Website when an end user clicks on a specific “User Response” of a Guidance Step.

Structure of the message:
{
   "messageName":"user-response-selected",
   "id":"3133cb50-9d62-11e2-bfd4-40406ab12aa1",
   "body":" No it is not."
}

Disable User Responses

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it prevents traversal by making the User Responses non clickable.

Structure of the message:
{
   "messageName":"disable-user-responses"
}

Enable User Responses

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it allows traversal by making the User Responses clickable.

Structure of the message:
{
   "messageName":"enable-user-responses"
}

Traversal Completed

This message is published to the Container Website when an end user clicks on the “Done” link of a Guidance Step to wrap up the traversal.

Structure of the message:
{
   "messageName":"traversal-completed",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "transcript":"http://testisp.yonyx.com:8888/incident/?did=72a3d100-b5a4-11e4-9ecf-0eeb802c7794\n\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:31] My TV Doesn't work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:51] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: Yes, it did.\n--------------------------------------------\nT: [00:00:30] Use Remote Control to Turn TV On\nQ: Did the TV turn on?\n--------------------------------------------\n\n "
}

Traversal Reference Id Submitted

This message is published to the Container Website when an end user clicks on the “Submit” button in the “Done” window after populating Reference Id field.

Structure of the message:
{
   "messageName":"traversal-reference-id-submitted",
   "transcriptId":"72a3d100-b5a4-11e4-9ecf-0eeb802c7794",
   "referenceId":"xxxxxxxx",
   "transcript":"http://testisp.yonyx.com:8888/incident/?did=72a3d100-b5a4-11e4-9ecf-0eeb802c7794\n\n============================================\nTRANSCRIPT SUMMARY: \nT = Title, Q = Question, U = User Response\n============================================\nT: [00:00:31] My TV Doesn't work\nQ: Is your TV plugged into the wall socket?\n--------------------------------------------\nU: No it is not.\n--------------------------------------------\nT: [00:00:51] Plug it in\nQ: Do you now see the red light come on?\n--------------------------------------------\nU: Yes, it did.\n--------------------------------------------\nT: [00:00:30] Use Remote Control to Turn TV On\nQ: Did the TV turn on?\n--------------------------------------------\n\n "
}

Dimension

This message is published to the Container Website whenever the dimension of Embedded Yonyx Guide changes.

Structure of the message:
{
  "messageName": "dimension",
  "width": 568,
  "height": 309
}

Get Dimension

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it publishes ‘dimension’ message back to the Container Website.

Structure of the message:
{
   "messageName":"get-dimension"
}

Invoke Feedback

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Feedback window.

Structure of the message:
{
   "messageName":"invoke-feedback"
}

Invoke Compliment

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Compliment window.

Structure of the message:
{
   "messageName":"invoke-compliment"
}

Complete Traversal

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it opens Done window.

Structure of the message:
{
   "messageName":"complete-traversal"
}

Replace Placeholders

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it replaces all placeholders in the body with the replacement values carried by this message.

Structure of the message:
{
  "messageName": "replace-placeholders",
  "placeholdersReplacementMap": {
    "placeholder-1": "replacement-value-1",
    "placeholder-2": "replacement-value-2",
    "placeholder-3": "replacement-value-3"
  }
}

Go Back

This message is published by the Container Website to Embedded Yonyx Guide. When Embedded Yonyx Guidance Step receives this message, it traverses back to the previous Guidance Step.

Structure of the message:
{
   "messageName":"go-back",
}

Step-by-step Walkthrough

Let’s walk you through the process of setting this up step by step.

Step 1: Create an html file.

Create an html file for your Container website with this markup.
This page contains 3 columns.
The first column consists of a few fields that make up the main region of your Container website.
The second column embeds Yonyx Landing page.
The third column display the communication activity logs.
Also notice that this page includes a javascript file called “up-api-harness-all.js” which we will go over later.

    
    <html>
    <head>
      <meta http-equiv="X-UA-Compatible" content="IE=edge">
      <title></title>
      <script src="http://code.jquery.com/jquery-1.10.1.min.js"></script>
      <script src="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/js/bootstrap.min.js"></script>
      <link rel="stylesheet" href="http://maxcdn.bootstrapcdn.com/bootstrap/3.3.2/css/bootstrap.min.css">
      <style type="text/css">
      </style>
      <style type="text/css">
        body {
          background-color: black;
        }
        .cell {
          color: white;
          background-color:black;
        }
      </style>
      <script type="text/javascript" src="ui-api-harness-all.js?t=1.1.2.1"></script>
      <script type="text/javascript">
        $(function() {
          // $("#logsContainer").hide();
          // $("#controlsContainer").hide();
          $( "#showLogs" ).prop( "checked", true );
          $( "#showControls" ).prop( "checked", true );

          $("#transcriptId").val("");
          $("#description").val("");
          $("#userResponsesContainer").html("");
        });

      </script> 
    </head>
    <body>

    <div class="modal fade" id="slnoModal" tabindex="-1" role="dialog" aria-labelledby="slnoModalLabel" aria-hidden="true" data-backdrop="static" >
      <div class="modal-dialog">
        <div class="modal-content">
          <div class="modal-header">
            <button type="button" class="close" data-dismiss="modal" aria-label="Close"><span aria-hidden="true">&times;</span></button>
            <h4 class="modal-title" id="slnoModalLabel">Enter Serial Number</h4>
          </div>
          <div class="modal-body">
            <form>
              <div class="form-group">
                <label for="recipient-name" class="control-label">Serial Number:</label>
                <input type="text" class="form-control" id="recipient-name" placeholder="999-99-9999" autofocus >
              </div>
            </form>
          </div>
          <div class="modal-footer">
            <!-- <button type="button" class="btn btn-default" data-dismiss="modal">Close</button> -->
            <button id="slnoDone" type="button" class="btn btn-primary">Done</button>
          </div>
        </div>
      </div>
    </div>

    <div class="row" style="margin-top:5px;">
      <!-- <div class="col-md-1 cell"></div> -->
      <div class="col-md-4 cell">
      <div style="background-color: #ff7f00; font-size: 18px; font-weight: bold; text-align:center;">YOUR APPLICATION</div>
      <br>
      <form>
        <div class="form-group">
          <label for="requester">Requester</label>
          <input class="form-control" id="requester" placeholder="Requester">
        </div>
        <div class="form-group">
          <label for="phone">Phone</label>
          <input class="form-control" id="phone" placeholder="Phone">
        </div>

        <div class="form-group">
          <label for="type">Model</label>
            <select class="form-control" id="type">
            <option>Skytech 1001</option>
            <option>Skytech 1002</option>
            <option>Skytech 1003</option>
            <option>Skytech 1004</option>
          </select>
        </div>
        <div class="form-group">
          <label for="priority">Priority</label>
            <select class="form-control" id="priority">
            <option>Low</option>
            <option>Normal</option>
            <option>High</option>
            <option>Urgent</option>
          </select>
        </div>
        <div class="form-group">
          <label for="subject">Subject</label>
          <input class="form-control" id="subject" placeholder="Subject">
        </div>

        <div class="form-group">
          <label for="transcriptId">Transcript Id</label>
          <input class="form-control" id="transcriptId" placeholder="Transcript Id">
        </div>

        <div class="form-group">
          <label for="description">Description</label>
          <textarea id="description" class="form-control" rows="3" style="height:200px;" placeholder="Description"></textarea>
        </div>



      </form>
      </div>


      <div class="col-md-4 cell">
      <div style="background-color: #00AFFF; font-size: 18px; font-weight: bold; text-align:center;">YONYX EMBED</div>    
        <br>
        <iframe id="yonyxAppFrame" frameborder="0" src="https://testisp.yonyx.com/y/portal/?id=847eb630-047c-11e4-9638-bc764e10f0e8&h=0&st=1&at=browse" width="100%" height="850px" style="border:none;"></iframe>

      </div>


      <div class="col-md-4 cell">
      <div style="background-color: #05a423; font-size: 18px; font-weight: bold; text-align:center;">COMMUNICATION LOGS</div>
        <br>
        <input type="checkbox" id="showControls" >Show Controls
        <br><br>
      <div id="controlsContainer">
        <div id="userResponsesHeaderContainer" >Select user responses programmatically:</div>
        <div id="userResponsesContainer"></div> 


        <button id="disable" class="btn btn-primary" >Disable</button>
        <button id="enable" class="btn btn-primary" >Enable </button>
        <button type="button" class="btn btn-primary" data-toggle="modal" data-target="#slnoModal" >Request Serial No</button>
      </div>  
      <br><br>
      <input type="checkbox" id="showLogs" >Show Logs
      <br><br>
      <div id="logsContainer" >This region listens to broadcast messages from Yonyx:</div>

      </div>

    </div>


    </body>
    </html>

Step 2: Create a javascript file.

Create a javascript file and include it in the html file you created in the previous step: Make sure to replace “testisp” with your own sub domain you chose while registering with Yonyx.

    
    $(function() {

      var constOrigin = "https://testisp.yonyx.com";

      function sender(data) {
            var origin = constOrigin;

        var message = "Message sent to " + origin + ":  " + JSON.stringify(data);
        $("#logsContainer").prepend("<br/><textarea style='font-size:12px; width:98%; height: 250px; margin-bottom:5px; padding:5px;border:1px solid; color:black;'> " + message + "</textarea>");

            var iframeWin = document.getElementById("yonyxAppFrame").contentWindow;
            iframeWin.postMessage(JSON.stringify(data), origin);
        }

        function enableUserResponses() {
          var data = new Object();
            data.messageName = "enable-user-responses";

            sender(data);
            return false;
        }
        function disableUserResponses() {
          var data = new Object();
            data.messageName = "disable-user-responses";

            sender(data);
            return false;
        }
        function selectUserResponse(userResponseId) {
          var data = new Object();
            data.messageName = "select-user-response";
            data.userResponseId = userResponseId;

            sender(data);
            return false;
        }
      $("#enable").click(function() {
        enableUserResponses();
        });

      $("#disable").click(function() {
        disableUserResponses();
        });
      

      function listener (event) {

        var message;
        var data = $.parseJSON(event.data);
        if (event.origin !== constOrigin) {
          message = "Not Authorized.";
        }
        else {
          message = "Message received from " + event.origin + ":  " + JSON.stringify(data);
        } 

        $("#logsContainer").prepend("<br/><textarea style='font-size:12px; width:98%; height: 250px; margin-bottom:5px; padding:5px;border:1px solid; color:black;'> " + message + "</textarea>");

        /**
             * Process incoming messages
             **/
        if(data.messageName === "guidance-step-loaded") {
          var notes = data.notes;

          if(notes && notes.length > 0) {

            if(notes === "form slno") {
              $("#slnoModal").modal('show');
              disableUserResponses();
            }
          }
          else {
            // do nothing for now
          }

          if(data.transcriptId) {
            $("#transcriptId").val(data.transcriptId);
          }

          if(data.responses) {
            $("#userResponsesContainer").html("");
            $.each( data.responses, function( index, value ){
              $("#userResponsesContainer").append("<button id='" + value.id + "' name='userResponse' class='btn btn-primary' >Select -> " + value.body + "</button> <br>");
            });
            $("#userResponsesContainer").append("<br><br><br><br>");

            $("#userResponsesContainer button").each(function( index ) {
              $( this ).click(function() {
                selectUserResponse($( this ).attr("id"));
                });
            });

          }

        }
        else if(data.messageName === "traversal-completed") {

          if(data.transcriptId && data.transcript) {

            $("#transcriptId").val(data.transcriptId);
            $("#description").val(  "\r\n \r\n" + 
                              "**** DO NOT DELETE BELOW THIS LINE ****" + "\r\n" +
                              data.transcript + "\r\n \r\n" );
          }
          else {
            // do nothing for now
          }
        }
      }

      if (window.addEventListener) {
        // For standards-compliant web browsers
        window.addEventListener("message", listener, false);
      }
      else {
        window.attachEvent("onmessage", listener);
      }

      $("#slnoDone").click(function() {
        $("#slnoModal").modal('hide');
        enableUserResponses();
      });


      $("#showLogs").click(function() {

        if($(this).is(":checked")) {
          $("#logsContainer").show();
        }
        else {
          $("#logsContainer").hide();
        }
      });

      $("#showControls").click(function() {
        if($(this).is(":checked")) {
          $("#controlsContainer").show();
        }
        else {
          $("#controlsContainer").hide();
        }
      });
      var yonyxTimer = null;

      $( "#subject" ).keyup(function() { //.change(function() {
        var searchUrl = constOrigin + "/y/portal/?id=847eb630-047c-11e4-9638-bc764e10f0e8&h=0&st=1&at=browse";
        if($("#subject").val() != "") {
          var searchUrl = constOrigin + "/y/portal/?id=847eb630-047c-11e4-9638-bc764e10f0e8" + "&h=0&st=1&at=search&st=1&q=" + $(this).val() ;
        }

        if(yonyxTimer != null) {
              clearTimeout(yonyxTimer);
              yonyxTimer = null;
            }

            yonyxTimer = setTimeout(function() { 

              $("#yonyxAppFrame").attr("src", searchUrl);
            }, 500);    


      });

    });

Let us help you evaluate.

Start your 30-day free trial. No credit card required. No strings attached. Sign up for a demoStart a trial