Usage
=====

Installation
------------

To run *pridar_telegram_bot*, first install it using pip:

.. code-block:: console

   (.venv) $ pip install pyTelegramBotAPI

Deployment to Telegram
----------------------


.. py:function:: launch(message=str)

   implements the API calls to Voiceflow for first message

   :param message: user response
   :type kind: str
   :return: response
   :rtype: JSON Object
   
.. code-block:: python
   :linenos: 

   def launch(message):
      """ implements the API calls to Voiceflow for first message

      Parameters
      ----------
      message : str
            User response
      
      Returns
      -------
      response : JSON object
         API call to VoiceFlow
      """
      body = {"action": {"type": "launch"}}
      response = requests.post(
         f"https://general-runtime.voiceflow.com/state/user/"+str(message.chat.id)+"/interact",
         json=body,
         headers={"Authorization": VF_API_KEY},
      )
      return response.json()


.. py:function:: sendMsg(message=str)

   implements the API calls to Voiceflow

   :param message: user response
   :type kind: str
   :return: response
   :rtype: JSON Object
   

.. code-block:: python
   :linenos:
   
   def sendMsg(message):
      """ implements the API calls to Voiceflow

      Parameters
      ----------
      message : str
            User response

      Returns
      -------
      response : JSON object
         API call to VoiceFlow
      """
      global request_body
      if choice:
         for c in choices:
               if c["name"] == message.text:
                  request_body = c
      else:
         request_body = {"action": {"type": "text","payload":message.text}}
      response = requests.post(
         f"https://general-runtime.voiceflow.com/state/user/"+str(message.chat.id)+"/interact",
         json=request_body,
         headers={"Authorization": VF_API_KEY},
      )
      return response.json()

.. py:function:: start(message='/start')

   creates first API call to VoiceFlow

   :param message: start message
   :type kind: str

.. code-block:: python
   :linenos:

   @bot.message_handler(commands=["start"])
   def start(message):
      """
      only implemented when "/start" command is received
      forwards the payload extracted from the response to the user

      Parameters
      ----------
      message : str
            User's first message
      """
      print("launched")
      response = launch(message)
      bot.send_message(message.chat.id, response[-1]["payload"]["message"])



.. py:function:: handle_message(message=str)

   forwards the payload extracted from all responses to the user after first message

   :param message: message
   :type kind: str
   
.. code-block:: python
   :linenos:

   @bot.message_handler()
   def handle_message(message):
      """
      forwards the payload extracted from all responses to the user after first message

      Parameters
      ----------
      message : str
         user message for payload to be extracted
      """
      print(message.text)
      global choice
      global choices
      global request_body
      global response
      response = sendMsg(message)
      choice = False
      choices = []

      for resp in response:
        if resp["type"] == "text":
            bot.send_message(message.chat.id, resp["payload"]["message"])
        elif resp["type"] == "choice":
            choice = True
            for choice in resp["payload"]["buttons"]:
                choices.append(choice)
                bot.send_message(message.chat.id, choice["name"])
        elif resp["type"] == "end":
            bot.send_message(message.chat.id, "Thanks for using our chatbot.")





Complete Implementation
-----------------------

Find below the complete implementation of PRIDAR Chatbot Telegram deployment.

.. code-block:: python
   :linenos:

   """
   pridar_telegram_bot.py
   ======================

   Deployment of PRIDAR Chatbot from VoiceFlow to Telegram

   This program makes https requests to VoiceFlow
   with the received messages using the VoiceFlow API key and
   extracts the response payload to forward back to Telegram.

   Documented by Linta Rahman
   """

   import telebot
   import requests
   import os

   BOT_API_KEY = os.environ.get("TELEBOT_API_KEY")
   VF_API_KEY = os.environ.get("VF_API_KEY")
   bot = telebot.TeleBot(BOT_API_KEY)
   request_body = ""
   choice = False
   choices = []
   response = ""


   def launch(message):
      """ implements the API calls to Voiceflow for first message

      Parameters
      ----------
      message : str
            User response
      
      Returns
      -------
      response : JSON object
         API call to VoiceFlow
      """
      body = {"action": {"type": "launch"}}
      response = requests.post(
         f"https://general-runtime.voiceflow.com/state/user/"+str(message.chat.id)+"/interact",
         json=body,
         headers={"Authorization": VF_API_KEY},
      )
      return response.json()

   def sendMsg(message):
      """ implements the API calls to Voiceflow

      Parameters
      ----------
      message : str
            User response

      Returns
      -------
      response : JSON object
         API call to VoiceFlow
      """
      global request_body
      if choice:
         for c in choices:
               if c["name"] == message.text:
                  request_body = c
      else:
         request_body = {"action": {"type": "text","payload":message.text}}
      response = requests.post(
         f"https://general-runtime.voiceflow.com/state/user/"+str(message.chat.id)+"/interact",
         json=request_body,
         headers={"Authorization": VF_API_KEY},
      )
      return response.json()

   @bot.message_handler(commands=["start"])
   def start(message):
      """
      only implemented when "/start" command is received
      forwards the payload extracted from the response to the user

      Parameters
      ----------
      message : str
            User's first message
      """
      print("launched")
      response = launch(message)
      bot.send_message(message.chat.id, response[-1]["payload"]["message"])

   @bot.message_handler()
   def handle_message(message):
      """
      forwards the payload extracted from all responses to the user after first message

      Parameters
      ----------
      message : str
         user message for payload to be extracted
      """
      print(message.text)
      global choice
      global choices
      global request_body
      global response
      response = sendMsg(message)
      choice = False
      choices = []

      for resp in response:
         if resp["type"] == "text":
               bot.send_message(message.chat.id, resp["payload"]["message"])
         elif resp["type"] == "choice":
               choice = True
               for choice in resp["payload"]["buttons"]:
                  choices.append(choice)
                  bot.send_message(message.chat.id, choice["name"])
         elif resp["type"] == "end":
               bot.send_message(message.chat.id, "Thanks for using our chatbot.")


   while True:
      try:
         bot.polling()
      except Exception as ex:
         print(ex)
         print("Bot polling failed, restarting...")
         bot.stop_polling()
      else:
         bot.stop_polling()
         break