tropo-webapi-python

A set of Python classes for working with the Tropo WebAPI

7 years after

NAME

tropo - The TropoPython module. This module implements a set of classes and methods for manipulating the 
Web API for the Tropo cloud communications service at http://www.tropo.com/

For more information about the Tropo Web API that is used with this module, please see:

    http://www.tropo.com/docs/webapi/

As this python module is still in development, please report any bugs or issues by raising an issue here:

    http://github.com/tropo/tropo-webapi-python/issues

FILE

http://github.com/tropo/tropo-webapi-python/blob/master/tropo.py

DESCRIPTION

Usage:

----
from tropo import Tropo

tropo = Tropo()
tropo.say("Hello, World")
json = tropo.RenderJson() 
----

You can write this JSON back to standard output to get Tropo to perform 
the action. For example, on Google Appengine you might write something like:

handler.response.out.write(json)

Much of the time, a you will interact with Tropo by  examining the Result 
object and communicating back to Tropo via the Tropo class methods, such 
as "say". In some cases, you'll want to build a class object directly such as in :

    choices = tropo.Choices("[5 digits]").obj

    tropo.ask(choices, 
              say="Please enter your 5 digit zip code.", 
              attempts=3, bargein=True, name="zip", timeout=5, voice="dave")
    ...

NOTE ON PYTHON VERSIONS

This module is for python 2.x and requires python 2.5 or higher.  
There is a separate version available for python 3.x at:

  http://github.com/tropo/python-webapi/tree/python3

TESTS

Run testsuite by issuing:

cd test
python test.py

CLASSES Ask Call Choices Conference Hangup Message On Record Redirect Reject Result Say Session StartRecording StopRecording Transfer Tropo unittest.TestCase(builtin.object) TestTropoPython

class Ask
 |  Class representing the "ask" Tropo action. Builds an "ask" JSON object.
 |  Class constructor arg: choices, a Choices object
 |  Convenience function: Tropo.ask()
 |  Class constructor options: attempts, bargein, choices, minConfidence, name, recognizer, required, say, timeout, voice
 |  
 |  Request information from the caller and wait for a response.
 |  (See https://www.tropo.com/docs/webapi/ask.htm)
 |  
 |      { "ask": {
 |          "attempts": Integer,
 |          "bargein": Boolean,
 |          "choices": Object, #Required
 |          "minConfidence": Integer,
 |          "name": String,
 |          "recognizer": String,
 |          "required": Boolean,
 |          "say": Object,
 |          "timeout": Float,
 |          "voice": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, choices, **options)

class Call
 |  Class representing the "call" Tropo action. Builds a "call" JSON object.
 |  Class constructor arg: to, a String
 |  Class constructor options: answerOnMedia, channel, from, headers, name, network, recording, required, timeout
 |  Convenience function: Tropo.call()
 |  
 |  (See https://www.tropo.com/docs/webapi/call.htm)
 |  
 |  { "call": {
 |      "to": String or Array,#Required
 |      "answerOnMedia": Boolean,
 |      "channel": string,
 |      "from": string,
 |      "headers": Object,
 |      "name": String,
 |      "network": String,
 |      "recording": Array or Object,
 |      "required": Boolean,
 |      "timeout": Float } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, to, **options)

class Choices
 |  Class representing choice made by a user. Builds a "choices" JSON object.
 |  Class constructor options: terminator, mode
 |  
 |  (See https://www.tropo.com/docs/webapi/ask.htm)
 |  
 |  Methods defined here:
 |  
 |  __init__(self, value, **options)

class Conference
 |  Class representing the "conference" Tropo action. Builds a "conference" JSON object.
 |  Class constructor arg: id, a String
 |  Convenience function: Tropo.conference()
 |  Class constructor options: mute, name, playTones, required, terminator
 |  
 |  (See https://www.tropo.com/docs/webapi/conference.htm)
 |  
 |  { "conference": {
 |      "id": String,#Required
 |      "mute": Boolean,
 |      "name": String,
 |      "playTones": Boolean,
 |      "required": Boolean,
 |      "terminator": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, id, **options)

class Hangup
 |  Class representing the "hangup" Tropo action. Builds a "hangup" JSON object.
 |  Class constructor arg: 
 |  Class constructor options: 
 |  Convenience function: Tropo.hangup()
 |  
 |  (See https://www.tropo.com/docs/webapi/hangup.htm)
 |  
 |  { "hangup": { } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self)

class Message
 |  Class representing the "message" Tropo action. Builds a "message" JSON object.
 |  Class constructor arg: say_obj, a Say object
 |  Class constructor arg: to, a String
 |  Class constructor options: answerOnMedia, channel, from, name, network, required, timeout, voice
 |  Convenience function: Tropo.message()
 |  
 |  (See https://www.tropo.com/docs/webapi/message.htm)
 |  { "message": {
 |          "say": Object,#Required
 |          "to": String or Array,#Required
 |          "answerOnMedia": Boolean,
 |          "channel": string,
 |          "from": Object,
 |          "name": String,
 |          "network": String,
 |          "required": Boolean,
 |          "timeout": Float,
 |          "voice": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, say_obj, to, **options)

class On
 |  Class representing the "on" Tropo action. Builds an "on" JSON object.
 |  Class constructor arg: event, a String
 |  Class constructor options:  name,next,required,say
 |  Convenience function: Tropo.on()
 |  
 |  (See https://www.tropo.com/docs/webapi/on.htm)
 |  
 |  { "on": {
 |      "event": String,#Required
 |      "name": String,
 |      "next": String,
 |      "required": Boolean,
 |      "say": Object } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, event, **options)

class Record
 |  Class representing the "record" Tropo action. Builds a "record" JSON object.
 |  Class constructor arg: 
 |  Class constructor options: attempts, bargein, beep, choices, format, maxSilence, maxTime, method, minConfidence, name, password, required, say, timeout, transcription, url, username
 |  Convenience function: Tropo.record()
 |  
 |  
 |  
 |  (See https://www.tropo.com/docs/webapi/record.htm)
 |  
 |      { "record": {
 |          "attempts": Integer,
 |          "bargein": Boolean,
 |          "beep": Boolean,
 |          "choices": Object,
 |          "format": String,
 |          "maxSilence": Float,
 |          "maxTime": Float,
 |          "method": String,
 |          "minConfidence": Integer,
 |          "name": String,
 |          "password": String,
 |          "required": Boolean,
 |          "say": Object,
 |          "timeout": Float,
 |          "transcription": Array or Object,
 |          "url": String,#Required ?????
 |          "username": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, **options)

class Redirect
 |  Class representing the "redirect" Tropo action. Builds a "redirect" JSON object.
 |  Class constructor arg: to, a String
 |  Class constructor options:  name, required
 |  Convenience function: Tropo.redirect()
 |  
 |  (See https://www.tropo.com/docs/webapi/redirect.htm)
 |  
 |  { "redirect": {
 |      "to": Object,#Required
 |      "name": String,
 |      "required": Boolean } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, to, **options)

class Reject
 |  Class representing the "reject" Tropo action. Builds a "reject" JSON object.
 |  Class constructor arg: 
 |  Class constructor options: 
 |  Convenience function: Tropo.reject()
 |  
 |  (See https://www.tropo.com/docs/webapi/reject.htm)
 |  
 |  { "reject": { } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self)

class Result
 |  Returned anytime a request is made to the Tropo Web API. 
 |  Method: getValue 
 |  (See https://www.tropo.com/docs/webapi/result.htm)
 |  
 |      { "result": {
 |          "actions": Array or Object,
 |          "complete": Boolean,
 |          "error": String,
 |          "sequence": Integer,
 |          "sessionDuration": Integer,
 |          "sessionId": String,
 |          "state": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, result_json)
 |  
 |  getValue(self)
 |      Get the value of the previously POSTed Tropo action.

class Say
 |  Class representing the "say" Tropo action. Builds a "say" JSON object.
 |  Class constructor arg: message, a String, or a List of Strings
 |  Class constructor options: attempts, bargein, choices, minConfidence, name, recognizer, required, say, timeout, voice
 |  Convenience function: Tropo.say()
 |  
 |  (See https://www.tropo.com/docs/webapi/say.htm)
 |  
 |  { "say": {
 |      "as": String,
 |      "name": String,
 |      "required": Boolean,
 |      "value": String #Required
 |      } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, message, **options)

class Session
 |  Session is the payload sent as an HTTP POST to your web application when a new session arrives. 
 |  (See https://www.tropo.com/docs/webapi/session.htm)
 |  
 |  Methods defined here:
 |  
 |  __init__(self, session_json)

class StartRecording
 |  Class representing the "startRecording" Tropo action. Builds a "startRecording" JSON object.
 |  Class constructor arg: url, a String
 |  Class constructor options: format, method, username, password
 |  Convenience function: Tropo.startRecording()
 |  
 |  (See https://www.tropo.com/docs/webapi/startrecording.htm)
 |  
 |  { "startRecording": {
 |      "format": String,
 |      "method": String,
 |      "url": String,#Required
 |      "username": String,
 |      "password": String } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, url, **options)

class StopRecording
 |   Class representing the "stopRecording" Tropo action. Builds a "stopRecording" JSON object.
 |   Class constructor arg:
 |   Class constructor options:
 |   Convenience function: Tropo.stopRecording()
 |  
 |  (See https://www.tropo.com/docs/webapi/stoprecording.htm)
 |     { "stopRecording": { } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self)

class TestTropoPython(unittest.TestCase)
 |  Class implementing a set of unit tests for TropoPython.
 |  
 |  Method resolution order:
 |      TestTropoPython
 |      unittest.TestCase
 |      __builtin__.object
 |  
 |  Methods defined here:
 |  
 |  test_ask(self)
 |      Test the "ask" Tropo class method.
 |  
 |  test_call(self)
 |      Test the "call" Tropo class method.
 |  
 |  test_conference(self)
 |      Test the "conference" Tropo class method.
 |  
 |  test_hangup(self)
 |      Test the "hangup" Tropo class method.
 |  
 |  test_list_say(self)
 |      Test the "say" Tropo class method, when a list of Strings is passed to it.
 |  
 |  test_message(self)
 |      Test the "message" Tropo class method.
 |  
 |  test_on(self)
 |      Test the "on" Tropo class method.
 |  
 |  test_record(self)
 |      Test the "record" Tropo class method.
 |  
 |  test_redirect(self)
 |      Test the "redirect" Tropo class method.
 |  
 |  test_reject(self)
 |      Test the "reject" Tropo class method.
 |  
 |  test_say(self)
 |      Test the "say" Tropo class method.
 |  
 |  test_startRecording(self)
 |      Test the "startRecording" Tropo class method.
 |  
 |  test_stopRecording(self)
 |      Test the "stopRecording" Tropo class method.
 |  
 |  test_transfer(self)
 |      Test the "transfer" Tropo class method.
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes defined here:
 |  
 |  ID = 'foo'
 |  
 |  MY_PHONE = '6021234567'
 |  
 |  RECORDING_URL = '/receive_recording.py'
 |  
 |  S3_URL = 'http://s3.amazonaws.com/xxx_s3_bucket/hello.wav'
 |  
 |  TO = '8005551212'
 |  
 |  ----------------------------------------------------------------------
 |  Methods inherited from unittest.TestCase:
 |  
 |  __call__(self, *args, **kwds)
 |  
 |  __init__(self, methodName='runTest')
 |      Create an instance of the class that will use the named test
 |      method when executed. Raises a ValueError if the instance does
 |      not have a method with the specified name.
 |  
 |  __repr__(self)
 |  
 |  __str__(self)
 |  
 |  assertAlmostEqual = failUnlessAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are unequal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  assertAlmostEquals = failUnlessAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are unequal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  assertEqual = failUnlessEqual(self, first, second, msg=None)
 |      Fail if the two objects are unequal as determined by the '=='
 |      operator.
 |  
 |  assertEquals = failUnlessEqual(self, first, second, msg=None)
 |      Fail if the two objects are unequal as determined by the '=='
 |      operator.
 |  
 |  assertFalse = failIf(self, expr, msg=None)
 |      Fail the test if the expression is true.
 |  
 |  assertNotAlmostEqual = failIfAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are equal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  assertNotAlmostEquals = failIfAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are equal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  assertNotEqual = failIfEqual(self, first, second, msg=None)
 |      Fail if the two objects are equal as determined by the '=='
 |      operator.
 |  
 |  assertNotEquals = failIfEqual(self, first, second, msg=None)
 |      Fail if the two objects are equal as determined by the '=='
 |      operator.
 |  
 |  assertRaises = failUnlessRaises(self, excClass, callableObj, *args, **kwargs)
 |      Fail unless an exception of class excClass is thrown
 |      by callableObj when invoked with arguments args and keyword
 |      arguments kwargs. If a different type of exception is
 |      thrown, it will not be caught, and the test case will be
 |      deemed to have suffered an error, exactly as for an
 |      unexpected exception.
 |  
 |  assertTrue = failUnless(self, expr, msg=None)
 |      Fail the test unless the expression is true.
 |  
 |  assert_ = failUnless(self, expr, msg=None)
 |      Fail the test unless the expression is true.
 |  
 |  countTestCases(self)
 |  
 |  debug(self)
 |      Run the test without collecting errors in a TestResult
 |  
 |  defaultTestResult(self)
 |  
 |  fail(self, msg=None)
 |      Fail immediately, with the given message.
 |  
 |  failIf(self, expr, msg=None)
 |      Fail the test if the expression is true.
 |  
 |  failIfAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are equal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  failIfEqual(self, first, second, msg=None)
 |      Fail if the two objects are equal as determined by the '=='
 |      operator.
 |  
 |  failUnless(self, expr, msg=None)
 |      Fail the test unless the expression is true.
 |  
 |  failUnlessAlmostEqual(self, first, second, places=7, msg=None)
 |      Fail if the two objects are unequal as determined by their
 |      difference rounded to the given number of decimal places
 |      (default 7) and comparing to zero.
 |      
 |      Note that decimal places (from zero) are usually not the same
 |      as significant digits (measured from the most signficant digit).
 |  
 |  failUnlessEqual(self, first, second, msg=None)
 |      Fail if the two objects are unequal as determined by the '=='
 |      operator.
 |  
 |  failUnlessRaises(self, excClass, callableObj, *args, **kwargs)
 |      Fail unless an exception of class excClass is thrown
 |      by callableObj when invoked with arguments args and keyword
 |      arguments kwargs. If a different type of exception is
 |      thrown, it will not be caught, and the test case will be
 |      deemed to have suffered an error, exactly as for an
 |      unexpected exception.
 |  
 |  id(self)
 |  
 |  run(self, result=None)
 |  
 |  setUp(self)
 |      Hook method for setting up the test fixture before exercising it.
 |  
 |  shortDescription(self)
 |      Returns a one-line description of the test, or None if no
 |      description has been provided.
 |      
 |      The default implementation of this method returns the first line of
 |      the specified test method's docstring.
 |  
 |  tearDown(self)
 |      Hook method for deconstructing the test fixture after testing it.
 |  
 |  ----------------------------------------------------------------------
 |  Data descriptors inherited from unittest.TestCase:
 |  
 |  __dict__
 |      dictionary for instance variables (if defined)
 |  
 |  __weakref__
 |      list of weak references to the object (if defined)
 |  
 |  ----------------------------------------------------------------------
 |  Data and other attributes inherited from unittest.TestCase:
 |  
 |  failureException = <type 'exceptions.AssertionError'>
 |      Assertion failed.

class Transfer
 |  Class representing the "transfer" Tropo action. Builds a "transfer" JSON object.
 |  Class constructor arg: to, a String, or List
 |  Class constructor options: answerOnMedia, choices, from, name, required, terminator
 |  Convenience function: Tropo.transfer()
 |  
 |  (See https://www.tropo.com/docs/webapi/transfer.htm)
 |  { "transfer": {
 |      "to": String or Array,#Required
 |      "answerOnMedia": Boolean,
 |      "choices": Object,
 |      "from": Object,
 |      "name": String,
 |      "required": Boolean,
 |      "terminator": String,
 |      "timeout": Float } }
 |  
 |  Methods defined here:
 |  
 |  __init__(self, to, **options)

class Tropo
 |  This is the top level class for all the Tropo web api actions.
 |  The methods of this class implement individual Tropo actions.
 |  Individual actions are each methods on this class.
 |  
 |  Each method takes one or more required arguments, followed by optional
 |  arguments expressed as key=value pairs.
 |  
 |  The optional arguments for these methods are described here:
 |  https://www.tropo.com/docs/webapi/
 |  
 |  Methods defined here:
 |  
 |  PrettyJson(self)
 |      Render a Tropo object into a Json string, pretty-printed with indents.
 |  
 |  RenderJson(self)
 |      Render a Tropo object into a Json string.
 |  
 |  __init__(self)
 |  
 |  ask(self, choices, **options)
 |      Sends a prompt to the user and optionally waits for a response.
 |      Arguments: "choices" is a Choices object
 |      See https://www.tropo.com/docs/webapi/ask.htm
 |  
 |  call(self, to, **options)
 |      Places a call or sends an an IM, Twitter, or SMS message. To start a call, use the Session API to tell Tropo to launch your code. 
 |      
 |      Arguments: to is a String.
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/call.htm
 |  
 |  conference(self, id, **options)
 |      This object allows multiple lines in separate sessions to be conferenced together so that the parties on each line can talk to each other simultaneously. 
 |      This is a voice channel only feature. 
 |      Argument: "id" is a String
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/conference.htm
 |  
 |  hangup(self)
 |      This method instructs Tropo to "hang-up" or disconnect the session associated with the current session.
 |      See https://www.tropo.com/docs/webapi/hangup.htm
 |  
 |  message(self, say_obj, to, **options)
 |      A shortcut method to create a session, say something, and hang up, all in one step. This is particularly useful for sending out a quick SMS or IM. 
 |      
 |      Argument: "say_obj" is a Say object
 |      Argument: "to" is a String
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/message.htm
 |  
 |  on(self, event, **options)
 |      Adds an event callback so that your application may be notified when a particular event occurs. 
 |      Possible events are: "continue", "error", "incomplete" and "hangup". 
 |      Argument: event is an event
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/on.htm
 |  
 |  record(self, **options)
 |      Plays a prompt (audio file or text to speech) and optionally waits for a response from the caller that is recorded. 
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/record.htm
 |  
 |  redirect(self, id, **options)
 |      Forwards an incoming call to another destination / phone number before answering it. 
 |      Argument: id is a String
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/redirect.htm
 |  
 |  reject(self)
 |      Allows Tropo applications to reject incoming sessions before they are answered. 
 |      See https://www.tropo.com/docs/webapi/reject.htm
 |  
 |  say(self, message, **options)
 |      When the current session is a voice channel this key will either play a message or an audio file from a URL. 
 |      In the case of an text channel it will send the text back to the user via i nstant messaging or SMS. 
 |      Argument: message is a string
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/say.htm
 |  
 |  startRecording(self, url, **options)
 |      Allows Tropo applications to begin recording the current session. 
 |      Argument: url is a string
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/startrecording.htm
 |  
 |  stopRecording(self)
 |      Stops a previously started recording.
 |      See https://www.tropo.com/docs/webapi/stoprecording.htm
 |  
 |  transfer(self, to, **options)
 |      Transfers an already answered call to another destination / phone number. 
 |      Argument: to is a string
 |      Argument: **options is a set of optional keyword arguments.
 |      See https://www.tropo.com/docs/webapi/transfer.htm

Related Repositories

tropo-webapi-php

tropo-webapi-php

A set of PHP classes for working with the Voxeo Tropo WebAPI ...

tropo-webapi-php-oop

tropo-webapi-php-oop

A set of PHP classes for working with the Tropo WebAPI ...