Merge pull request #215 from maxkahan/2.x

Adding Messages API support

Author: maxkahan

CHANGES.md

@@ -1,3 +1,6 @@
+# 2.8.0
+- Added Messages API v1.0 support. Messages API can now be used by calling the client.messages.send_message() method.
+
 # 2.7.0
 - Moved some client methods into their own classes: `account.py, application.py, 
 message_search.py, number_insight.py, numbers.py, short_codes.py, ussd.py`

README.md

@@ -14,6 +14,7 @@ need a Vonage account. Sign up [for free at vonage.com][signup].
 - [Installation](#installation)
 - [Usage](#usage)
 - [SMS API](#sms-api)
+- [Messages API](#messages-api)
 - [Voice API](#voice-api)
 - [Verify API](#verify-api)
 - [Number Insight API](#number-insight-api)
@@ -68,6 +69,8 @@ To check signatures for incoming webhook requests, you'll also need
 to specify the `signature_secret` argument (or the `VONAGE_SIGNATURE_SECRET`
 environment variable).
 
+To use the SDK to call Vonage APIs, pass in dicts with the required options to methods like `Sms.send_message()`. Examples of this are given below.
+
 ## Simplified structure for calling API Methods
 
 The client now instantiates a class object for each API when it is created, e.g. `vonage.Client(key="mykey", secret="mysecret")`
@@ -93,6 +96,7 @@ client.CLASS_NAME.CLASS_METHOD
 
 ## SMS API
 
+Although the Messages API adds more messaging channels, the SMS API is still supported.
 ### Send an SMS
 
 ```python
@@ -138,6 +142,82 @@ response = client.sms.send_message({
 client.sms.submit_sms_conversion(response['message-id'])
 ```
 
+## Messages API
+
+The Messages API is an API that allows you to send messages via SMS, MMS, WhatsApp, Messenger and Viber. Call the API from your Python code by 
+passing a dict of parameters into the `client.messages.send_message()` method.
+
+It accepts JWT or API key/secret authentication.
+
+Some basic samples are below. For more detailed information and code snippets, please visit the [Vonage Developer Documentation](https://developer.vonage.com).
+
+### Send an SMS
+```python
+responseData = client.messages.send_message({
+        'channel': 'sms', 
+        'message_type': 'text', 
+        'to': '447123456789', 
+        'from': 'Vonage',
+        'text': 'Hello from Vonage'
+    })
+```
+
+### Send an MMS
+Note: only available in the US. You will need a 10DLC number to send an MMS message.
+
+```python
+client.messages.send_message({
+        'channel': 'mms', 
+        'message_type': 'image', 
+        'to': '11112223333', 
+        'from': '1223345567',
+        'image': {'url': 'https://example.com/image.jpg', 'caption': 'Test Image'}
+    })
+```
+
+### Send an audio file via WhatsApp
+
+You will need a WhatsApp Business Account to use WhatsApp messaging. WhatsApp restrictions mean that you
+must send a template message to a user if they have not previously messaged you, but you can send any message
+type to a user if they have messaged your business number in the last 24 hours.
+
+```python
+client.messages.send_message({
+        'channel': 'whatsapp', 
+        'message_type': 'audio', 
+        'to': '447123456789', 
+        'from': '440123456789',
+        'audio': {'url': 'https://example.com/audio.mp3'}
+    })
+```
+
+### Send a video file via Facebook Messenger
+
+You will need to link your Facebook business page to your Vonage account in the Vonage developer dashboard. (Click on the sidebar
+"External Accounts" option to do this.)
+
+```python
+client.messages.send_message({
+        'channel': 'messenger', 
+        'message_type': 'video', 
+        'to': '594123123123123', 
+        'from': '1012312312312',
+        'video': {'url': 'https://example.com/video.mp4'}
+    })
+```
+
+### Send a text message with Viber
+
+```python
+client.messages.send_message({
+    'channel': 'viber_service',
+    'message_type': 'text',
+    'to': '447123456789',
+    'from': '440123456789',
+    'text': 'Hello from Vonage!'
+})
+```
+
 ## Voice API
 
 ### Make a call
@@ -247,6 +327,7 @@ client.voice.send_dtmf(response['uuid'], digits='1234')
 response = client.get_recording(RECORDING_URL)
 ```
 
+
 ## Verify API
 
 ### Search for a Verification request
@@ -509,12 +590,6 @@ client.api_host('myapi.vonage.com') # rewrite the value of api_host
 
 ## Frequently Asked Questions
 
-### Dropping support for Python 2.7
-
-Back in 2014 when Guido van Rossum, Python's creator and principal author, made the announcement, January 1, 2020 seemed pretty far away. Python 2.7’s sunset has happened, after which there’ll be absolutely no more support from the core Python team. Many utilized projects pledge to drop Python 2 support in or before 2020. [(Official statement here)](https://www.python.org/doc/sunset-python-2/).
-
-Just because 2.7 isn’t going to be maintained past 2020 doesn’t mean your applications or libraries suddenly stop working but as of this moment we won't give official support for upcoming releases. Please read the official ["Porting Python 2 Code to Python 3" guide](https://docs.python.org/3/howto/pyporting.html). Please also read the [Python 3 Statement Practicalities](https://python3statement.org/practicalities/) for advice on sunsetting your Python 2 code.
-
 ### Supported APIs
 
 The following is a list of Vonage APIs and whether the Python SDK provides support for them:
@@ -529,7 +604,7 @@ The following is a list of Vonage APIs and whether the Python SDK provides suppo
 | Dispatch API          |         Beta         |     ❌     |
 | External Accounts API |         Beta         |     ❌     |
 | Media API             |         Beta         |     ❌     |
-| Messages API          |         Beta         |     ❌     |
+| Messages API          | General Availability |     ✅     |
 | Number Insight API    | General Availability |     ✅     |
 | Number Management API | General Availability |     ✅     |
 | Pricing API           | General Availability |     ✅     |

src/vonage/__init__.py

@@ -1,7 +1,3 @@
 from .client import *
-from .errors import *
-from .voice import *
-from .sms import *
-from .verify import *
 
 __version__ = "2.7.0"

src/vonage/client.py

@@ -1,15 +1,18 @@
+import vonage
+
 from ._internal import _format_date_param
-from .account import *
+from .account import Account
 from .application import ApplicationV2, BasicAuthenticatedServer
 from .errors import *
-from .message_search import *
+from .message_search import MessageSearch
+from .messages import Messages
 from .number_insight import NumberInsight
-from .numbers import *
-from .short_codes import *
-from .sms import *
-from .ussd import *
-from .voice import *
-from .verify import *
+from .numbers import Numbers
+from .short_codes import ShortCodes
+from .sms import Sms
+from .ussd import Ussd
+from .voice import Voice
+from .verify import Verify
 
 import logging
 from datetime import datetime
@@ -129,9 +132,10 @@ def __init__(
             api_secret=self.api_secret,
         )
         self.application_v2 = ApplicationV2(api_server)
-
+        
         self.account = Account(self)
         self.message_search = MessageSearch(self)
+        self.messages = Messages(self)
         self.number_insight = NumberInsight(self)
         self.numbers = Numbers(self)
         self.short_codes = ShortCodes(self)
@@ -234,6 +238,7 @@ def post(
         params,
         supports_signature_auth=False,
         header_auth=False,
+        additional_headers=None
     ):
         """
         Low-level method to make a post request to a Vonage API server, which may have a Nexmo url.
@@ -245,7 +250,12 @@ def post(
         :param bool header_auth: Use basic authentication instead of adding api_key and api_secret to the request params.
         """
         uri = f"https://{host}{request_uri}"
-        headers = self.headers
+        
+        if not additional_headers:
+            headers = {**self.headers}
+        else:
+            headers = {**self.headers, **additional_headers}
+
         if supports_signature_auth and self.signature_secret:
             params["api_key"] = self.api_key
             params["sig"] = self.signature(params)

src/vonage/errors.py

@@ -17,4 +17,9 @@ class AuthenticationError(ClientError):
 class CallbackRequiredError(Error):
     """
     Indicates a callback is required but was not present.
-    """
+    """
+
+class MessagesError(Error):
+    """
+    Indicates an error related to the Messages class which calls the Vonage Messages API.
+    """

src/vonage/messages.py

@@ -0,0 +1,88 @@
+from .errors import MessagesError
+
+import re
+import json
+
+class Messages:
+    valid_message_channels = {'sms', 'mms', 'whatsapp', 'messenger', 'viber_service'}
+    valid_message_types = {
+        'sms': {'text'},
+        'mms': {'image', 'vcard', 'audio', 'video'},
+        'whatsapp': {'text', 'image', 'audio', 'video', 'file', 'template', 'custom'},
+        'messenger': {'text', 'image', 'audio', 'video', 'file'},
+        'viber_service': {'text', 'image'}
+    }
+    
+    def __init__(self, client):
+        self._client = client
+
+    def send_message(self, params: dict, header_auth=False):        
+        self.validate_send_message_input(params)
+
+        json_formatted_params = json.dumps(params)
+        if header_auth: # Using base64 encoded API key/secret pair
+            return self._client.post(
+                self._client.api_host(), 
+                "/v1/messages",
+                json_formatted_params, 
+                header_auth=header_auth,
+                additional_headers={'Content-Type': 'application/json'})
+        else: # If using jwt auth
+            return self._client._jwt_signed_post(
+                "/v1/messages",
+                params)
+
+    def validate_send_message_input(self, params):
+        self._check_input_is_dict(params)
+        self._check_valid_message_channel(params)
+        self._check_valid_message_type(params)
+        self._check_valid_recipient(params)
+        self._check_valid_sender(params)
+        self._channel_specific_checks(params)
+        self._check_valid_client_ref(params)
+    
+    def _check_input_is_dict(self, params):
+        if type(params) is not dict:
+            raise MessagesError(f'Parameters to the send_message method must be specified as a dictionary.')
+
+    def _check_valid_message_channel(self, params):
+        if params['channel'] not in Messages.valid_message_channels:
+            raise MessagesError(f"""
+            '{params['channel']}' is an invalid message channel. 
+            Must be one of the following types: {self.valid_message_channels}'
+            """)
+
+    def _check_valid_message_type(self, params):
+        if params['message_type'] not in self.valid_message_types[params['channel']]:
+            raise MessagesError(f"""
+                "{params['message_type']}" is not a valid message type for channel "{params["channel"]}". 
+                Must be one of the following types: {self.valid_message_types[params["channel"]]}
+            """)
+
+    def _check_valid_recipient(self, params):
+        if not isinstance(params['to'], str):
+            raise MessagesError(f'Message recipient ("to={params["to"]}") not in a valid format.')
+        elif params['channel'] != 'messenger' and not re.search(r'^[1-9]\d{6,14}$', params['to']):
+            raise MessagesError(f'Message recipient number ("to={params["to"]}") not in a valid format.')
+        elif params['channel'] == 'messenger' and not 0 < len(params['to']) < 50:
+            raise MessagesError(f'Message recipient ID ("to={params["to"]}") not in a valid format.')
+
+    def _check_valid_sender(self, params):
+        if not isinstance(params['from'], str) or params['from'] == "":
+            raise MessagesError(f'Message sender ("frm={params["from"]}") set incorrectly. Set a valid name or number for the sender.')
+
+    def _channel_specific_checks(self, params):
+        try:        
+            if params['channel'] == 'whatsapp' and params['message_type'] == 'template':
+                params['whatsapp']
+            if params['channel'] == 'viber_service':
+                params['viber_service']
+        except (KeyError, TypeError):
+            raise MessagesError(f'''You must specify all required properties for message channel "{params["channel"]}".''')
+
+    def _check_valid_client_ref(self, params):
+        if 'client_ref' in params:
+            if len(params['client_ref']) <= 40:
+                self._client_ref = params['client_ref']
+            else:
+                raise MessagesError('client_ref can be a maximum of 40 characters.')

src/vonage/voice.py

@@ -1,6 +1,6 @@
 import vonage
 
-class Voice():
+class Voice:
     #application_id and private_key are needed for the calling methods
     #Passing a Vonage Client is also possible 
     def __init__(

tests/conftest.py

@@ -103,4 +103,10 @@ def ussd(client):
 def short_codes(client):
     import vonage
 
-    return vonage.ShortCodes(client)
+    return vonage.ShortCodes(client)
+
+@pytest.fixture
+def messages(client):
+    import vonage
+
+    return vonage.Messages(client)

tests/test_messages_send_message.py

@@ -0,0 +1,38 @@
+from util import *
+
+@responses.activate
+def test_send_sms_with_messages_api(messages, dummy_data):
+    stub(responses.POST, 'https://api.nexmo.com/v1/messages')
+
+    params = {
+        'channel': 'sms', 
+        'message_type': 'text', 
+        'to': '447123456789', 
+        'from': 'Vonage',
+        'text': 'Hello from Vonage'
+    }
+
+    assert isinstance(messages.send_message(params), dict)
+    assert request_user_agent() == dummy_data.user_agent
+    assert b'"from": "Vonage"' in request_body()
+    assert b'"to": "447123456789"' in request_body()
+    assert b'"text": "Hello from Vonage"' in request_body()
+
+@responses.activate
+def test_send_whatsapp_image_with_messages_api(messages, dummy_data):
+    stub(responses.POST, 'https://api.nexmo.com/v1/messages')
+
+    params = {
+        'channel': 'whatsapp', 
+        'message_type': 'image', 
+        'to': '447123456789', 
+        'from': '440123456789',
+        'image': {'url': 'https://example.com/image.jpg', 'caption': 'fake test image'}
+    }
+
+    assert isinstance(messages.send_message(params), dict)
+    assert request_user_agent() == dummy_data.user_agent
+    assert b'"from": "440123456789"' in request_body()
+    assert b'"to": "447123456789"' in request_body()
+    assert b'"image": {"url": "https://example.com/image.jpg", "caption": "fake test image"}' in request_body()
+