Contents Emulator Overview ....................................................................................................................................... 2

Server Details ................................................................................................................................................ 4

CLI Options ................................................................................................................................................ 4

Sending StartSay options to all clients ...................................................................................................... 5

Conversation Driver Client Details ................................................................................................................ 5

CLI options................................................................................................................................................. 5

Sending DTMF events ............................................................................................................................... 6

Terminating call session ............................................................................................................................ 6

Force a Tropo server error event .............................................................................................................. 6

Take the “timeout” event ......................................................................................................................... 6

Take the “invalid input” event .................................................................................................................. 6

Server and Client Event Messages ................................................................................................................ 6

Client Event Types ..................................................................................................................................... 6

Server Event Types .................................................................................................................................... 9

Class Definitions .......................................................................................................................................... 12

ClientEvent .............................................................................................................................................. 12

ClientEventNotification ........................................................................................................................... 12

NewCall ................................................................................................................................................... 12

Record ..................................................................................................................................................... 13

Choices .................................................................................................................................................... 13

Transcription ........................................................................................................................................... 13

Transfer ................................................................................................................................................... 13

Transfer Results ...................................................................................................................................... 14

ResponseEvent ........................................................................................................................................ 14

ResponseEventNotification ..................................................................................................................... 15

ServerEvent ............................................................................................................................................. 15

ServerEventNotification .......................................................................................................................... 15

SessionList ............................................................................................................................................... 15

Ask ........................................................................................................................................................... 15

Say ........................................................................................................................................................... 16

Choices .................................................................................................................................................... 16

ServerTrafficInfo ..................................................................................................................................... 16

ServerInfo ................................................................................................................................................ 16

A Word about Recording and Transcription ............................................................................................... 16

Server Setup ................................................................................................................................................ 17

Stand Alone ............................................................................................................................................. 17

Using the Routing Service ....................................................................................................................... 18

Step 1. Run the Routing Service .......................................................................................................... 18

Step 2. Configure Servers to Register with the Service ...................................................................... 18

Step 3. Configure Clients to Request Server Address from Router .................................................... 19

Version History ............................................................................................................................................ 19

Server CLI ................................................................................................................................................ 19

Emulator Overview In short the Emulator provides the web service functionality of Tropo while providing status updates to various clients connected to it via web sockets via a web socket library. This simple sequence diagram shows what a basic interaction could look like starting with a client attaching to the emulator’s web socket interface and going from there:

The clients can be written directly using web sockets interfaces. Supported web socket libraries are available for .NET, Pyton, Java, JavaScript and other clients. The emulator is written using the widely used Fleck web socket library which works with several different web socket standards.

The basic model here is the client provides public methods that the TES can call and the TES provides methods the clients can call. The TES is designed explicitly to be loosely coupled, not a synchronous call/result method (this is not RPC). You _can_ emulate a return of various types with web sockets but these are really hacks (spawning a function at the client that simply executes when the result comes in on another method call in the back ground) and will hurt the ability to scale. So when designing clients keep that design methodology in mind. For instance in the diagram above the StartCall made by the client does not return the JSON or a TropoCallId or the like – the DesWebResponse call is made by TES to the client asynchronously sometime later (usually very quickly but not necessarily). Followed by the StartSay and so on. The order of calls from TES to the client is guaranteed, but not the timing.

A couple of important notes about the Tropo Emulator Service (TES) design

• A client can initiate a single call session per web socket session. If you call StartCall a 2nd time on the same session the first call is terminated first. To handle multiple calls you must create multiple web socket sessions. On the server side events coming in and going out on a socket

session are assumed to be related to a single ongoing call be managed against the conversation service being tested such as CES/AA or Voice Mail.

• All media handling duties fall to the client to handle if that’s desired. TES does not stream WAVs or produce TTS streams or the like. As noted in the diagram above it sends a SayStart event to the client which contains the stream reference or string to play via TTS and the client can manage that to the user if they wish or they can simply send a SayComplete event right away to force the server to advance to the next script function.

• Digit handling – notice in the example above that the client raised a DTMF event to the server and the server calls the client’s DigitAccepted – if a DTMF event is raised when a conversation is not active or an “Ask” state is not active no DigitAccepted call is made – the server simply ignores the event in that case. This allows a proper “interrupt” experience you’d have with a real conversation – touching tones outside of an ask state does not interrupt the playing media or advance the conversation.

• The JSON from CES/VM transmitted to the client via the CesWebResponse call and the JSON for the StartAsk call are purely optional items – they are provided to clients interested in them for driving intelligent conversation clients that “know” what all the options are. Clients can simply not provide event handles for these if they’re not interested.

Server Details Currently the server is a simple CLI application that can run on any version of Windows with .NET 4.5 installed on it. While a simple CLI application it can actually handle numerous client sessions talking to different CES/VM services.

By default the service runs against “127.0.0.1:8181” – which means it’s listening for WebSocket connection requests coming in on port 8181 for local clients only (Windows blocks access to localhost from off box). You can change this and put the explicit IP address and different port if you like – the CLI options below show this.

There’s nothing you need to do on the server side once it’s running, however if you press any key on the server console while running it will broadcast “SayStart” calls to all connected clients with the letter entered. This can be helpful in testing your clients processing of the SayStart and making sure it properly calls the SayComplete on the server when done.

Logs are provided in the “logs” folder created under the folder where the executable is run from. As noted in the CLI section you can pass “debug” as the last parameter on the CLI list to turn on debug output to both the CLI interface and the logs.

There is also a performance CSV file written to the same logs folder – every 60 seconds the server will output how many clients are connected, the longest and shortest return time on CES/VM web calls and the average CES/VM call length for that 60 second period. The values are wiped and gather again for the next 60 seconds.

CLI Options tropoEmulatorFleck.exe [Address to listen on] [Web Socket Port] [HTTP Port] [Routing Server to register with] [DEBUG]

If the IP address to listen on is not provided it will default to 127.0.0.1. Note that this address works fi you are using a server and client to test on a local box but Windows will not allow external clients to attach to your service from off the local box unless a real IP address is provided.

If the web socket port is not provided it will default to 8181.

If the HTTP port is not provided it will default to 7171. This is used for the “Signal Port” functionality that allows an action to be triggered in an ongoing conversation via a separate HTTP call. This is most commonly used to have a conversation in a loop, such as a hold pattern, that is then broken out of via an external HTTP call by another process.

NOTE: You need to run the server “as administrator” on most Windows installations or the HTTP listener used for the signal port functionality will not work. The server will continue to run for web socket traffic but the signal port calls will be ignored. You will also see an error in the command window during startup since the HTTP listener will fail to start.

The routing server address and port is used to register the server instance with a router so clients can use larger “farms” of servers. If none is provided the server runs only in “local mode” on the local server.

Sending StartSay options to all clients Press any key on the keyboard an all attached clients will get a “StartSay” event with the name of the key pressed. This can be handy for testing if your client is properly handling the ClientEvent structure and sending SayComplete events as it should be.

Conversation Driver Client Details One of the clients offered for download is a simple conversation driver command line application – this can be used to actually call a conversation entry point and explore it just as if you were calling in on a phone – the prompts are played via TTS and you can enter commands (i.e. like DTMF entry) using the keyboard. When the client is running you can press the “s” key and a NewCall will be started with the details provided on the CLI. During conversation execution it will TTS out strings for the Say states provided and you can press and digit key to send DTMF events to the server to navigate.

Logs are provided in the “logs” folder created under the folder where the executable is run from. As noted in the CLI section you can pass “debug” and/or “trace” as the last 1 or 2 parameters on the CLI list to turn on debug and trace output to both the CLI interface and the logs. This shows some of the WebSocket call details which can be helpful at times.

Clients for Python and JavaScript will be provided as samples as we move ahead and there’s also a load test client capable of spinning up multiple automatically controlled conversation sessions. Others will be provided over time.

CLI options fleckCliClient.exe [Address:port of emulator server] [Dialed number] [CES Server] [CES Port] [CES Login] [CES PW] [CustomerId] ] [DEBUG] [TRACE]

Examples:

fleckCliclient 192.168.0.28:8181 4086204695

defaults to ces.int-tx3.huron-int.com for server, 443 for port, Hur0n_tr0p011:This.Is.3.Really.Long.Password.4.test.basicauth.2015 for login/pw, trace and debug are off.

fleckCliclient 127.0.0.1:8080 4086204695 ces.hptx1.huron-dev.com

defaults to Hur0n_tr0p011:This.Is.3.Really.Long.Password.4.test.basicauth.2015 for login/pw, trace and debug are off.

fleckCliclient 127.0.0.1:8080 4086204695 ces.hptx1.huron-dev.com 443 MyCesLogin MyCesPw MyCustomerId debug trace

To turn debug and/or trace on you need to pass all parameters and include one or both at the end.

Sending DTMF events Press any digit character on the keyboard. The digit is ignored by the server if the conversation is not in an ASK state.

Terminating call session Press “h” on the keyboard for “hang-up”

Force a Tropo server error event Press the “e” key for “error”

Take the “timeout” event Rather than waiting for the multiple repeats on a menu to complete and then being directed to the timeout event defined, you can press the “t” key for “timeout” and this action will be taken immediately. This key is only acted on in an ASK state.

Take the “invalid input” event Rather than entering invalid input repeatedly until the number of retries is exceeded, you can press the “i” for “invalid” and that action will be taken immediately. This key is only acted on in an ASK state.

Server and Client Event Messages Client Event Types Events sent from the connected clients to the Tropo emulation server. All events raised by the client to the server will use this construction – it leverages the ClientEventType enum and the simple ClientEvent class defined below – a number and a string pair. There will be other events added I’m sure… DTMF and SayComplete are the only two plumbed in on the server side for now. SayComplete doesn’t need any string with it and DTMF the string is the digit. One digit at a time only, no fair shoving whole DTMF strings down (perhaps another event for that would be useful).

Event Parameter Description 0 - Disconnect Empty string Hangs up the call.

1 - DTMF Single digit string Client raises a DTMF event (one at a time) using this method to the server. If the server is not processing an Ask state that accepts digits, the event is ignored. If it is processing an Ask state a Digit Accepted event on the server is sent in response. This allows a proper “cut through” interrupt sequence between the server and the client

2 – Speech (coming soon) Will be added later for emulating ASR driven events

3 – Record Complete Record Termination String

When the client is finished processing a record (i.e. recording a microphone and sending recording to the target web page) it needs to raise this event to tell the server to proceed. Client can also respond with the Generate Dummy Recording Data event – see below. The termination string can be empty for hangup or a digit (0-9, *, #) indicating what digit was entered to terminate the recording.

4 – Take Timeout Action Empty string Forces the emulator to take the timeout action for the Ask state if one is defined. This event is only responded to in an Ask state, it’s ignored otherwise.

5 – Take Invalid Input Action Empty string Force the emulator to take the invalid input action for the Ask state if one is defined. This event is only responded to in an Ask state, it’s ignored otherwise.

6 – Raise Tropo Server Error Empty string Make the emulator raise a Tropo server error to the conversation service.

7 – Say Complete Empty string When the client is finished processing a say (i.e. playing the TTS of the string out to a user) it needs to raise this event to tell the server to advance to the next step.

8 – Start New Call JSON following the NewCall format below

To initiate a new call session between the emulator and conversation service the client needs to call this method. If the TropoCallSessionId is passed as empty, the emulator will generate a GUID of its own to use, otherwise the one provided by the client will be used.

9 – Get Active SessionIds Empty String Requests the server to produce a list of all active sessions connected to it and send them to the ActiveSessionIds event to the client. This will be used for clients that wish to monitor sessions going on the emulator. After calling this event the client will get notified of all new sessions and sessions that end as well.

10 – Register for Session Events

SessionId of session to monitor – if you wish to monitor multiple sessions you must register for them individually.

Monitor one or more active sessions being handled by the emulator. Read only view is planned here. When connected the last status of the call (Tropo JSON loaded, say state issued, ask state entered) will be provided. This client will get all “Say Start”, “Ask Start”, “Ask Complete” coming from the server and “Say Complete”, “DTMF” events coming from the driving client. Any calls to change the status of an active call from the monitoring clients will be ignored. Only the client that initiated the StartCall can drive that call.

11 – Unregister for Session Events

SessionId to stop monitoring.

Stop monitoring one or more session being handled by the emulator. Just terminate your session will end monitoring of both session and web traffic will be terminated automatically.

12 – Register for Web Traffic Events

SessionId of session to monitor

All HTTP request and responses going to the conversation service and coming back will be provided to the monitoring client.

12 – Unregister for Web Traffic Events

SessionId to stop monitoring

Stop monitoring HTTP request/response traffic for one or more web socket session Ids

13 – Name Session String for name to associate with session

When monitoring multiple sessions using tools like Session Spy it can be handy to name your sessions something meaningful – this event allows for that.

14 – Get Traffic Info Empty String Asks the server to send a traffic info message which includes connected sessions, conversation service latency, average number of web socket and conversation service calls that have been made in the last minute. Used to monitor multiple servers and route session requests to the least busy server

15 – Get Traffic Info Empty String Used by the routing service if it wants a traffic update from a server out of band. Not currently used as when a server is attached to a router it updates it automatically every 60 seconds.

16 – Get Least Busy Server Empty String Used for talking to a routing service that is monitoring multiple servers – the IP address, web socket port number and HTTP signal port number for the least busy monitored server will be sent to the client using the “Least Busy Server Info” server event.

17 – Update Traffic Info JSON for ServerTrafficInfo structure

Servers send this to a monitoring service instance – in that case they are acting as a client sending updates to the monitoring service every minute.

18 – Generate Dummy Recording Data

Json for Record structure

Tells the emulator server to push a small or large (random) WAV file to the recording target. If speech-to-text is included in the record request that will also be provided. When the media upload for this request is complete, the server raises a “Dummy Recording Complete” event.

19 – Transfer Complete Json for TransferResults structure

Tells the emulator server how to respond to conversation service for a transfer request. Can be any of 6 results triggered.

20 – Hangup Empty string Terminates the current active call but does not tear down the web socket connection between the client and the TENSE server as “Disconnect” does.

21 – Add Bearer Token String – bearer token to use.

Just the token itself (i.e. everything after the “bearer token” moniker). If passed this token will be passed on all calls to CES. Calling this method will simply update the token being used on the current session, it has no bearing on other sessions regardless of target CES server. If this is empty but the login/pw properties are not, basic authentication will be used instead.

22 – Update Session Id String for Tropo Session ID GUID

TENSE Server sends this to TENSE Router (if it’s attached to one) on each new call event to update the router about which TENSE server is handling which Tropo session Id for signal routing purposes

Server Event Types Method calls initiated on the server to connected clients. Follows the same number/string value pair format under the ServerEvent class construct defined below. Clients do not have to implement all of these, however if no handling of “StartSay” is done, for instance, you will never be able to drive a conversation from your application.

Event Parameter Description 0 - Disconnect GUID for the Tropo

CallSessionId (optional) Hangs up the call.

1 – Say Start String for the URI or text to say to the caller

Tells the client a new say segment has started – the server then waits for the client to send a Say Complete event back before proceeding.

2 – Record Start JSON for Record structure Tells the client a new recording segment has started – the server

then waits for the client to send a Record Complete or a Generate Dummy Recording Data event back before proceeding.

3 – Digit Accepted Empty string When the emulator is in an ASK state capable of processing digits, all inbound digit events will all Digit Accepted to that client. If a digit event arrives outside of an ask state, the event is ignored by the emulator.

4 – Error Error string Errors may be sent from the server to a specific client affected or to all clients in the event of a broader server issue

5 – Message Message string Informational messages may be sent by the server to individual clients or all clients.

6 – Ask Start JSON for the Ask structure When a new Ask state is being processed on the emulator, the entire Ask Json structure is sent to the client using this method. The server is not looking for any event from the client for this, it’s purely for informational purposes

7 – Ask Complete Empty string When the emulator exits processing an ask structure, this event is sent to the client

8 – Conversation Service Web Response

JSON for ResponseEvent structure

When a new Tropo session is loaded from the conversation service, the client is called with the entire JSON structure received using this method.

9 – Get Active SessionIds Array of GUIDs using the SessionList structure

Provides a list of web socket session Id GUIDs for all active session on the server the client is attached to. This is called by the server after the GetActiveSessionIds is call by the client.

10 – Web Traffic Update JSON for ResponseEventNotification structure

The request/response pair of a Tropo call to the conversation service and response will be provided to clients that have registered for that against an active web socket session ID

11 – Session Traffic Update for Server Event

JSON for ServerEventNotification structure

For sessions being monitored, when the server sends that session and event, the monitoring clients get a copy of the message via this event as well.

12 – Session Traffic Update for Client Event

JSON for ClientEventNotification structure

For sessions being monitored, when the client sends the server a message the monitoring clients get a copy of that message via this event as well.

13 – New Session Started SessionId string For all monitoring clients that have requested active SessionIds, they will be notified of all new sessions started after that point.

14 – Session Ended SessionId string For all monitoring clients that have requested active SessionIds, they will be notified of all ending sessions, even if they are not monitoring them.

15 – Transfer Start JSON for Transfer structure Tells the client a new transfer segment has started – the server then waits for the client to send a Transfer Complete event back before proceeding.

16 – No Incomplete State Defined

Empty string When a client requests to take an incomplete action or a timeout action but there is no incomplete state defined for the current Ask, the server raises this event to the client to let them know that.

17 – No Error State Defined Empty string When the client requests to take the error action but one is not defined in the currently active “on” clauses, the server raises this event back to the client to let them know that.

18 – Least Busy Server Info JSON for ServerInfo structure Used for clients to talk to a routing service that directs them to the least busy server that it’s monitoring. Used when clients are talking to large server farms.

19 – Transfer Interrupt Arrived

Signal name for the triggered interrupt

When a signal interrupt is sent to TENSE for a particular session that has a matching signal name handler this event is sent to the client associated with that session so they can know the call has be broken out of the loop they were in and process the next conversation request.

20 – HTTP Event JSON for RequestEvent 21 – Dummy Recording Complete

Empty string Sent when the media upload from a Dummy Recording event request is complete

Class Definitions ClientEvent public class ClientEvent { public ClientEventType EventType { get; set; } public string EventData { get; set; } }

ClientEventNotification public class ClientEventNotification { public ClientEvent ClientEvent { get; set; } public string WebSocketSessionId { get; set; } public string TropoSessionId { get; set; } public string CustomerId { get; set; } public string DialedNumber { get; set; } public string ClientIpAddress { get; set; } public string SessionFriendlyName { get; set; } }

NewCall public class NewCall { public string BearerToken { get; set; } public string CallingIdCiscoNumber { get; set; } public string CallingName { get; set; } public string CallingIdSip { get; set; } public string CallingExtension { get; set; } public string CallingUserId { get; set; } public string CallingE164 { get; set; } public string CesServerName { get; set; } public string CesUri { get; set; } public string CiscoTrackingId { get; set; } public string CustomerId { get; set; } public string DateTime { get; set; } public string DialedIdSip { get; set; } public string ForwardingIdSip { get; set; } public string ForwardingIdCiscoNumber { get; set; } public string ForwardingName { get; set; } public string ForwardingReason { get; set; } public string ForwardingName { get; set; } public string ForwardingExtension { get; set; } public string PilotNumber { get; set; } public string Login { get; set; } public string Password { get; set; } public int Port { get; set; } public bool UseHttps { get; set; } public string TropoCallSessionId { get; set; } }

TropoCallSessionId – if provided empty the emulator will generate a GUID of its own.

The DateTime field is an optional string – if left blank the conversation services will get the current date and time from the local system, if passed in that time will be used for routing decisions as such for services like CES (Auto Attendant). The format looks like this “Fri, 22 Apr 2016 11:47:11 GMT”

The BearerToken can be passed and all calls to the target CES server will use that token for this session until it’s replaced – this can be done sending the simple AddBearerToken client event which will replace it. If not passed but the Login and Password are, basic authentication will be used instead.

Record public class Record { public int Attempts { get; set; } public bool BargeIn { get; set; } public bool Beep { get; set; } public Choices Choices { get; set; } public string format { get; set; } // audio/wav or audio/mp3 public float MaxSilence { get; set; } public flaot MaxTime { get; set; } public string Method { get; set; } // PUT or POST public string Name { get; set; } public bool Required { get; set; } public List<Say> Say { get; set; } public Transcription Transcription { get; set; } public string Url { get; set; } public string Password { get; set; } public string UserName { get; set; } public float Timeout { get; set; } public int InterdigitTimeout { get; set; } public string Voice { get; set; } public float Timeout { get; set; } public string AllowSignals { get; set; } }

Choices public class Choices { public string Value { get; set; } // public string Mode { get; set; } // speech, dtmf or any public string Terminator { get; set; } }

Transcription public class Transcription { public string Id { get; set; } // public string Url { get; set; } // uses same login/pw as the wav upload site does }

Transfer public class Transfer { public string to { get; set; }

public string from { get; set; } public float timeout { get; set; } public string name { get; set; } public bool required { get; set; } public Dictionary<string,string> headers { get; set; } public int ringRepeat { get; set; } public bool playTones { get; set; } public bool answerOnMedia { get; set; } public On on { get; set; } //ring or connect on events can be defined public string allowSignals { get; set; } public bool machineDetection { get; set; } public Choices choices { get; set; } public int interdigitTimeout { get; set; } }

Transfer Results 0 – Success Transfer was answered by the destination party 1 – Timeout Call to destination party was not answered before the

timeout expired. 2 – Busy Destination phone was busy. 3 – Failed An unspecified failure occurred 4 – External Event An external event fired (no one knows what this is currently) 5 - Rejected The destination rejected the inbound call (we aren’t real sure

what this means currently yet either)

RequestEvent public class RequestEvent { public DateTime RequestTime { get; private set; } public string RequestType { get; set; } public string RequestUrl { get; set; } public string RequestBody { get; set; } public string RequestHeaders { get; set; } public int ResponseCode { get; set; } public string ResponseBody { get; set; } public string ResponseHeaders { get; set; } public string TropoSessionId { get; set; } }

ResponseEvent public class ResponseEvent { public int Code { get; set; } public string Body { get; set; } public string RequestUrl { get; set; } public string RequestBody { get; set; } public DateTime ResponseTime { get; private set; } }

ResponseEventNotification public class ResponseEvent { public ResponseEvent ResponseEvent { get; set; } public string WebSocketSessionId { get; set; } public string TropoSocketSessionId { get; set; } }

ServerEvent public class ServerEvent { public ServerEventType EventType { get; set; } public string EventData { get; set; } }

ServerEventNotification public class ServerEventNotification { public ServerEvent ServerEvent { get; set; } public string WebSocketSessionId { get; set; } public string TropoSessionId { get; set; } public string CustomerId { get; set; } public string DialedNumber { get; set; } public string ClientIpAddress { get; set; } public string SessionFriendlyName { get; set; } }

SessionList public class SessionList { public List<string> SessionIds; }

Ask public class Ask { public int attempts; public bool bargein; public Choices choices; public int interdigitTimeout; public int minConfidence; public string name; public string recognizer; public bool required; public List<Say> say; public float sensitivity; public float speechCompleteTimeout; public float speechIncompleteTimeout; public float timeout; public string voice; public string allowSignals; }

Say public class Say { public string value; public string as; public string name; public bool required; public string event; public string voice; public string allowSignals; }

Choices public class Choices { public string value; public string mode; public string terminator; }

ServerTrafficInfo public class ServerTrafficInfo { public string IpAddress; public int Port; public int ActiveSessions; public int CesCalls; public long CesLatency; public int InboundSocketMessages; public int OutboundSocketMessages; }

ServerInfo public class ServerInfo { public string IpAddress; public int WebSocketPort; public int HttpSignalPort; }

A Word about Recording and Transcription TENSE includes support for recording and transcriptions that works similar to the “say” framework that allows clients to control the conversation flow easily. For a say sequence, the TENSE server sends a client a “Start Say” event that has the text of the say (actual words or an HTTP reference for a piece of media for instance). The client can choose to log that, play it via speech-to-text, use a media player to play it if it’s a file reference or whatever. When it’s complete it raises a “Say Complete” event to the TENSE server to have it continue.

For recording the client also gets an event from the TENSE server: “Start Record” – the string data for this event is the JSON for the Record structure which contains information such as the desired destination of the recorded media, the HTTP upload location with login/pw details for security as well as if speech-to-text output is desired at the location to send that data as well. At this point the client can:

1. Just send a “Record Complete” back to the server which will then press ahead. This is as if the user did not record anything and just skipped ahead (i.e. pressed # without recording).

2. Gather a recording from the user via a microphone or the like and actually upload it to the target destination and include STT output if that’s desired. This is what the TENSE Phone Emulator client does. It also sends the resulting media to an external STT engine (ATT in this case) and the resulting transcription is sent to the destination in the Record structure. Once the recording of the media is complete, a “Record Complete” event is raised to the server to proceed. The transcription event is raised later out of band which is the same way Tropo does it since the transcription time can be long sometimes.

3. The client can instead raise a “Generate Dummy Record Data” event – the string data for this event is the same JSON for the Record structure the server sends with the “Record Complete” event. The server will then randomly select a small (5 second) or large (25 second) recording file and send it to the destination defined in the Record structure. If a transcription is also defined in the Record structure, a small text string is sent to the transcription target destination as well. Once this is complete the TENSE server proceeds with the normal conversation flow – the client does not need to raise a separate “Record Complete” event to proceed.

Not that for heavy load testing having the server generate the dummy data will add additional overhead to the TENSE server workload and will slow things down a bit. But for normal scripted testing and the like this is a convieient way to allow clients to be written against only web sockets and not have to tangle with complicated multi page MIME uploads of wav files to HTTP targets and the like.

Server Setup TENSE servers are designed to be used in two ways: stand alone on your local client and in packs across multiple servers in conjunction with the routing service to support heavy load scenarios.

Stand Alone By default when you install the TENSE emulation server it will run listening on port 8181 for IP address 127.0.0.1. It has no knowledge of remote conversation servers to talk to or anything else – all of that is provided by the clients that attach to it.

For most local testing scenarios this is all you need – it’s perfectly capable of talking to conversation services such as CES or VM in integration and production from whatever Windows client or server you’re running it on with no further changes. If, however, you want to access that TENSE server from another box you need to instead run it with the actual IP of the box it’s running on and open the port it’s listening on for inbound connections in the Windows Firewall in the control panel. Just run the tense server with “10.20.30.40 8181” as the command line (substituting your actual IP address in there of course) and you’re good to go.

Using the Routing Service There is a substantial TENSE server setup that can be used by anyone developing clients made available out of the Seattle VMWare server farm – the routing services address is 10.93.238.209:8080 and it supports web socket and HTTP signal port traffic routed to about 20 server instances running across several Windows Server 2008 instances. However, if you’d like to setup your own multi server configuration for large load capacity and the like, you certainly can.

Step 1. Run the Routing Service Each installation of the TENSE emulation server include a binary called “SessionRouter.exe” in the installation folder along with the server itself. It uses the same DLLs as the emulator server itself and can simply be run from there. You need to run it with a command line with two parameters – the first being the IP address of the machine you are running it from and the second being the port number it is listening on. Be sure to adjust the firewall settings to allow incoming connections on whatever port it’s listening on.

The router can be run anywhere, server or client Windows install that supports. .NET 4.5 or later. It can have server instances on that same box or not – doesn’t matter. Traffic to and from the routing service is very light – each server it’s monitoring sends it a small amount of traffic information every 60 seconds and clients asking for an IP address connect and raise one event and then go away. As such it’s not critical that this service is running on a powerful server or have excellent bandwidth.

Step 2. Configure Servers to Register with the Service If you’re making a farm of servers for high capacity, presumably you will want to run numerous TENSE emulator servers across several Windows servers. It’s important that these be servers and not client installs of Windows since HTTP session traffic is severely restricted in non-server installations and that will seriously hamper your capacity. Windows Server 2008R2 or 20012R2 work equally well for the task and it’s not necessary to have anything on those servers other than .NET 4.5. You do not need to have the IIS service active (it’s not used) or anything else, so the overall configuration needed is pretty minimal.

Next, install the TENSE Tropo Emulation Service off the web site on the server and edit the LaunchServers.BAT file included in the installation directory – this is provided as a helper to remember how to launch multiple CLI EXEs in a single batch file using the “start” command. So if your server is IP address 10.20.30.40, and the IP address of your routing service you configured in the previous step is 10.20.30.50 listening on port 8080, your BAT file would look something like this:

start "" "TropoEmulatorServer.exe" –l 10.20.30.40 –w 8181 –h 7171 –r 10.20.30.50:8080 start "" "TropoEmulatorServer.exe" –l 10.20.30.40 –w 8182 –h 7172 –r 10.20.30.50:8080 start "" "TropoEmulatorServer.exe" –l 10.20.30.40 –w 8183 –h 7173 –r 10.20.30.50:8080

This spins up 4 server sessions listening on 8 ports (two each) and registers each with the routing service. Be sure to adjust the firewall to allow inbound connections on 8181-8484 and 7171-7474 in this example. The 8181-8484 is the web socket traffic and the 7171-7474 is the HTTP signal port listeners. In testing I’ve found that a Windows 2008R2 with 4 gig of RAM and 4 CPUs works best with 6 service instances when maxed out with client traffic. With load test clients hitting it as hard as they can this

spreads out the web socket traffic enough such that the bottleneck will become the CPU before it runs out of communication capacity.

You can repeat this process on any number of additional Windows servers – there’s no practical limit to how many service instances the router can monitor. Given that 4 servers worth of service instances was enough to generate roughly 10,000 CES web calls a minute under load, there’s no need to go overly wild with it at this point. While a capability of 100,000 calls a minute is impressive, that’s significantly beyond the capabilities of the target services we’re testing at this time.

Step 3. Configure Clients to Request Server Address from Router The Multiple Session Load client available on the TENSE site for download has built in support for requesting the IP/port of the least busy server. To use it simply provide the IP/Port of the routing service on the command line and a parameter “ROUTER” to tell the client that this is a router and not a TENSE Emulation service. In this way you can use the client directly or via the routing service. All future clients such as Night Crawler and other interactive and load clients will include this capability as well.

For instance if you want to start the multiple session load client for 10 sessions where the SAY states play out at 100 words a minute and the ASK states take random amounts of time from 0 to 3 seconds for the user to respond you can start the client up like this:

MultiSessionCSharp.exe 10 100 3000 10.20.30.50:8080 ROUTER

If you don’t include the “ROUTER” in there or include it as “SERVER” it will try and connect to the IP and port as if it were a server which will, of course, fail if you’re pointing it to a routing service.

Version History Server CLI 2.0.10 – 3/8/2017

• Added new calling properties for the updated Spark Call requirements for Avril. • Added updated headers for diversion, remote-id and the new request-uri. • Updated the NewCall structure definition • Updated request-uri to remove dash in header

2.0.8 – 12/12/2016

• Added DummyRecordingComplete event raised to clients when dummy recording request has completed uploading.

• Added additional logging around media upload times to help track delays

2.0.7 – 11/3/2016

• Updated media upload for pre recorded small and large recordings to use bearer token for session when uploading if it’s been set.

2.0.5 – 10/1/2016

• Added functionality to update router service with Tropo session IDs being handled by a server instance talking to a router. Allows for smart routing of signal calls coming to the router to be redirected to the correct server on the back end.

2.0.3 – 9/16/2016

• Added support for sending bearer tokens for client sessions on the NewCall and the new AddBearerToken event.

2.0.2 – 9/14/2016

• Updated debug output to strip any credentials information from URL construction included in the log output

• Checks for unnecessary leading forward slash in URI parameters added to prevent “double slash” after server name which is now being checked for.

2.0.1 – 9/4/2016

• Changed over service to be on OWIN self hosted web server model – all the web socket functions work identically but inbound HTTP events such as signals and log requests are handled via web service controllers. Allow full functionality from within Docker containers and not just as a stand along service on Windows or Linux.

1.0.56 – 9/1/2016

• Fixed issue with signal routing not picking the correct “on” continue state and defaulting to the first one found.

• Added web socket event for signal interrupt notices to listening clients

1.0.54 – 8/31/2016

• Updated to send monitoring clients the request and response header information along with the body/results.

• Fixed issue with advertising address CLI parameter when launched from Docker – it was only being applied if a router service was being employed.

1.0.52 – 8/24/2016

• Added x-tropo-interrupt-url parameter on to new call HTTPS call going from Tropo to CES to set the callback URL to TENSE instead of Tropo.

1.0.51 – 7/28/2016

• Updated logic around invalid key handling during an ask state to force flush of current multi part prompt playback.

1.0.49 – 7/21/2016

• Added support for recording upload failure notices coming back from client. • Added support for recording upload failure notices when using automatic dummy recording

construct

1.0.48 – 6/6/2016

• Updated dummy recording upload logic to include the login/pw authentication in the header when uploading the wav file to the target URL provided.

• Updated response from dummy recording upload to include the “uploadStatus” field in the actions included in the result structure.

1.0.47 – 5/28/2016

• Updated data model for say, ask, record and wait to allow for single strings or a list of strings on the allowSignals element.

• Forced ExpectContinue100 header item to be removed when sending HTTP requests - some proxy servers get tripped up by this including the lab server proxy in Seattle

1.0.45 – 5/12/2016

• Added log download option using the signal port off the server address using “/1.0/logfile/” url. This is a simple HTTP get call currently.

• Added more debug logging output around the hangup/continue/record processing • Updated signals logic to force HTTP only for now – HTTPS will have to come later for inbound

messages

1.0.42 – 4/24/2016

• Added DateTime field to the new call structure allowing for custom times to be sent into the conversation service that is looking at the INVITE_DATE_HEADER property in the SIP header details.

• Added full header details for all request and responses sent and received from the target conversation service in the HTTP traffic info structures sent to clients for tracking purposes.

1.0.41 – 4/18/2016

• Made minor project adjustments to build for Mono support on Linux. • Added container construction support and made public container images on DockerHub

available.

1.0.40 – 4/4/2016

• Removed dashes from GUID used for Cisco session-id header value in new call offer. • Adjusted behavior when no valid instruction remains for processing – error is kicked out but

then conversation session is torn down as if we received a proper “hangup” instruction

1.0.38 – 3/31/2016

• Changed CLI options to be more extendable and easier to use. Updated launch bat file among other things.

• Added server design notes to the source control for code reviewers

1.0.37 – 3/24/2016

• Added Cisco Tracking Id to new call construction – if not provided by the client in the new call request a GUID is generated on the fly by the server.

• Updated error handling for 400+ response codes coming from conversation service – a separate “error” client event is raised rather than sending the normal response back which typically causes the client to fail parsing the string as JSON.

1.0.36 – 3/17/2016

• Added ability to have a separate IP address from the advertised IP address when registering with the routing service. Needed for hosted services that have internal/external IPs and ports that are different.

1.0.35 – 3/14/2016

• Fixed generate dummy record logic to randomly pick a terminating character from the record’s choices structure. If empty, none is returned.

• Fixed case where error status code from conversation service is not being retuned on an error, instead 404 is always sent.

• Fixed issue where “on” state with embedded “say” was not being processed.

1.0.34 – 3/7/2016

• Updated default HTTP timeout from 15 to 30 seconds. • Added 50 ms wait between canceling current running script and returning event to client when

responding to a server error event on a client session. • Fixed issue with error handling – forced any requests to follow “on” states not related to error

to cancel while error state is being handled. Regular processing of instructions continues after error path (if present) is processed.

1.0.33 – 2/22/2016

• Added the HTTP signal port used by the server to the information sent to the routing service that, in turn, provides that information to clients. This allows large server farms to handle both web socket and HTTP signal port traffic spread across many server instances cleanly.

1.0.32 – 2/17/2016

• Fixed issue with record details (url/name) when acting on recording (accept/reject) after recording was complete and uploaded.

1.0.31 – 2/11/2016

• Fixed issue with “result” wrapper on record results not being formatted correctly

1.0.30 – 2/5/2016

• Added record termination reason to recordComplete event from client to server • Fixed issues with invalid input handling resulting in say repeats that were not necessary • Added support for handling skipping to timeout and invalid input events if a record state is

active.

• Added support for jumping to the “hangup” on event if one is defined when a hangup event comes in from client

• Updated record complete event to send name, url and other properties to the conversation service in the follow on request

1.0.29 – 1/31/2016

• Rolled back fix for formatting diversion header details to original format • Fixed issue where “hangup” event embedded in instructions would not be shown properly on

client output. • Add ability to set login/password for both HTTP and HTTPS modes • Updated record logic to issue continue statement only after record upload is complete. • Updated hangup to be more responsive from the client side • Changed diversion header and other header elements to force lower case since CES looks to be

case sensitive in parsing those out (SIP header is caps, what comes from Tropo is lowered).

1.0.27 – 1/21/2016

• Added hangup event for clients separate from the full disconnect event already plumbed in. Allows for terminating call without tearing down the web socket connection in the process.

• Changed new call function to allow the transport to be used to be passed in on the call request so each call can determine if the pathway to the conversation service is HTTP or HTTPS.

• Fixed formatting issue with diversion header details in call request body.

1.0.24 – 1/5/2016

• Updated NewCall structure and new call presentation logic to add more detail on inbound call offer including forwarding reason, forwarding name, breaking up SIP and cisco number values to be properly presented in the header info sent to the call handling service (CES or Avril)

1.0.23 – 12/16/2015

• Added support for new TransferStart/TransferComplete eventing model giving clients control over transfer event results. Currently only successful transfers are processed – working on error events.

1.0.22 – 12/13/2015

• Fixed mixed TTS and media file playback used by GUI phone emulator

1.0.21 – 12/8/2015

• Added support for record and transcription verbs for Tropo and StartRecord, FinishedRecord and GenerateDummyRecordingData web socket events for use by clients.

1.0.20 – 12/2/2015

• Added additional logging and CPU usage tracking • Included lib libraries in installation for client developers • Removed VS 2015 specific string handling so it’ll build on older versions of VS

• Removed some unnecessary CLI output

1.0.19 – 11/22/2015

• Added server traffic information responses for supporting a session routing service supporting multiple server installs

• Removed multiple port options for single server instance • Added CLI and server options for contacting and responding to routing services used to direct

client data to least busy servers in a multiple server configuration.

1.0.17 – 11/14/2015

• Reformatted server help format and updated content

1.0.16 – 11/12/2015

• Added support for the client forcing a route to the timeout, invalid input states • Added support for client requesting to throw a Tropo error state • Added second logging file for running performance number output in CSV format. • Added updated latency and session count/traffic info every 60 seconds – updated in

performance output log as well as on the console title.

1.0.11 – 11/1/2015

• Updated console output to include color for different log type outputs • Added session naming option for easier monitoring output • Simplified threading model and fixed a few bugs around messages being raised for socket

sessions that are terminated before being sent and raising an error as a result.

1.0.10 – 10/30/2015

• Added support for transfers • Updated notification eventing models for monitoring clients

1.0.7 – 10/19/2015

• Moved some server side logging to debug to clean up the CLI output a bit • Added support for sending disconnect events from the server to the client and handling

disconnect events raised from the client.

1.0.6 – 10/18/2015

• First fully working version talking to CES and broadcasting methods to connected clients cleanly. Can do most conversation navigation using Client CLI at this point.

Router CLI 1.0.7 – 10/1/2016

• Broke router project into separate install • Added ability to route HTTP signal request coming to the router to the correct TENSE server

based on TropoSessionId mapping