Adding dial() method (#143)

* Adding dial() method

Author: normanargueta

README.rst

@@ -307,6 +307,40 @@ Your application server can disconnect a client from an OpenTok session by calli
   # To send a request to disconnect a client:
   opentok.force_disconnect(session_id, connection_id)
 
+Working with SIP Interconnect
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can connect your SIP platform to an OpenTok session, the audio from your end of the SIP call is added to the OpenTok session as an audio-only stream. The OpenTok Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint.
+
+.. code:: python
+
+  session_id = u('SESSIONID')
+  token = u('TOKEN')
+  sip_uri = u('sip:[email protected];transport=tls')
+
+  # call the method with the required parameters
+  sip_call = opentok.dial(session_id, token, sip_uri)
+
+  # the method also support aditional options to establish the sip call
+
+  options = {
+      'from': '[email protected]',
+      'headers': {
+          'headerKey': 'headerValue'
+      },
+      'auth': {
+          'username': 'username',
+          'password': 'password'
+      },
+      'secure': True
+  }
+
+  # call the method with aditional options
+  sip_call = opentok.dial(session_id, token, sip_uri, options)
+
+For more information, including technical details and security considerations, see the
+`OpenTok SIP interconnect <https://tokbox.com/developer/guides/sip/>`_ developer guide.
+
 Samples
 -------
 

opentok/__init__.py

@@ -5,3 +5,4 @@
 from .version import __version__
 from .stream import Stream
 from .streamlist import StreamList
+from .sip_call import SipCall

opentok/endpoints.py

@@ -45,3 +45,8 @@ def set_archive_layout_url(self, archive_id):
         """ this method returns the url to set the archive layout """
         url = self.api_url + '/v2/project/' + self.api_key + '/archive/' + archive_id + '/layout'
         return url
+
+    def dial_url(self):
+        """ this method returns the url to initialize a SIP call """
+        url = self.api_url + '/v2/project/' + self.api_key + '/dial'
+        return url

opentok/exceptions.py

@@ -48,3 +48,11 @@ class ForceDisconnectError(OpenTokException):
     is not connected to the session
     """
     pass
+
+class SipDialError(OpenTokException):
+    """
+    Indicates that there was a SIP dial specific problem:
+    The Session ID passed in is invalid or you attempt to start a SIP call for a session
+    that does not use the OpenTok Media Router.
+    """
+    pass

opentok/opentok.py

@@ -24,6 +24,7 @@
 from .archives import Archive, ArchiveList, OutputModes
 from .stream import Stream
 from .streamlist import StreamList
+from .sip_call import SipCall
 from .exceptions import (
     OpenTokException,
     RequestError,
@@ -32,7 +33,8 @@
     ArchiveError,
     SignalingError,
     GetStreamError,
-    ForceDisconnectError
+    ForceDisconnectError,
+    SipDialError
 )
 
 class Roles(Enum):
@@ -636,6 +638,88 @@ def set_archive_layout(self, archive_id, layout_type, stylesheet=None):
         else:
             raise RequestError('OpenTok server error.', response.status_code)
 
+
+    def dial(self, session_id, token, sip_uri, options=[]):
+        """
+        Use this method to connect a SIP platform to an OpenTok session. The audio from the end
+        of the SIP call is added to the OpenTok session as an audio-only stream. The OpenTok Media
+        Router mixes audio from other streams in the session and sends the mixed audio to the SIP
+        endpoint
+
+        :param String session_id: The OpenTok session ID for the SIP call to join
+
+        :param String token: The OpenTok token to be used for the participant being called
+
+        :param String sip_uri: The SIP URI to be used as destination of the SIP call initiated from
+        OpenTok to the SIP platform
+
+        :param Dictionary options optional: Aditional options with the following properties:
+
+            String 'from': The number or string that will be sent to the final SIP number
+            as the caller
+
+            Dictionary 'headers': Defines custom headers to be added to the SIP INVITE request
+            initiated from OpenTok to the SIP platform. Each of the custom headers must
+            start with the "X-" prefix, or the call will result in a Bad Request (400) response
+
+            Dictionary 'auth': Contains the username and password to be used in the the SIP
+            INVITE request for HTTP digest authentication, if it is required by the SIP platform
+            For example:
+
+                'auth': {
+                    'username': 'username',
+                    'password': 'password'
+                }
+
+            Boolean 'secure': A Boolean flag that indicates whether the media must be transmitted
+            encrypted (true) or not (false, the default)
+
+        :rtype: A SipCall object, which contains data of the SIP call: id, connectionId and streamId
+        """
+        payload = {
+            'sessionId': session_id,
+            'token': token,
+            'sip': {
+                'uri': sip_uri
+            }
+        }
+
+        if 'from' in options:
+            payload['sip']['from'] = options['from']
+
+        if 'headers' in options:
+            payload['sip']['headers'] = options['headers']
+
+        if 'auth' in options:
+            payload['sip']['auth'] = options['auth']
+
+        if 'secure' in options:
+            payload['sip']['secure'] = options['secure']
+
+        endpoint = self.endpoints.dial_url()
+        response = requests.post(
+            endpoint,
+            data=json.dumps(payload),
+            headers=self.json_headers(),
+            proxies=self.proxies,
+            timeout=self.timeout
+        )
+
+        if response.status_code == 200:
+            return SipCall(response.json())
+        elif response.status_code == 400:
+            raise SipDialError('Invalid request. Invalid session ID.')
+        elif response.status_code == 403:
+            raise AuthError('Authentication error.')
+        elif response.status_code == 404:
+            raise SipDialError('The session does not exist.')
+        elif response.status_code == 409:
+            raise SipDialError(
+                'You attempted to start a SIP call for a session that '
+                'does not use the OpenTok Media Router.')
+        else:
+            raise RequestError('OpenTok server error.', response.status_code)
+
     def _sign_string(self, string, secret):
         return hmac.new(secret.encode('utf-8'), string.encode('utf-8'), hashlib.sha1).hexdigest()
 

opentok/sip_call.py

@@ -0,0 +1,17 @@
+import json
+
+class SipCall(object):
+    """
+    Represents data from a SIP call
+    """
+
+    def __init__(self, kwargs):
+        self.id = kwargs.get('id')
+        self.connectionId = kwargs.get('connectionId')
+        self.streamId = kwargs.get('streamId')
+
+    def json(self):
+        """
+        Returns a JSON representation of the SIP call
+        """
+        return json.dumps(self, default=lambda o: o.__dict__, sort_keys=True, indent=4)

tests/test_sip_call.py

@@ -0,0 +1,100 @@
+import unittest
+import textwrap
+import httpretty
+
+from six import u
+from expects import *
+from opentok import OpenTok, SipCall, __version__
+
+from .validate_jwt import validate_jwt_header
+
+class OpenTokSipCallTest(unittest.TestCase):
+    def setUp(self):
+        self.api_key = u('123456')
+        self.api_secret = u('1234567890abcdef1234567890abcdef1234567890')
+        self.opentok = OpenTok(self.api_key, self.api_secret)
+
+        self.session_id = u('SESSIONID')
+        self.token = u('TOKEN')
+        self.sip_uri = u('sip:[email protected];transport=tls')
+
+    @httpretty.activate
+    def test_sip_call_with_required_parameters(self):
+        """
+        Test dial() method using just the required parameters: session_id, token, sip_uri
+        """
+        sip_call = SipCall({
+            u('id'): u('b0a5a8c7-dc38-459f-a48d-a7f2008da853'),
+            u('connectionId'): u('e9f8c166-6c67-440d-994a-04fb6dfed007'),
+            u('streamId'): u('482bce73-f882-40fd-8ca5-cb74ff416036')
+        })
+
+        httpretty.register_uri(
+            httpretty.POST,
+            u('https://api.opentok.com/v2/project/{0}/dial').format(self.api_key),
+            body=textwrap.dedent(u("""\
+                {
+                    "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
+                    "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
+                    "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036"
+                }""")),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        sip_call_response = self.opentok.dial(self.session_id, self.token, self.sip_uri)
+        validate_jwt_header(self, httpretty.last_request().headers[u('x-opentok-auth')])
+        expect(httpretty.last_request().headers[u('user-agent')]).to(contain(
+            u('OpenTok-Python-SDK/')+__version__))
+        expect(httpretty.last_request().headers[u('content-type')]).to(equal(u('application/json')))
+        expect(sip_call_response).to(be_an(SipCall))
+        expect(sip_call_response).to(have_property(u('id'), sip_call.id))
+        expect(sip_call_response).to(have_property(u('connectionId'), sip_call.connectionId))
+        expect(sip_call_response).to(have_property(u('streamId'), sip_call.streamId))
+
+    @httpretty.activate
+    def test_sip_call_with_aditional_options(self):
+        """
+        Test dial() method with aditional options
+        """
+        sip_call = SipCall({
+            u('id'): u('b0a5a8c7-dc38-459f-a48d-a7f2008da853'),
+            u('connectionId'): u('e9f8c166-6c67-440d-994a-04fb6dfed007'),
+            u('streamId'): u('482bce73-f882-40fd-8ca5-cb74ff416036')
+        })
+
+        httpretty.register_uri(
+            httpretty.POST,
+            u('https://api.opentok.com/v2/project/{0}/dial').format(self.api_key),
+            body=textwrap.dedent(u("""\
+                {
+                    "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
+                    "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
+                    "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036"
+                }""")),
+            status=200,
+            content_type=u('application/json')
+        )
+
+        # aditional options to establish the sip call
+        options = {
+            'from': '[email protected]',
+            'headers': {
+                'headerKey': 'headerValue'
+            },
+            'auth': {
+                'username': 'username',
+                'password': 'password'
+            },
+            'secure': True
+        }
+
+        sip_call_response = self.opentok.dial(self.session_id, self.token, self.sip_uri, options)
+        validate_jwt_header(self, httpretty.last_request().headers[u('x-opentok-auth')])
+        expect(httpretty.last_request().headers[u('user-agent')]).to(contain(
+            u('OpenTok-Python-SDK/')+__version__))
+        expect(httpretty.last_request().headers[u('content-type')]).to(equal(u('application/json')))
+        expect(sip_call_response).to(be_an(SipCall))
+        expect(sip_call_response).to(have_property(u('id'), sip_call.id))
+        expect(sip_call_response).to(have_property(u('connectionId'), sip_call.connectionId))
+        expect(sip_call_response).to(have_property(u('streamId'), sip_call.streamId))