Merge pull request #198 from opentok/3.x-beta

* SIP Video Outbound and Play DTMF
* Selective Stream API (for Archive/broadcast)
* observeMute API

Author: pardel

opentok/endpoints.py

@@ -132,6 +132,42 @@ def get_broadcast_url(self, broadcast_id=None, stop=False, layout=False):
             url = url + "/layout"
         return url
 
+    def get_mute_all_url(self, session_id):
+        """ this method returns the urls for muting every stream in a session """
+        url = (
+             self.api_url  
+            + "/v2/project/" 
+            + self.api_key
+            + "/session/"
+            + session_id
+            + "/mute"
+
+        )
+
+    def get_dtmf_all_url(self, session_id):
+        """ this method returns the url for Play DTMF to all clients in the session """
+        url = (
+            self.api_url
+            + "/v2/project/" 
+            + self.api_key
+            + "/session/"
+            + session_id
+            + "/play-dtmf"
+        )
+
+    def get_dtmf_specific_url(self, session_id, connection_id):
+        """ this method returns the url for Play DTMF to a specific client connection"""
+        url = (
+            self.api_url
+            + "/v2/project/"
+            + self.api_key
+            + "/session/"
+            + session_id
+            + "/connection/"
+            + connection_id
+            + "/play-dtmf"
+        )
+
     def get_archive_stream(self, archive_id=None):
         """ this method returns urls for working with streamModes in archives """
         url = (

opentok/exceptions.py

@@ -89,6 +89,11 @@ class BroadcastError(OpenTokException):
 
     pass
 
+class DTMFError(OpenTokException):
+    """
+    Indicates that one of the properties digits, session_id or connection_id is invalid
+    """
+
 class ArchiveStreamModeError(OpenTokException):
     """
     Indicates that the archive is configured with a streamMode that does not support stream manipulation.

opentok/opentok.py

@@ -45,6 +45,7 @@
     SipDialError,
     SetStreamClassError,
     BroadcastError,
+    DTMFError
 )
 
 
@@ -1120,9 +1121,51 @@ def dial(self, session_id, token, sip_uri, options=[]):
             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
+            Boolean 'observeForceMute': A Boolean flag that determines whether the SIP endpoint should 
+            honor the force mute action. The force mute action allows a moderator to force clients to 
+            mute audio in streams they publish. It defaults to False if moderator does not want to observe 
+            force mute a stream and set to True if the moderator wants to observe force mute a stream.
+
+            Boolean 'video': A Boolean flag that indicates whether the SIP call will include video(true)
+            or not(false, which is the default). With video included, the SIP client's video is included 
+            in the OpenTok stream that is sent to the OpenTok session. The SIP client will receive a single 
+            composed video of the published streams in the OpenTok session.
+
+            This is an example of what the payload POST data body could look like:
+
+            {
+                "sessionId": "Your OpenTok session ID",
+                "token": "Your valid OpenTok token",
+                "sip": {
+                        "uri": "sip:[email protected];transport=tls",
+                        "from": "[email protected]",
+                        "headers": {
+                            "headerKey": "headerValue"
+                        },
+                    "auth": {
+                        "username": "username",
+                        "password": "password"
+                    },
+                        "secure": true|false,
+                        "observeForceMute": true|false,
+                        "video": true|false
+                    }
+                }
+
+        :rtype: A SipCall object, which contains data of the SIP call: id, connectionId and streamId. 
+        This is what the response body should look like after returning with a status code of 200:
+
+        {
+            "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
+            "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007",
+            "streamId": "482bce73-f882-40fd-8ca5-cb74ff416036",
+        }
+
+        Note: Your response will have a different: id, connectionId and streamId
         """
         payload = {"sessionId": session_id, "token": token, "sip": {"uri": sip_uri}}
+        observeForceMute = False
+        video = False
 
         if "from" in options:
             payload["sip"]["from"] = options["from"]
@@ -1136,6 +1179,14 @@ def dial(self, session_id, token, sip_uri, options=[]):
         if "secure" in options:
             payload["sip"]["secure"] = options["secure"]
 
+        if "observeForceMute" in options:
+            observeForceMute = True
+            payload["sip"]["observeForceMute"] = options["observeForceMute"]
+        
+        if "video" in options:
+            video = True
+            payload["sip"]["video"] = options["video"]
+
         endpoint = self.endpoints.dial_url()
 
         logger.debug(
@@ -1588,4 +1639,81 @@ def __init__(
             app_version=app_version
         )
 
+
+
+    def mute(self, session_id: str, stream_id: str= "", options: dict = {}) -> requests.Response:
+        """
+        Use this method so the moderator can mute all streams or a specific stream for OpenTok.
+        Please note that a client is able to unmute themselves.
+        This function stays in the OpenTok class and inherits from the Client class.
+
+        :param session_id gets the session id from another function called get_session()
+
+        :param stream_id gets the stream id from another function called get_stream(). Note
+        that this variable is set to an empty string in the function definition as a specific
+        stream may not be chosen.
    
+        """
+        
+        try:
+            if not stream_id:
+                url = self.endpoints.get_mute_all_url(session_id)
+                data = {'excludedStream': stream_id}
+            else:
+                url = self.endpoints.get_stream_url(session_id, stream_id) + "/mute"
+                data = None
+            
+            
+            response = requests.post(url, headers=self.get_headers(), data=data)
+
+            if response:
+                return response
+            elif response.status_code == 400:
+                raise GetStreamError("Invalid request. This response may indicate that data in your request data is invalid JSON. Or it may indicate that you do not pass in a session ID or you passed in an invalid stream ID.")
+            elif response.status_code == 403:
+                raise AuthError("Failed to create session, invalid credentials")
+            elif response.status_code == 404:
+                raise NotFoundError("Mute not found")
+        except Exception as e:
+            raise OpenTokException(
+                ("There was an error thrown by the OpenTok SDK, please check that your session_id {0} and stream_id (if exists) {1} are valid").format(
+                    session_id, stream_id))
+
+    def play_dtmf(self, session_id: str, connection_id: str, digits: str, options: dict = {}) -> requests.Response:
+        """
+        Plays a DTMF string into a session or to a specific connection
+
+        :param session_id The ID of the OpenTok session that the participant being called
+        will join
+
+        :param connection_id An optional parameter used to send the DTMF tones to a specific
+        connectoiin in a session.
+
+        :param digits DTMF digits to play
+        Valid DTMF digits are 0-9, p, #, and * digits. 'p' represents a 500ms pause if a delay is
+        needed during the input process.
+
+        """
+
+        try:
+            if not connection_id:
+                url = self.endpoints.get_dtmf_all_url(session_id)
+                payload = {"digits": digits}
+            else:
+                url = self.endpoints.get_dtmf_specific_url(session_id, connection_id)
+                payload = {"digits": digits}
+
+            response = requests.post(url, headers=self.get_json_headers(), data=json.dumps(payload))
+
+            if response.status_code == 200:
+                return response
+            elif response.status_code == 400:
+                raise DTMFError("One of the properties digits, sessionId or connectionId is invalid.")
+            elif response.status_code == 403:
+                raise AuthError("Failed to create session, invalid credentials. Please check your OpenTok API Key or JSON web token")
+            elif response.status_code == 404:
+                raise NotFoundError("The session does not exists or the client specified by the connection_id is not connected to the session")
+        except Exception as e:
+            raise OpenTokException(
+                (f"There was an error thrown by the OpenTok SDK, please check that your session_id: {session_id}, connection_id (if exists): {connection_id} and digits: {digits} are valid"))
+

opentok/version.py

@@ -1,2 +1,3 @@
 # see: http://legacy.python.org/dev/peps/pep-0440/#public-version-identifiers
 __version__ = "3.2.0"
+

test_requirements.txt

@@ -4,4 +4,4 @@ expects
 wheel
 twine
 bump2version
-sure
+sure

tests/test_opentok.py

@@ -21,6 +21,8 @@ def setUp(self):
         self.api_key = "123456"
         self.api_secret = "1234567890abcdef1234567890abcdef1234567890"
         self.session_id = "SESSIONID"
+        self.connection_id = "CONNECTIONID"
+
         self.opentok = Client(self.api_key, self.api_secret)
         token = string.ascii_letters+string.digits
         self.jwt_token_string = ''.join(random.choice(token[:100]))
@@ -73,3 +75,45 @@ def test_mute_stream_response(self):
         response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
         response.headers["Content-Type"].should.equal("application/json")
 
+    @httpretty.activate
+    def test_dtmf_all_clients(self):
+        self.url = f"https://api.opentok.com/v2/project/{self.api_key}/session/{self.session_id}/play-dtmf"
+                                                                            
+        httpretty.register_uri(httpretty.POST, 
+                                        self.url, 
+                                        responses=[
+                                            httpretty.Response(body="Testing text matches inside of the JSON file", 
+                                                               content_type="application/json",
+                                                               adding_headers= {"x-opentok-auth": self.jwt_token_string},
+                                                               status=200)
+                                        ])
+
+    
+        response = requests.post(self.url)
+
+        response.status_code.should.equal(200)
+        response.text.should.equal("Testing text matches inside of the JSON file")
+        response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
+        response.headers["Content-Type"].should.equal("application/json")
+
+    @httpretty.activate
+    def test_dtmf_specific_client(self):
+        self.url = f"https://api.opentok.com/v2/project/{self.api_key}/session/{self.session_id}/connection/{self.connection_id}/play-dtmf"
+                                                                            
+        httpretty.register_uri(httpretty.POST, 
+                                        self.url, 
+                                        responses=[
+                                            httpretty.Response(body="Testing text matches inside of the JSON file", 
+                                                               content_type="application/json",
+                                                               adding_headers= {"x-opentok-auth": self.jwt_token_string},
+                                                               status=200)
+                                        ])
+
+    
+        response = requests.post(self.url)
+
+        response.status_code.should.equal(200)
+        response.text.should.equal("Testing text matches inside of the JSON file")
+        response.headers["x-opentok-auth"].should.equal(self.jwt_token_string)
+        response.headers["Content-Type"].should.equal("application/json")
+

tests/test_sip_call.py

@@ -102,6 +102,8 @@ def test_sip_call_with_aditional_options(self):
             "headers": {"headerKey": "headerValue"},
             "auth": {"username": "username", "password": "password"},
             "secure": True,
+            "observeForceMute": True,
+            "video": True
         }
 
         sip_call_response = self.opentok.dial(