voipms-api 1.0.0b9__py3-none-any.whl

tests/test_voipms_client.py

@@ -0,0 +1,17 @@
+import unittest
+from voipms_api import VoipMsClient
+
+class TestVoIPmsClient(unittest.TestCase):
+
+    def test_connection(self):
+        """
+        Tests if the credentials and IP address are correct.
+        """
+        client = VoipMsClient()
+        result = client.test_connection()
+        self.assertEqual(result["status"], "success")
+
+
+if __name__ == "__main__":
+    
+    unittest.main()

voipms_api/__init__.py

@@ -0,0 +1,25 @@
+from .accounts import Accounts
+from .call_hunting import CallHunting
+from .dids import DIDs
+from .forwarding import Forwarding
+from .general import General
+from .ivr import IVR
+from .lnp import LNP
+from .ring_groups import RingGroups
+from .sms import SMS
+from .voicemail import Voicemail
+from .voipms_client import VoipMsClient
+
+__all__ = [
+    "Accounts",
+    "CallHunting",
+    "DIDs", 
+    "Forwarding", 
+    "General",
+    "IVR", 
+    "LNP", 
+    "RingGroups",
+    "SMS", 
+    "Voicemail", 
+    "VoipMsClient"
+]

voipms_api/accounts.py

@@ -0,0 +1,161 @@
+import requests
+from typing import Optional, Union
+
+
+class Accounts():
+    '''
+    A class to call the Sub Accounts functions of the VoIP.ms API.
+
+    Methods:
+        create_subaccount:
+            Creates a Sub Account and returns the result of the request.
+    '''
+
+    def __init__(self, username=None, password=None) -> None:
+
+        from voipms_api import VoipMsClient
+        
+        if (username and not password) or (password and not username):
+            raise ValueError("Both username and password must be provided together")
+        elif(username and password):
+            self.username = username
+            self.password = password
+            self.vms_client = VoipMsClient(self.username, self.password)
+        else:
+            self.vms_client = VoipMsClient()
+
+    
+    def create_subaccount(self, 
+            username:str,
+            password:str,
+            extension:Optional[Union[str, int]]=None,
+            protocol:Optional[Union[str, int]]=1,
+            auth_type:Optional[Union[str, int]]=1,
+            device_type:Optional[Union[str, int]]=2,
+        ) -> dict:
+        """
+        Calls the VoIP.ms createSubAccount function.
+
+        Args:
+            username (str, required): Username to set to the sub account (Example: 'VoIP').
+            password (str, required): Password to set for the authentication.
+            extension str or int, optional): Sub Account Internal Extension (Example: 1 -> Creates 101).
+            protocol (str or int, optional): The protocol the sub account will use. Default is '1' for SIP (value from get_Protocols).
+            auth_type (str or int, optional): The authentication type the sub account will use. Default is '1' for User/Password (value from get_auth_types).
+            device_type (str or int, optional): Device type that will be used. Default is '2' for ATA device, IP Phone or Softphone (value from get_device_types).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Account that was created.
+        """
+        
+        mtd = "createSubAccount"
+
+        try:
+            params = {
+
+                # Required by this package.
+                "username": username,
+                "password": password,
+
+                # Required by the VoIP.ms API but set with default values in this package.
+                "lock_international": 1,
+                "international_route": 1,
+                "music_on_hold": "default",
+                "allowed_codecs": "g722",
+                "dtmf_mode": "auto",
+                "nat": "yes",
+            }
+
+            # Optional parameters in this package.
+            if protocol:
+                params["protocol"] = protocol
+            if auth_type:
+                params["auth_type"] = auth_type
+            if device_type:
+                params["device_type"] = device_type
+            if extension:
+                params["internal_extension"] = extension
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def delete_subaccount(self, 
+            id:Union[str, int],
+        ) -> dict:
+        """
+        Calls the VoIP.ms delSubAccount function.
+
+        Args:
+            id (str or int, required): ID of the Sub Account that will be deleted(Example: '99785' or 99785). Value from get_subaccounts.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Account that was canceled.
+        """
+        
+        mtd = "delSubAccount"
+
+        try:
+            params = {
+                "id": id,
+            }
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["result"] = "Sub Account deleted"
+            data["id"] = id
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def get_subaccounts(self, 
+            subaccount:Optional[Union[str, int]]=None
+        ) -> dict:
+        """
+        Calls the VoIP.ms getSubAccounts function.
+
+        Args:
+            subaccount (str or int, optional): Sub Account ID or username (Example: '100000_SubAccount' or 99785).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the Sub Accounts and their data, or a specific Sub Account data if an ID or username is provided.
+        """
+        
+        mtd = "getSubAccounts"
+
+        try:
+            params = {}
+
+            if subaccount:
+                params["account"] = subaccount
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None

voipms_api/call_hunting.py

@@ -0,0 +1,173 @@
+import requests
+from typing import Optional, Union
+
+class CallHunting():
+    '''
+    A class to call the Call Hunting functions of the VoIP.ms API.
+
+    Methods:
+        create_call_hunting:
+            Creates a new Call Hunting and returns the result of the request.
+        delete_call_hunting:
+            Deletes a specific Call Hunting and returns the result of the request.
+        get_call_hunting:
+            Returns all the existing Call Huntings, or a specific Call Hunting if a Call Hunting ID is provided.
+    '''
+
+    def __init__(self, username=None, password=None) -> None:
+
+        from voipms_api import Accounts, VoipMsClient
+        
+        if (username and not password) or (password and not username):
+            raise ValueError("Both username and password must be provided together")
+        elif(username and password):
+            self.username = username
+            self.password = password
+            self.vms_client = VoipMsClient(self.username, self.password)
+        else:
+            self.vms_client = VoipMsClient()
+
+        # Code to get the Account number to set the Main Account as the default member so it is not required.
+        accounts = Accounts()
+        get_accounts = accounts.get_subaccounts()
+        self.acc_number = get_accounts['accounts'][0]['account']
+        self.acc_number = self.acc_number[0:6]
+
+
+    def create_call_hunting(self, 
+            name:str,
+            recording:Optional[Union[str, int]]=None,
+            language:Optional[str]=None,
+            order:Optional[str]=None,
+            members:Optional[str]=None,
+        ) -> dict:
+        """
+        Calls the VoIP.ms setCallHunting function to create a new Call Hunting.
+
+        Args:
+            name (str, required): A name for the new Call Hunting.
+            recording (str or int, optional): ID of the recording to set to the Call Hunting. Values from get_recordings.
+            language (str, optional): Language of the Call Hunting. Default  is 'en' for English. Values from get_languages.
+            order (str, optional): Ring order of the Call Hunting. Default  is 'follow' to follow member's order. Alternative is 'random'.
+            members (srt, optional): A string of members separated by semicolons. Default is Main Account as only member. (Example: 'account:100001;fwd:16006'). See VoIP.ms API documentation for more details.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the name of the Call Hunting that was created.
+        """
+        
+        mtd = "setCallHunting"
+        main_account = "account:" + self.acc_number
+
+        try:
+            params = {
+                # Required by this package
+                "description": name,
+
+                # Required by VoIP.ms API but set with default values so it is not required in this package.
+                "music": "default",
+                "recording": "default",
+                "language": "en",
+                "order": "follow",
+                "members": main_account,
+                "ring_time": 25,
+                "press": 0
+            }
+
+            # Optional in this package.
+            if recording:
+                params["recording"] = recording
+            if language:
+                params["language"] = language
+            if order:
+                params["order"] = order
+            if members:
+                params["members"] = members
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["name"] = name
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def delete_call_hunting(self, 
+            call_hunting:Union[str, int],
+        ) -> dict:
+        """
+        Calls the VoIP.ms delCallHunting function.
+
+        Args:
+            call_hunting (str or int, required): ID of the call hunting that will be deleted (Example: 18635). Value from get_call_huntings.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the ID of the call hunting that was deleted.
+        """
+        
+        mtd = "delCallHunting"
+
+        try:
+            params = {
+                "callhunting": call_hunting,
+            }
+
+            # Code to get the name of the call hunting that is deleted.
+            ch_info = self.get_call_huntings(call_hunting)
+            ch_name = ch_info["call_hunting"][0]["description"]
+
+            data = self.vms_client.make_request(mtd, params)
+            data["call_hunting"] = ch_name
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def get_call_huntings(self, 
+            call_hunting:Optional[Union[str, int]]=None,
+        ) -> dict:
+        """
+        Calls the VoIP.ms getCallHuntings function.
+
+        Args:
+            call_hunting (str or int, optional): ID of a specific call hunting (Example: 323).
+
+        Returns:
+            dict: A dictionary containing the status of the request and the data of all the call huntings, or the data of a specific call hunting if an ID is provided.
+        """
+        
+        mtd = "getCallHuntings"
+
+        try:
+            params = {}
+
+            # Optional in this package.
+            if call_hunting:
+                params["callhunting"] = call_hunting
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None

voipms_api/dids.py

@@ -0,0 +1,222 @@
+'''
+VoIP.ms DIDs functions
+'''
+
+import requests
+from typing import Optional, Union
+
+
+class DIDs():
+    '''
+    A class to call the DID functions of the VoIP.ms API.
+
+    Methods:
+        cancel_did:
+            Cancels a specific DID number and returns the result of the request.
+        get_dids_info:
+            Returns the current balance of the VoIP.ms account.
+    '''
+
+    def __init__(self, username=None, password=None) -> None:
+
+        from voipms_api import VoipMsClient
+        
+        if (username and not password) or (password and not username):
+            raise ValueError("Both username and password must be provided together")
+        elif(username and password):
+            self.username = username
+            self.password = password
+            self.vms_client = VoipMsClient(self.username, self.password)
+        else:
+            self.vms_client = VoipMsClient()
+
+    
+    def cancel_did(self, 
+            did:Union[str, int],
+            comment:Optional[str]=None,
+            port_out:Optional[Union[str, bool]]=None,
+            test:Optional[Union[str, bool]]=None
+        ) -> dict:
+        """
+        Calls the VoIP.ms cancelDID function.
+
+        Args:
+            did (str or int, required): Specific DID number to be canceled (Example: 5551234567).
+            comment (str, optional): Comment for DID cancellation.
+            port out (str or bool, optional): Set True if the DID was ported out.
+            test (str or bool, optional): Set True if testing the DID cancelation function.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the DID that was canceled.
+        """
+        
+        mtd = "cancelDID"
+
+        try:
+            params = {
+                "did": did,
+            }
+
+            if comment:
+                params["comment"] = comment
+            if port_out:
+                params["portout"] = port_out
+            if test:
+                params["test"] = test
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["result"] = "DID canceled"
+            data["did"] = did
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+
+
+    def get_dids_info(self, 
+            client:Optional[Union[str, int]]=None, 
+            did:Optional[Union[str, int]]=None
+        ) -> dict:
+        """
+        Calls the VoIP.ms getDIDsInfo function.
+
+        Args:
+            client (str or int, optional): ID of a specific Reseller client or Sub Account (Example: 123456 or 100000_Account).
+            did (str or int, optional): Specific DID number or Sub Account (Example: 5551234567).   
+
+        Returns:
+            dict:   If no parameter is provided, a dictionary containing the status and information from all the DIDs.
+                    If a client ID is provided, a dictionary containing the status and information from the client's DIDs.
+                    If a Sub Account is provided, a dictionary containing the status and information of the Sub Account's DID.
+                    If a DID is provided, a dictionary containing the status and information of the specific DID.
+        """
+        
+        mtd = "getDIDsInfo"
+
+        try:
+            params = {}
+
+            if client:
+                params["client"] = client
+            if did:
+                params["did"] = did
+            
+            data = self.vms_client.make_request(mtd, params)
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+        
+    def order_did(self,
+        did: Union[str, int],
+        routing: Optional[str]="sys:hangup",
+        pop:Optional[Union[str, int]]=22,
+        dial_time:Optional[Union[str, int]]=60,
+        cnam:Optional[Union[str, int]]=0,
+        billing_type: Optional[Union[str, int]]=1
+        )-> dict:
+        """
+        Calls the VoIP.ms orderDID function.
+
+        Args:
+            did (str or int, required): Specific DID number to be ordered (Example: 5551234567).
+            routing (str, optional): Routing of the DID. Default is sys:hangup.
+            pop (str or int, optional): POP server of the DID. Default is 22 (sanjose1.voip.ms). Data from get_severs.
+            dial time (str or int, optional): Ring time of the DID. Default is 60 (seconds).
+            cnam: (str or int, optional): Activates CNAM lookup. Default is 0 (disabled). Set 1 for enable.
+            billing type (str or int, optional): Sets the Billing plan. Default is 1 (Per Minute). Set 2 for Flat Rate.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the DID that was ordered.
+        """
+        
+        mtd = "orderDID"
+
+        try:
+            params = {
+                "did": did,
+                "routing": routing,
+                "pop": pop,
+                "dialtime": dial_time,
+                "cnam": cnam,
+                "billing_type": billing_type,
+            }
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["result"] = "DID ordered"
+            data["did"] = did
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None
+        
+
+    def order_toll_free(self,
+        did: Union[str, int],
+        routing: Optional[str]="sys:hangup",
+        pop:Optional[Union[str, int]]=22,
+        dial_time:Optional[Union[str, int]]=60,
+        cnam:Optional[Union[str, int]]=0
+        )-> dict:
+        """
+        Calls the VoIP.ms orderTollFree function.
+
+        Args:
+            did (str or int, required): Specific Toll-free DID number to be ordered (Example: 8771234567).
+            routing (str, optional): Routing of the DID. Default is sys:hangup.
+            pop (str or int, optional): POP server of the DID. Default is 22 (sanjose1.voip.ms). Data from get_severs.
+            dial time (str or int, optional): Ring time of the DID. Default is 60 (seconds).
+            cnam: (str or int, optional): Activates CNAM lookup. Default is 0 (disabled). Set 1 for enable.
+            billing type (str or int, optional): Sets the Billing plan. Default is 1 (Per Minute). Set 2 for Flat Rate.
+
+        Returns:
+            dict: A dictionary containing the status of the request and the DID that was ordered.
+        """
+        
+        mtd = "orderTollFree"
+
+        try:
+            params = {
+                "did": did,
+                "routing": routing,
+                "pop": pop,
+                "dialtime": dial_time,
+                "cnam": cnam
+            }
+            
+            data = self.vms_client.make_request(mtd, params)
+            data["result"] = "DID ordered"
+            data["did"] = did
+            return data
+        
+        except requests.exceptions.HTTPError as http_err:
+            print(f"HTTP error ocurred: {http_err}")
+            return None
+        except KeyError as key_err:
+            print(f"Key error: {key_err}")
+            return None
+        except Exception as err:
+            print(f'An error occurred: {err}')
+            return None