NAME

Tropo - Use the TropoAPI via Perl

VERSION

version 0.16

SYNOPSIS

Ask the

  my $tropo = Tropo->new;
  $tropo->call(
    to => $clients_phone_number,
  );
  $tropo->say( 'hello ' . $client_name );
  $tropo->json;

Creates this JSON output:

  {
      "tropo":[
          {
              "call": {
                      "to":"+14155550100"
              }
          },
          {
              "say": [
                  {
                      "value":"Tag, you're it!"
                  }
              ]
          }
      ]
  }

You can also chain the method calls:

  my $tropo = Tropo->new;
  print $tropo->call( to => $phone )->say ( 'hello' )->json;

DESCRIPTION

HOW THE TROPO API WORKS

The Tropo server talks with your web application via json sent with HTTP POST requests.

When you'd like to initiate a call/text message, you have to start a session.

        my $session = Tropo::RestAPI::Session->new(
            url => 'https://tropo.developergarden.com/api/', # use developergarden.com api
        );

        my $data = $session->create(
            token        => $token,
            call_session => $id,
        ) or print $session->err;

When you create a session you can pass any parameter you want. The only mandatory parameter is token. You'll find that token in your developergarden account in the application management.

The Tropo server then requests the URI that you added in the application management. It is an HTTP POST request that contains session data (the parameters that you passed, too). An example of the dumped request data can be found below.

Your application has to send JSON data back to the Tropo server. In that JSON data you can define (see command on) which URLs the Tropo server requests on specific events.

COMMANDS

This list show the commands currently implemented. This library is under heavy development, so that more commands will follow in the near future:

ask

call

on

say

wait

A detailed description of all commands and their attributes can be found at http://www.developergarden.com/fileadmin/microsites/ApiProject/Dokumente/Dokumentation/Api_Doc_5_0/telekom-tropo-2.1/html/method_summary.html|DeveloperGarden.

Only on can't be found there.

EXAMPLES

All examples can be found in the examples directory of this distribution. Those examples might have extra dependencies that you might have to install when you want to run the code.

You also need an account e.g. for developergarden.com or tropo.com.

Two factor authentication

call_customer.psgi

You can find a small Mojolicious::Lite application that calls a customer to tell him a code... On the start page a small form is shown where the customer sends his phone number. Then a new call is initiated and the Tropo provider calls the customer and tells him the secret.

Handle incoming calls

televote.psgi

You can publish a phonenumber that is connected to your application (e.g. in developergardens application management). The people call that number and are asked to "vote"...

MORE INFO

Here you can find some detailed info that might help to debug your code.

Session data sent from Tropo to your app

    $VAR1 = {
          'session' => {
                       'userType' => 'NONE',
                       'parameters' => {
                                       'token' => 'your_api_token',
                                       'action' => 'create',
                                       'call_session' => 'zRlbp7UET5ecDcneDCnoB4'
                                     },
                       'callId' => undef,
                       'initialText' => undef,
                       'timestamp' => '2013-09-06T18:53:20.168Z',
                       'accountId' => '9183',
                       'id' => '9884f64erb41e97948083c25980d63683'
                     }
        };

ACKNOWLEDGEMENT

I'd like to thank Richard from Telekoms Developergarden. He has done a lot of debugging during the #startuphack (Hackathon at "Lange Nacht der Startups" 2013).

AUTHOR

Renee Baecker <module@renee-baecker.de>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2013 by Renee Baecker.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm Tropo

perl -MCPAN -e shell
install Tropo