Add support for sending contacts

The Bot API 2.0 update added support for sending contacts, which your
bot could receive but not send. This commit implements all the required
methods to expose this to the users.

Fixes: GH-57

Author: Pietro Albini

botogram/objects/mixins.py

@@ -164,6 +164,18 @@ def send_sticker(self, sticker, reply_to=None, extra=None, notify=True):
         return self._api.call("sendSticker", args, files,
                               expect=_objects().Message)
 
+    def send_contact(self, phone, first_name, last_name=None, *, reply_to=None,
+                     extra=None, notify=True):
+        """Send a contact"""
+        args = self._get_call_args(reply_to, extra, notify)
+        args["phone_number"] = phone
+        args["first_name"] = first_name
+
+        if last_name is not None:
+            args["last_name"] = last_name
+
+        return self._api.call("sendContact", args, expect=_objects().Message)
+
 
 class MessageMixin:
     """Add some methods for messages"""
@@ -254,6 +266,11 @@ def reply_with_sticker(self, *args, **kwargs):
         """Reply with a sticker to the current message"""
         return self.chat.send_sticker(*args, reply_to=self, **kwargs)
 
+    @_require_api
+    def reply_with_contact(self, *args, **kwargs):
+        """Reply with a contact to the current message"""
+        return self.chat.send_contact(*args, reply_to=self, **kwargs)
+
 
 class FileMixin:
     """Add some methods for files"""

docs/api/telegram.rst

@@ -316,6 +316,30 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: send_contact(phone, first_name, [last_name=None, reply_to=None, extra=None, notify=True])
+
+      Send a contact to the user. A Telegram contact is made of its phone
+      number (with the international prefix), its first name and optionally its
+      last name. You can use this, for example, to send the user the phone
+      number of a buisness so he can call them:
+
+      .. code-block:: python
+
+         @bot.command("support")
+         def support_command(chat, message, args):
+             message.sender.send("Hi there, here is our support number:")
+             message.sender.send_contact("+390124567890", "Support")
+
+      :param str phone: The phone number of the contact
+      :param str first_name: The first name of the contact
+      :param str last_name: The last name of the contact
+      :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to
+      :param object extra: An extra reply interface object to attach
+      :param bool notify: If you want to trigger a notification on the client
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. versionadded:: 0.3
 
 .. py:class:: botogram.Chat
 
@@ -732,6 +756,31 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: send_contact(phone, first_name, [last_name=None, reply_to=None, extra=None, notify=True])
+
+      Send a contact to the chat. A Telegram contact is made of its phone
+      number (with the international prefix), its first name and optionally its
+      last name. You can use this, for example, to send the user the phone
+      number of a buisness so he can call them:
+
+      .. code-block:: python
+
+         @bot.command("support")
+         def support_command(chat, message, args):
+             chat.send("Hi there, here is our support number:")
+             chat.send_contact("+390124567890", "Support")
+
+      :param str phone: The phone number of the contact
+      :param str first_name: The first name of the contact
+      :param str last_name: The last name of the contact
+      :param int reply_to: The ID of the :py:class:`~botogram.Message` this one is replying to
+      :param object extra: An extra reply interface object to attach
+      :param bool notify: If you want to trigger a notification on the client
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. versionadded:: 0.3
+
 .. py:class:: botogram.ParsedText
 
    This class contains the parsed representation of the text of a received
@@ -1327,6 +1376,30 @@ about its business.
 
          Now the method returns the sent message
 
+   .. py:method:: reply_with_contact(phone, first_name, [last_name=None, extra=None, notify=True])
+
+      Reply to this message with a contact. A Telegram contact is made of its
+      phone number (with the international prefix), its first name and
+      optionally its last name. You can use this, for example, to send the user
+      the phone number of a buisness so he can call them:
+
+      .. code-block:: python
+
+         @bot.command("support")
+         def support_command(chat, message, args):
+             message.reply("Hi there, here is our support number:")
+             message.reply_with_contact("+390124567890", "Support")
+
+      :param str phone: The phone number of the contact
+      :param str first_name: The first name of the contact
+      :param str last_name: The last name of the contact
+      :param object extra: An extra reply interface object to attach
+      :param bool notify: If you want to trigger a notification on the client
+      :returns: The message you sent
+      :rtype: ~botogram.Message
+
+      .. versionadded:: 0.3
+
 
 .. py:class:: botogram.Photo
 

docs/changelog/0.3.rst

@@ -48,6 +48,12 @@ New features
    * New decorator :py:meth:`botogram.Bot.message_edited`
    * New method :py:meth:`botogram.Component.add_message_edited_hook`
 
+* Added support for sending contacts:
+
+   * New method :py:meth:`botogram.User.send_contact`
+   * New method :py:meth:`botogram.Chat.send_contact`
+   * New method :py:meth:`botogram.Message.reply_with_contact`
+
 * Added new attribute :py:attr:`botogram.Message.pinned_message`
 * Added new attribute :py:attr:`botogram.Sticker.emoji`
 * Added new attribute :py:attr:`botogram.Chat.admins`