Hello,

A great use of Token initiated calls, or calls initiated via HTTP request, are click to call applications. This is when you have a fancy button on your website and can have your customers simply ‘click to call’ your call center. This allows them to get right to the people they need quickly and effectively, but how do you do it? Well over here at the ‘Halls of Justice’, sorry I mean Tropo Support we get this a lot. This being the case I have gone ahead and put together a nice example to show you just how to put a click to call application together!

So before we start I need to make one thing clear, Scripting is top down execution, or the fancy word is synchronous. This means task 2 can’t start until task 1 is complete, but to get around this we will make use of threads, providing our language of choice supports it. In Ruby this is pretty simple, and other markups may allow for threading, but that is a whole another discussion. In this example it’s Ruby and we are using with threads, just go with it =):

So, in order to start a new thread you just need a call to Thread.new. A new thread will be created to execute the code inside the thread block, then the original thread will return from Thread.new right away and continue with the next statement

# Thread #1 is running here
 Thread.new
  # Thread #2 runs this code
 end
# Thread #1 runs this code

If you want to read up on this more there is a great tutorial I have linked here which you should check out.

Now this whole posting is predicated on the fact that you do know how to do a token call, so if you don’t please take a quick look at the Tropo Session API (Token Initiation ) documentation. You can find this here in our documentation so please give it a read if you have not already.

In this example we are going to base our code on a code snippet provided in that section of our documentation:

call('tel:+1' + $numberToDial, {
  :onAnswer => lambda { |event|
    say("Hello " + $customerName + ", " + $message);
    log("Contacted customer: " + $numberToDial);
    hangup()
  }}
)

So this example will call someone, and it will play a message, but that is only going to get us halfway there I am afraid; The reason is we not only need to call our user (customer) we also need to call our call center. Once have them both on the line we then need to get them to talk to each other using a conference. Since as I mentioned Ruby is executed top down we’ll need to use threads in order to achieve this goal. Yea, it may sound complicated, but in actuality it’s bark is much worse then it’s bite; Lets take a look at the finished example below:

#Define Global Options
operatorNumber = "4074181800"
applicationCallerID = "8008675309"

#Method to create timeStamp as our conferenceID
	def get_conference_id()
		timeVar  = Time.new
		returnValue = timeVar.strftime("%Y%H%M%S")
		return returnValue
	end

	conferenceOptions={
				:mute=>false,
				:playTones=>true,
				:leaveprompt=>"beep"
				}

begin

#Create conference ID
 conferenceID = get_conference_id()

#Call First Leg (User)
	call 'tel:+1'+$numberToCall, {
	        :callerID => applicationCallerID,
	        :onAnswer => lambda{|event|
			log "@"*5 + "User has answered"
			#Create second thread for second leg (Operator)
			Thread.new do
				log "@"*5 + "Start second tread"
					call 'tel:+1'+operatorNumber, {
						:callerID=>applicationCallerID,
						:onAnswer=>lambda{|event|
							log "@"*5+"Operator answered join conference"
							newCall = event.value
							#announce caller
							newCall.say("You have a call from " + $callerName)
							#join operator to conference
							newCall.conference(conferenceID,conferenceOptions)
						}
					}
			end

			newCall = event.value
			# prompt user
			newCall.say("Please hold while we connect you")
			newCall.conference(conferenceID,conferenceOptions)
		}
	}
end

The only thing really not covered here is the fact that you need to have a conference to join the callers, and since we are using threads we need to make sure each one joins the right conference. This is done with the conference ID, and in my example we are going to use a time stamp, called from a method, as our conferenceID.

#Method to create timeStamp as our conferenceID
	def get_conference_id()
		timeVar  = Time.new
		returnValue = timeVar.strftime("%Y%H%M%S")
		return returnValue
	end

So I think this part is pretty simple, and I don’t think going in to much more then a ‘hey look at that, it’s that thing you like’ type of explanation is really needed here; Of course if I am wrong please comment below, or contact our support team, and we would be glad to offer more clarification.

So as a whole you can see the script is pretty simple, we just fire off an HTTP request to the session API which can be done by a form on our website (obviously you need to change the values highlighted here):

<form action="http://api.tropo.com/1.0/sessions" method="get" accept-charset="utf-8">
	<input type="text" name="numberToCall" value="4075551212"/><br>
	<input type="text" name="callerName" value="John"/><br>
	<input type="hidden" name="token" value="token_id_goes_here"/>
	<input type="hidden" name="action" value="create"/>
	<p><input type="submit" value="Continue &rarr;"></p>
</form>

Of if you want you can also use CURL as well:

curl -I "http://api.tropo.com/1.0/sessions?action=create&token=my_token_id_goes_here&numberToCall=4075551212&callerName=john"

You can even get real fancy and build an XML payload which you can then post to the sessions API (curl -d @token.xml “http://api.tropo.com/1.0/sessions”)

<session>
 <token>my_token_id_goes_here</token>
 <var name="callerName" value="John"/>
 <var name="numberToCall" value="4075551212"/>
</session>

Once we caller 1 has answered we do a Thread.new and call caller two, and then as mentioned above Thread.new instantly returns us the the first thread and then we join caller 1 to the conference. Then once caller two answers we announce caller 1′s name and join him to the waiting conference participant, pretty simple huh?

Well I really do hope this is helpful, and if there are any questions on any of this please let us know!

Regards,

John Dyer
Customer Engineer
Voxeo Support