If you are in Spain next week then you may be interested in stopping by the ETSII University in Seville, where it will take place one of the most exciting events in Europe this year, the Apache Barcamp Spain. An event created by developers for developers. It promises to be a great event with lots of fun.

We are proud sponsors of this event and we will be there speaking about Tropo and Phono and helping anyone interested to learn more about these awesome platforms.

By the way, the event sold out pretty quickly but we still have some spare tickets for anyone planning to attend. So if you happen to be at the sunny Spain next week and you are interested then in attending then do not hesitate to contact us.

Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design. This blog will discuss how to implement Django with Python to receive and reply to a text message – note that installation instructions will be Mac oriented, if you use Windows you can find some alternate install instructions here.

Requirements:
    1)Tunnlr - used to simulate a web server, so you can test from a desktop
        -signup to Tunnlr here
        -detailed instructions on setup can be found here
    2)Python Library
        -Download in the terminal:
              $git clone https://github.com/tropo/tropo-webapi-python.git
        -Or download directly from github.com here             
    3)Django
        -Download Django-1.3.1.tar.gz
          Next, in the terminal, execute the following
              $cd Django-1.3.1
              $sudo python setup.py install

Follow the above instructions to install/setup Tunnlr and Django; once they’re ready, go into whatever directory you want the Django/Tropo app to reside in (Sites/Django_Apps, for example. Once you’re in your chosen directory, go ahead and download the Python library mentioned above. With everything installed and downloaded, enter this in the terminal:

    $django-admin.py startproject mysite

This will create a directory that looks like this:

    mysite/
        __init__.py
        manage.py
        settings.py
        urls.py

The file “urls.py” is the only one that needs to be edited in this directory. Open this file and insert this:

from django.conf.urls.defaults import * 
from hello.views import hello

urlpatterns = patterns('',
('^hello/$', hello)
)

This sets the URL that calls the app to something like this http://server_example.com/hello/, and sets it to specifically call the method “hello” in the actual Tropo app.

On to the meat – while in the mysite directory, enter the following in the terminal:

    $python manage.py startapp hello

This will open another directory with four more files as shown below:

    hello/
        __init__.py
        models.py
        tests.py
        views.py

The Tropo application will be stored in the “views.py” file, shown below, which receives a text and replies back to the same number:

# Create your views here.
# sends information back to Tropo
from django.http import HttpResponse  
# This will allow you to call Tropo functions
from tropo import Tropo 
# This will bypass authorization
from django.views.decorators.csrf import csrf_exempt
@csrf_exempt

# hello is the method name called by urls.py 
# Also, request is where all of the text's information lies
def hello(request): 
  t = Tropo()
  # This is the initial text that you want to extract
  msg = request.POST['msg'] 
  # This sends a text reply back
  json = t.say("you just said: " + msg) 
  # This renders the reply into JSON so Tropo can read it
  json = t.RenderJson(json) 
  # This sends the JSON to Tropo
  return HttpResponse(json) 

Now that this is complete, go to Tropo and create a new WebAPI app. Define the URL that powers this app as your Tunnlr address (which can be set up and located using the Tunnlr instructions mentioned earlier), followed by the app name. In our case, it would be :

    http://web1.tunnlr.com:XXXXX/hello/

Hit Create, then once the screen refreshes with your application, add a U.S. number (needed to send an SMS) and hit Update.

You now want to launch Tunnlr under port 8000, in order for the app to be accessible – instructions on the manual launch of Tunnlr can be found on the same instructions page mentioned earlier. Django comes with its own webserver, which is mostly used for development, and we’re going to use it to access the app. Navigate to the directory mysite, which we were in previously, and enter:

    $python manage.py runserver

With the Django webserver running and Tunnlr open and ready, you can now send a text to the phone number you added to your Tropo app earlier – shortly after sending, you should receive a text message back saying “You just said: …..”

That pretty much sums everything up – it’s a basic example without a lot of real world functionality, but we received enough questions on how to implement Django with Tropo that we felt a quick example would be beneficial. You can view both of the created directories on github here.

Note that all of the Tunnlr bits are unnecessary if you have an actual webserver – you would just be running Django there, instead, and using the URL to your server and the “hello” resource.

We often get a common request to create a “whisper” dialog, where an inbound call is transferred to a second contact, and that contact has the option to decline the call or accept it. While our transfer doesn’t have that level of functionality, there is a relatively straightforward method using a conference to mimic it.

The following app is written in PHP and intended for Tropo Scripting; it also utilizes our REST API to submit an interrupt signal, which we’ll get into in more detail shortly.

We’ll need to initially describe what the app does, as it loops back on itself, making code breakouts difficult to explain linearly. Essentially, the app has if/else logic built into to handle an inbound call and an outbound call. When an inbound call comes in, Tropo drops the user into a conference and lets them sit for a few moments. While they wait, Tropo relaunches the same app using the curl REST client for PHP and makes an outbound call to a second contact. When this contact picks up, they’re prompted to accept or decline a call – if they say yes, they’re dropped into the same conference as the inbound caller. If they say no, Tropo disconnects the original conference with the inbound caller using a signal and then disconnects the outbound call as well.

With the general explanation out of the way, we’ll move on to the code. First, we define a couple of functions:

<?php

function choiceFCN($event) {
    global $session;
    if ($event->value == "yes") {
        conference("1337");
    }
    else {
        $curl_handle=curl_init(); 
        curl_setopt($curl_handle,CURLOPT_URL,'https://api.tropo.com
/1.0/sessions/'.$session.'/signals?action=signal&value=exit'); 
        curl_setopt($curl_handle,CURLOPT_CONNECTTIMEOUT,2); 
        curl_exec($curl_handle); 
        curl_close($curl_handle);
        say("You declined, disconnecting");
    }
}

function badChoiceFCN($event) {
    say("I’m sorry,  I didn’t understand that. You can say yes or no");
}

These functions determine what to do when the outbound call recipient says yes or no, or something completely different like “okay”. choiceFCN is the more complicated of the two – if the recipient says ‘yes’, then you can see where the conference is connected. If they say ‘no’, curl is utilized to submit a signal to the inbound caller’s conference to disconnect it, and then disconnects the outbound call as well.

Next, we have the if/else functionality, which is the bulk of the app:

if ($currentCall->callerID == null) {
    call("+14075550100");
    ask("Do you want to connect to ".$caller."?", array(
        "choices" => "yes, no",
        "timeout" => 10.0,
        "attempts" => 3,
        "onChoice" => "choiceFCN",
        "onBadChoice" => "badChoiceFCN"
        )
    );
}
else {
    $token = 'your_token';
    $callerID = $currentCall->callerID;
    $sessionID = $currentCall->sessionId; 
    $curl_handle=curl_init(); 

    curl_setopt($curl_handle,CURLOPT_URL,'http://api.tropo.com/1.0/
sessions?action=create&token='.$token.'&caller='.$callerID.'
&session='.$sessionID); 
    curl_setopt($curl_handle,CURLOPT_CONNECTTIMEOUT,2); 
    curl_exec($curl_handle); 
    curl_close($curl_handle); 

    say("please hold while we connect your call");
    conference("1337", array(
        "allowSignals" => "exit"
        ));
    say("The recipient declined the call.  Goodbye.");
    }
?>

The inbound/outbound detection is done through the use of “callerID” – no callerID means the app was launched using a token, and therefore outbound. So if callerID is null, trigger the outbound portion of the app; if there is a callerID, launch the inbound portion.

The outbound portion is relatively straightforward – call out to a number, ask the user if they want to connect, use the onChoice and onBadChoice handlers to define which function to use in each case. The inbound, on the other hand, is a little more complex. There’s several variables to start:

$token = 'your_token'; $callerID = $currentCall->callerID; $sessionID = $currentCall->sessionId;

First variable is the token for your app, which is found beneath the URLs when you’re looking at your app in the Tropo UI. Second is saving the callerID of the inbound user for use during the outbound session, and then the sessionID as well for use in the signaling.

Once the variables are locked in, the curl to relaunch the app for the outbound call is started, and then the inbound caller is dropped into the conference. Note in the URL for the curl we add in the variable from earlier – this passes them into the outbound portion of the app as variables that we can then use. Also note in the actual conference the inbound caller is added to, there’s an extra variable in there called “allowSignals”. This is where you define a keyword (or “signal”) that can be used by the REST API to interrupt the conference, dropping the caller back to the application. If the outbound user says “no” and the signal is sent (defined in the URL

https://api.tropo.com/1.0/sessions/'.$session.'/signals?action=signal&value=exit

shown in the earlier portion of code), the conference will disconnect and the inbound user will hear “The recipient declined the call. Goodbye.”

That’s the extent of it; hope it helps someone! You can find the complete app on my Github, feel free to use it and abuse it as you see fit.