Add SIP Outbound video Flag and PlayDTMF function with API endpoints (#194)

* Adding the ObserveForceMute flag

* Removed 3.5 from the build and fixed extra space in opentok.py

* Add SIP Outbound video flag and Play DTMF API

* Change wording in docstring for force mute

Author: geekchick

opentok/endpoints.py

@@ -142,4 +142,28 @@ def get_mute_all_url(self, session_id):
             + 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"
         )

opentok/exceptions.py

@@ -88,3 +88,9 @@ class BroadcastError(OpenTokException):
     """
 
     pass
+
+class DTMFError(OpenTokException):
+    """
+    Indicates that one of the properties digits, session_id or connection_id is invalid
+    """
+    pass

opentok/opentok.py

@@ -42,6 +42,7 @@
     SipDialError,
     SetStreamClassError,
     BroadcastError,
+    DTMFError
 )
 
 
@@ -1006,8 +1007,14 @@ def dial(self, session_id, token, sip_uri, options=[]):
             encrypted (true) or not (false, the default)
 
             Boolean 'observeForceMute': A Boolean flag that determines whether the SIP endpoint should 
-            honor the force mute action. 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.
+            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:
 
@@ -1025,7 +1032,8 @@ def dial(self, session_id, token, sip_uri, options=[]):
                         "password": "password"
                     },
                         "secure": true|false,
-                        "observeForceMute": true|false
+                        "observeForceMute": true|false,
+                        "video": true|false
                     }
                 }
 
@@ -1042,6 +1050,7 @@ def dial(self, session_id, token, sip_uri, options=[]):
         """
         payload = {"sessionId": session_id, "token": token, "sip": {"uri": sip_uri}}
         observeForceMute = False
+        video = False
 
         if "from" in options:
             payload["sip"]["from"] = options["from"]
@@ -1058,6 +1067,10 @@ def dial(self, session_id, token, sip_uri, options=[]):
         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()
 
@@ -1447,3 +1460,41 @@ def mute(self, session_id: str, stream_id: str= "", options: dict = {}) -> reque
                 ("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"))
+

tests/test_opentok.py

@@ -21,6 +21,7 @@ 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 +74,46 @@ 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,7 +102,8 @@ def test_sip_call_with_aditional_options(self):
             "headers": {"headerKey": "headerValue"},
             "auth": {"username": "username", "password": "password"},
             "secure": True,
-            "observeForceMute": True
+            "observeForceMute": True,
+            "video": True
         }
 
         sip_call_response = self.opentok.dial(