add method for creating call

Author: Stefan Rogin

examples/call.py

@@ -1,46 +1,42 @@
 #!/usr/bin/env python
 
-import sys, os 
+import os
+import sys
+
 sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
 
 import messagebird
 
-#ACCESS_KEY = ''
-#CALL_ID = ''
+# ACCESS_KEY = ''
+# CALL_ID = ''
 
 try:
-  ACCESS_KEY
+    ACCESS_KEY
 except NameError:
-  print('You need to set an ACCESS_KEY constant in this file')
-  sys.exit(1)
+    print('You need to set an ACCESS_KEY constant in this file')
+    sys.exit(1)
 
 try:
-  CALL_ID
+    CALL_ID
 except NameError:
-  print('You need to set a CALL_ID constant in this file')
-  sys.exit(1)
+    print('You need to set a CALL_ID constant in this file')
+    sys.exit(1)
 
 try:
-  # Create a MessageBird client with the specified ACCESS_KEY.
-  client = messagebird.Client(ACCESS_KEY)
-
-  # Fetch the Message object for the specified MESSAGE_ID.
-  call = client.call(CALL_ID)
-
-  # Print the object information.
-  print('\nThe following information was returned as a Message object:\n')
-  print('  id                : %s' % call.data.id)
-  print('  status            : %s' % call.data.status)
-  print('  source            : %s' % call.data.source)
-  print('  destination       : %s' % call.data.destination)
-  print('  createdAt         : %s' % call.data.createdAt)
-  print('  updatedAt         : %s' % call.data.updatedAt)
-  print('  endedAt           : %s' % call.data.endedAt)
-  
+    # Create a MessageBird client with the specified ACCESS_KEY.
+    client = messagebird.Client(ACCESS_KEY)
+
+    # Fetch the Call object for the specified CALL_ID.
+    call = client.call(CALL_ID)
+
+    # Print the object information.
+    print('\nThe following information was returned as a', str(call.__class__), 'object:\n')
+    print('  '.join(str(call).splitlines(True)))
+
 except messagebird.client.ErrorException as e:
-  print('\nAn error occured while requesting a Message object:\n')
+    print('\nAn error occurred while requesting a Message object:\n')
 
-  for error in e.errors:
-    print('  code        : %d' % error.code)
-    print('  description : %s' % error.description)
-    print('  parameter   : %s\n' % error.parameter)
+    for error in e.errors:
+        print('  code        : %d' % error.code)
+        print('  description : %s' % error.description)
+        print('  parameter   : %s\n' % error.parameter)

examples/call_create.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python
+import os
+import sys
+import json
+import argparse
+import requests
+
+sys.path.append(os.path.join(os.path.dirname(__file__), '..'))
+import messagebird
+
+exampleCallFlow = '{"title":"Test Flow","steps":[{"action":"say","options":{"payload":"Hey, this is your first voice \
+call","language":"en-GB","voice":"female"}}]}'
+
+parser = argparse.ArgumentParser(usage='call_create.py\
+ --accessKey="*******" \
+ --destination=31612345678 \
+ --source=31644556677 \
+ --callFlow \'' + exampleCallFlow + '\'\
+')
+parser.add_argument('--accessKey', help='access key for MessageBird API', type=str, required=True)
+parser.add_argument('--source', help='The caller ID of the call.', type=str, required=True)
+parser.add_argument('--destination', help='The number/address to be called.', type=str, required=True)
+parser.add_argument('--callFlow', help='The call flow object to be executed when the call is answered.', type=str, required=False, default=exampleCallFlow)
+parser.add_argument('--webhook', help='The webhook object containing the url & required token.', type=str, required=False, default='{}')
+args = vars(parser.parse_args())
+
+# arguments to parse as json
+jsonArgs = ['callFlow', 'webhook']
+
+print()
+for jsonArg in jsonArgs:
+    try:
+        args[jsonArg] = json.loads(str(args[jsonArg]).strip('\''))
+    except json.decoder.JSONDecodeError as e:
+        parser.print_usage()
+        print('Invalid json provided for', jsonArg, ':', e)
+        print('Provided', jsonArg, 'json:', args[jsonArg])
+        exit(1)
+
+try:
+    # Create a MessageBird client with the specified accessKey.
+    client = messagebird.Client(args['accessKey'])
+    del(args['accessKey'])
+
+    # Create a call for the specified callID.
+    call = client.call_create(**args)
+
+    # Print the object information.
+    print('\nThe following information was returned as a', str(call.__class__), 'object:\n')
+
+except messagebird.client.ErrorException as e:
+    print('\nAn error occurred while creating a call:\n')
+
+    for error in e.errors:
+        print('  code        : %d' % error.code)
+        print('  description : %s' % error.description)
+        print('  parameter   : %s' % error.parameter)
+        print('  type        : %s' % error.__class__)
+
+except requests.exceptions.HTTPError as e:
+    print('\nAn http exception occurred while creating a call:')
+    print(' ', e)
+    print('  Http request body: ', e.request.body)
+    print('  Http response status: ', e.response.status_code)
+    print('  Http response body: ', e.response.content.decode())
+
+except Exception as e:
+    print('\nAn ', e.__class__, ' exception occurred while creating a call:')
+    print(e)
+

messagebird/call.py

@@ -19,3 +19,9 @@ def data(self):
     @data.setter
     def data(self, value):
         self._data = CallData().load(value[0])
+
+    def __str__(self):
+        return "\n".join([
+            'id                 : %s' % self.id,
+            'data.'+'data.'.join(str(self._data).splitlines(True)),
+        ])

messagebird/call_data.py

@@ -45,3 +45,12 @@ def webhook(self):
     @webhook.setter
     def webhook(self, value):
         self._webhook = Webhook.load(value)
+
+    def __str__(self):
+        return "\n".join([
+            'id                 : %s' % self.id,
+            'updatedAt          : %s' % self.updatedAt,
+            'createdAt          : %s' % self.createdAt,
+            'endedAt            : %s' % self.endedAt,
+            'webhook            : %s' % self.webhook,
+        ])

messagebird/client.py

@@ -124,6 +124,25 @@ def call(self,id):
         """Retrieve the information of a specific call"""
         return Call().load(self.request('calls/' + str(id), 'GET', None, VOICE_TYPE))
 
+    def call_create(self, source, destination, callFlow, webhook):
+        """Creating a call
+
+        Args:
+            source(str)             : The caller ID of the call.
+            destination(string)     : The number/address to be called.
+            callFlow(object)        : The call flow object to be executed when the call is answered.
+            webhook(object)         : The webhook object containing the url & required token.
+        Raises:
+            ErrorException:         On api returning errors
+
+        Returns:
+            If successful, this request will return an object with a data property, which is an array that has a single
+            call object. If the request failed, an error object will be returned."""
+
+        params = locals()
+        del(params['self'])
+        return Call().load(self.request('calls', 'POST', params, VOICE_TYPE))
+
     def hlr(self, id):
         """Retrieve the information of a specific HLR lookup."""
         return HLR().load(self.request('hlr/' + str(id)))
@@ -155,11 +174,11 @@ def message_delete(self, id):
         self.request_plain_text('messages/' + str(id), 'DELETE')
 
     def mms_create(self, originator, recipients, body, mediaUrls, subject = None, reference = None, scheduledDatetime = None):
-        ''' Send bulk mms.
+        """ Send bulk mms.
 
         Args:
             originator(str): name of the originator
-            recipients(str/list(str)): comma seperated numbers or list of numbers in E164 format
+            recipients(str/list(str)): comma separated numbers or list of numbers in E164 format
             body(str)       : text message body
             mediaUrl(str)   : list of URL's of attachments of the MMS message.
             subject(str)    : utf-encoded subject
@@ -169,8 +188,8 @@ def mms_create(self, originator, recipients, body, mediaUrls, subject = None, re
             ErrorException:  On api returning errors
 
         Returns:
-            MMS: On success an MMS instance instantiated with succcess response
-        '''
+            MMS: On success an MMS instance instantiated with success response
+        """
         if isinstance(recipients,list):
             recipients = ','.join(recipients)
         if isinstance(mediaUrls,str):

tests/test_call.py

@@ -1,5 +1,7 @@
+import json
 import unittest
 from messagebird import Client, ErrorException
+from messagebird.base import Base
 
 try:
     from unittest.mock import Mock
@@ -13,10 +15,111 @@ class TestCall(unittest.TestCase):
 
     def test_call(self):
         http_client = Mock()
-        http_client.request.return_value = '{"data":[{"id":"call-id","status":"ended","source":"16479311111","destination":"1416555555","createdAt":"2019-08-06T13:17:06Z","updatedAt":"2019-08-06T13:17:39Z","endedAt":"2019-08-06T13:17:39Z"}],"_links":{"legs":"/calls/66bd9f08-a8af-40fe-a830-652d8dabc057/legs","self":"/calls/66bd9f08-a8af-40fe-a830-652d8bca357"},"pagination":{"totalCount":0,"pageCount":0,"currentPage":0,"perPage":0}}'
+        http_client.request.return_value = """
+            {
+               "data":[
+                  {
+                     "id":"call-id",
+                     "status":"ended",
+                     "source":"16479311111",
+                     "destination":"1416555555",
+                     "createdAt":"2019-08-06T13:17:06Z",
+                     "updatedAt":"2019-08-06T13:17:39Z",
+                     "endedAt":"2019-08-06T13:17:39Z"
+                  }
+               ],
+               "_links":{
+                  "legs":"/calls/66bd9f08-a8af-40fe-a830-652d8dabc057/legs",
+                  "self":"/calls/66bd9f08-a8af-40fe-a830-652d8bca357"
+               },
+               "pagination":{
+                  "totalCount":0,
+                  "pageCount":0,
+                  "currentPage":0,
+                  "perPage":0
+               }
+            }
+            """
 
         call = Client('', http_client).call('call-id')
 
         http_client.request.assert_called_once_with('calls/call-id', 'GET', None)
 
-        self.assertEqual('ended', call.data.status)
+        self.assertEqual('ended', call.data.status)
+
+    def test_call_create(self):
+        api_response = {
+            "data": [
+                {
+                    "id": "21025ed1-cc1d-4554-ac05-043fa6c84e00",
+                    "status": "queued",
+                    "source": "31644556677",
+                    "destination": "31612345678",
+                    "createdAt": "2017-08-30T07:35:37Z",
+                    "updatedAt": "2017-08-30T07:35:37Z",
+                    "endedAt": None
+                }
+            ],
+            "_links": {
+                "self": "/calls/21025ed1-cc1d-4554-ac05-043fa6c84e00"
+            }
+        }
+
+        params = {
+            "source": "31644556677",
+            "destination": "31612345678",
+            "callFlow": {
+                "title": "Say message",
+                "steps": [
+                    {
+                        "action": "say",
+                        "options": {
+                            "payload": "This is a journey into sound. Good bye!",
+                            "voice": "male",
+                            "language": "en-US"
+                        }
+                    }
+                ]
+            },
+            "webhook": {
+                "url": "https://example.com",
+                "token": "token_to_sign_the_call_events_with",
+            }
+        }
+
+        http_client = Mock()
+        http_client.request.return_value = json.dumps(api_response)
+
+        call_creation_response = Client('', http_client).call_create(**params)
+
+        http_client.request.assert_called_once_with('calls', 'POST', params)
+
+        # check all api response data is outputted
+        expected_data = self.create_expected_call_data_based_on_api_response(api_response)
+        response_data = call_creation_response.data.__dict__
+        self.assertEqual(expected_data, response_data, 'Check client response contains the api response data.')
+
+        # check it can be formatted as string
+        expected_call_string = 'id                 : None\n' + \
+            'data.id                 : 21025ed1-cc1d-4554-ac05-043fa6c84e00\n' + \
+            'data.updatedAt          : 2017-08-30 07:35:37+00:00\n' + \
+            'data.createdAt          : 2017-08-30 07:35:37+00:00\n' + \
+            'data.endedAt            : None\n' + \
+            'data.webhook            : None'
+        self.assertEqual(expected_call_string, str(call_creation_response), 'Check returned call can be formatted as' +
+                         'string')
+
+    @staticmethod
+    def create_expected_call_data_based_on_api_response(api_response):
+        expected_data = api_response['data'][0]
+
+        # convert dates
+        expected_data['_createdAt'] = Base.value_to_time(expected_data['createdAt'], '%Y-%m-%dT%H:%M:%SZ')
+        expected_data['_updatedAt'] = Base.value_to_time(expected_data['updatedAt'], '%Y-%m-%dT%H:%M:%SZ')
+        expected_data['_endedAt'] = Base.value_to_time(expected_data['endedAt'], '%Y-%m-%dT%H:%M:%SZ')
+        del (expected_data['createdAt'], expected_data['updatedAt'], expected_data['endedAt'])
+
+        # add generated data
+        expected_data.setdefault('_webhook', None)
+
+        return expected_data