TwHello - IDE and Cloud Service for Telecom - Powered by Twilio
Register for FreeLogin
FeaturesPricingDocsHelp
Introduction
Message Interfaces
Twilio Classes
Twilio.Verb Classes
Twilio.Noun Classes
Utility Classes
3rd Party Integrations

Intro to the TwHello JavaScript Library

Last updated on May 26, 2014.

The JavaScript you program in the IDE is executed on the TwHello servers. If you are familiar with client-side JavaScript, you will be comfortable with this JavaScript. However, there are two notable differences related to the server-side engine executing the script: strongly typed variables and read-only objects.

Strongly Typed Variables
The constructors and methods of the library classes are strongly typed. Argument and return types are documented throughout these docs. Use of the wrong variable type will throw an exception.

Read-Only Objects
The associative arrays that the library methods return are read-only. Attempting to modify these objects will throw an exception. If, in the future, an associative array is not read-only, the docs will indicate the change.

Exceptions
As expected, exceptions can be handled with try/catch blocks. Uncaught exceptions will (ungracefully) end the call.

Production and Development Modes

Your applications can run in Production or Development mode. This is determined by the subdomains used for web hooks and REST API requests.

Development Mode

Voice Request URL:
https://api-dev.twhello.com/v1/Twilio/Requests/VoiceRequestHandler.xml
Voice Status Callback URL:
https://api-dev.twhello.com/v1/Twilio/Requests/StatusCallbackHandler.xml
Messaging Request URL:
https://api-dev.twhello.com/v1/Twilio/Requests/MessagingRequestHandler.xml

Production Mode

Voice Request URL:
https://api.twhello.com/v1/Twilio/Requests/VoiceRequestHandler.xml
Voice Status Callback URL:
https://api.twhello.com/v1/Twilio/Requests/StatusCallbackHandler.xml
Messaging Request URL:
https://api.twhello.com/v1/Twilio/Requests/MessagingRequestHandler.xml

Performance
Production servers run on beefier hardware and are optimized for performance. In addition to being load balanced and auto-scalable, another part of our server performance optimization is the use of caching. Data can be cached for up to one hour on a production server. This would obviously make development very slow and painful. Development servers do not cache data, thereby showing changes to applications immediately.

Exceptions
On production servers, uncaught exceptions immediately end the call. On development servers, an uncaught exception message will be announced on the call before it ends. Exceptions are also logged in your admin log history.

Error Logging
The Utilities class provides a method for logging messages of varying levels. In production mode, DEBUG and INFO level messages are not logged. Use logging for insight into the state of your applications during development.

Usage Costs
Our mission is to keep our servers responsive and stable. To further encourage our developers to not run production applications on the development servers, Development Mode is twice as expensive as Production Mode. This should not add significantly to development costs, but could add up for high-volume production.


Element Handlers

Every element must have a do__Response() function. The system calls this function when an element is to be executed. This function incorporates the name of the element as shown below. The IDE will alert you to any accidental mismatches. Since each element must have a unique name, each element's do__Response() function will have a unique name.

Example element handler for an element named "HelloWorld":

 
/**
 * Function called by the system to execute this element.
 * Element ID: 1234567890
 * @param req	the Message.Request object
 * @param resp	the Message.Response object
 */
function doHelloWorldResponse(req, resp) {
	// Add code here
	var say = new Twilio.Verb.Say("Hello World!");
	resp.send(say);
}
 

The two arguments req and resp in the do__Response() function are subclasses of Message.Request and Message.Response. These are available in the global scope and also passed as arguments for convenience.

Note: Currently, each element is executed in its own scope, so unique do__Response() functions are not critical. However, future optimization improvements may compile all elements under the same scope, making elements with the same do__Response() functions fatally conflict. The IDE does not enforce unique element names. Future proof your application and use unique names anyway. You'll be glad you did!


Global Scope

The first tab in every new workflow is the Global Configuration tab. Under this tab you can set your workflow's name, assign the Home Element and add Global JavaScript. JavaScript entered in the Global JavaScript Editor is "Workflow Level" and executed before every element's do__Response() function is called.

This allows you to initialize common variables, create utility functions, import external scripts, etc.

Example of Global JavaScript:

 
// Import underscore.js for use in every element.
Network.importJS("http://underscorejs.org/underscore-min.js");

// Set global var with current element id.
var elementId = Message.Request.getHistory().slice(-1)[0];

// Track all element visits in Analytics by id.
Google.Analytics.init("UA-123456789-1").track(elementId);

// Global function to format phone +17145551212 to (714) 555-1212
function formatPhone(num) {
	return "("+ num.substr(2,3) +") "+ num.substr(5,3) +"-"+ num.substr(8);
}
 

Note: This is different from Message.Request.getGlobalVars(), which is set at the "Account Level". For example, you would likely set the Google Analytics Tracking Id as an Account's GlobalVar and not hard-code it as shown. This would allow you to set distinct Tracking Ids across different Accounts linked to the same Workflow.

Tip: Resist putting expensive API calls in the Global JavaScript. For example, call Salesforce.getByPhone() once in the Home Element and store the results as a SessionVar.


Session Management

For stateless inbound messages, TwHello provides session management to track state through the workflows. Examples of stateless inbounds include SMS and Twitter. An example of an inbound with native session management is Twilio Voice.

Sessions are created automatically and expire in 60 minutes after the last hit. Sessions can be ended by calling Message.Request.endSession(). This will cause the next visit to be treated as a new session and hit the workflow's "home element".

An IDE and Cloud Service for Voice and Messaging Applications.

Design by workflow. Program in JavaScript. Deploy to AWS. Powered by Twilio.

TwHello - IDE and Cloud Service for Voice and Messaging Apps - Powered by Twilio   About UsContactLegal

© 2014 TwHello, Inc. All rights reserved.