Merge pull request #122 from Bandwidth/DX-2897

DX-2897, DX-2902, DX-2909 - `<PlayAudio>`, `<SpeakSentence>`, and `<Gather>` verbs refactored

Author: brianluisgomez

bandwidth/model/bxml/terminal_verb.py

@@ -28,6 +28,6 @@ def add_verb(self, verb: Verb):
             verb (Verb): BXML verb
 
         Raises:
-            AttributeError: This method is not allowed for <SipUri>
+            AttributeError: This method is not allowed for this verb
         """
         raise AttributeError('Adding verbs is not supported by this verb')

bandwidth/model/bxml/verbs/__init__.py

@@ -1,8 +1,22 @@
 from .bridge import Bridge
+from .conference import Conference
+from .hangup import Hangup
+from .gather import Gather
+from .pause import Pause
 from .pause_recording import PauseRecording
 from .phone_number import PhoneNumber
+from .play_audio import PlayAudio
 from .record import Record
+from .ring import Ring
 from .send_dtmf import SendDtmf
 from .sip_uri import SipUri
+from .speak_sentence import SpeakSentence
+from .start_gather import StartGather
+from .start_recording import StartRecording
+from .start_stream import StartStream
+from .stop_gather import StopGather
+from .stop_stream import StopStream
+from .stop_recording import StopRecording
+from .stream_param import StreamParam
 from .tag import Tag
 from .transfer import Transfer

bandwidth/model/bxml/verbs/conference.py

@@ -0,0 +1,97 @@
+"""
+conference.py
+
+Bandwidth's Conference BXML verb
+
+@copyright Bandwidth INC
+"""
+from typing import Union, List
+from ..verb import Verb
+from .play_audio import PlayAudio
+from .speak_sentence import SpeakSentence
+from .start_recording import StartRecording
+from .stop_recording import StopRecording
+from .pause_recording import PauseRecording
+from .resume_recording import ResumeRecording
+
+
+class Conference(Verb):
+
+    def __init__(
+        self, name: str,
+        audio_and_recording_verbs: List[Union[PlayAudio, SpeakSentence, StartRecording, StopRecording, PauseRecording, ResumeRecording]] = [], mute: str=None, 
+        hold: str=None, call_ids_to_coach: str=None, 
+        conference_event_url: str=None, conference_event_method: str=None, 
+        conference_event_fallback_url: str=None, conference_event_fallback_method: str=None, 
+        username: str=None, password: str=None,
+        fallback_username: str=None, fallback_password: str=None, 
+        tag: str=None, callback_timeout: str=None,
+    ):
+        """Initialize a <Conference> verb
+
+        Args:
+            name (str): The name of the conference. Can contain up to 100 characters of letters, numbers, and the symbols -, _, and .
+            mute (str, optional): A boolean value to indicate whether the member should be on mute in the conference. When muted, a member can hear others speak, but others cannot hear them speak. Defaults to false.
+            hold (str, optional): A boolean value to indicate whether the member should be on hold in the conference. When on hold, a member cannot hear others, and they cannot be heard. Defaults to false.
+            call_ids_to_coach (str, optional): A comma-separated list of call ids to coach. When a call joins a conference with this attribute set, it will coach the listed calls. 
+                Those calls will be able to hear and be heard by the coach, but other calls in the conference will not hear the coach.
+            conference_event_url (str, optional): URL to send Conference events to. The URL, method, username, and password are set by the BXML document that creates the conference, 
+                and all events related to that conference will be delivered to that same endpoint. If more calls join afterwards and also have this property (or any other webhook related properties like username and password), 
+                they will be ignored and the original webhook information will be used. This URL may be a relative endpoint.
+            conference_event_method (str, optional): The HTTP method to use for the request to conferenceEventUrl. GET or POST. Default value is POST.
+            conference_event_fallback_url (str, optional): A fallback url which, if provided, will be used to retry the conference webhook deliveries in case conferenceEventUrl fails to respond.
+            conference_event_fallback_method (str, optional): The HTTP method to use to deliver the conference webhooks to conferenceEventFallbackUrl. GET or POST. Default value is POST.
+            username (str, optional):The username to send in the HTTP request to conferenceEventUrl.
+            password (str, optional): The password to send in the HTTP request to conferenceEventUrl.
+            fallback_username (str, optional): The username to send in the HTTP request to conferenceEventFallbackUrl.
+            fallback_password (str, optional): The password to send in the HTTP request to conferenceEventFallbackUrl.
+            tag (str, optional): A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared. May be cleared by setting tag="". 
+                Max length 256 characters. Defaults to None.
+            callback_timeout (str, optional): This is the timeout (in seconds) to use when delivering webhooks for the conference. 
+                If not set, it will inherit the webhook timeout from the call that creates the conference. Can be any numeric value (including decimals) between 1 and 25.
+
+        Nested Verbs:
+            PlayAudio: (optional) 
+            SpeakSentence: (optional) 
+            StartRecording: (optional) 
+            StopRecording: (optional)
+            PauseRecording: (optional) 
+            ResumeRecording: (optional)
+        """
+        self.name = name
+        self.mute = mute
+        self.hold = hold
+        self.call_ids_to_coach = call_ids_to_coach
+        self.conference_event_url = conference_event_url
+        self.conference_event_method = conference_event_method
+        self.conference_event_fallback_url = conference_event_fallback_url
+        self.conference_event_fallback_method = conference_event_fallback_method
+        self.username = username
+        self.password = password
+        self.fallback_username = fallback_username
+        self.fallback_password = fallback_password
+        self.tag = tag
+        self.callback_timeout = callback_timeout
+        self.audio_and_recording_verbs = audio_and_recording_verbs
+        super().__init__(
+            tag="Conference", 
+            content=self.name,
+            nested_verbs=self.audio_and_recording_verbs)
+
+    @property
+    def _attributes(self):
+        return {
+            "mute": self.mute,
+            "hold": self.hold,
+            "callIdsToCoach": self.call_ids_to_coach,
+            "conferenceEventUrl": self.conference_event_url,
+            "conferenceEventMethod": self.conference_event_method,
+            "conferenceEventFallbackUrl": self.conference_event_fallback_url,
+            "conferenceEventFallbackMethod": self.conference_event_fallback_method,
+            "username": self.username,
+            "password": self.password,
+            "fallbackUsername": self.fallback_username,
+            "fallbackPassword": self.fallback_password,
+            "tag": self.tag,
+            "callbackTimeout": self.callback_timeout,
+        }

bandwidth/model/bxml/verbs/forward.py

@@ -0,0 +1,67 @@
+"""
+forward.py
+
+Bandwidth's Forward BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class Forward(TerminalVerb):
+
+    def __init__(
+        self, to: str=None, _from: str=None, 
+        call_timeout: str=None, diversion_treatment: str=None, 
+        diversion_reason: str=None, uui: str=None
+    ):
+        """Initialize a <Forward> verb
+
+        Args:
+            to (str): The phone number destination of the call.
+            from_ (str, optional): The phone number that the recipient will receive the call from.
+            call_timeout (str, optional): The number of seconds to wait before timing out the call.
+            diversion_treatment (str, optional): Can be any of the following:
+                none: No diversion headers are sent on the outbound leg of the transferred call.
+                propagate: Copy the Diversion header from the inbound leg to the outbound leg. Ignored if there is no Diversion header present on the inbound leg.
+                stack: After propagating any Diversion header from the inbound leg to the outbound leg, stack on top another Diversion header based on the Request-URI of the inbound call.
+
+                Defaults to none. If diversionTreatment is not specified, no diversion header will be included for the transfer even if one came with the inbound call. Defaults to None.
+            diversion_reason (str, optional): Can be any of the following values:
+                unknown
+                user-busy
+                no-answer
+                unavailable
+                unconditional
+                time-of-day
+                do-not-disturb
+                deflection
+                follow-me
+                out-of-service
+                away
+
+                This parameter is considered only when diversionTreatment is set to stack. Defaults is unknown. 
+                Defaults to None.
+            uui (str, optional): The value of the User-To-User header to send within the outbound INVITE when forwarding to a SIP URI. 
+                Must include the encoding parameter as specified in RFC 7433. Only base64 and jwt encoding are currently allowed. 
+                This value, including the encoding specifier, may not exceed 256 characters.
+        """
+        self.to = to
+        self._from = _from
+        self.call_timeout = call_timeout
+        self.diversion_treatment = diversion_treatment
+        self.diversion_reason = diversion_reason
+        self.uui = uui
+
+        super().__init__(tag="Forward")
+
+    @property
+    def _attributes(self):
+        return {
+            "to": self.to,
+            "_from": self._from,
+            "callTimeout": self.call_timeout,
+            "diversionTreatment": self.diversion_treatment,
+            "diversionReason": self.diversion_reason,
+            "uui": self.uui,
+        }        

bandwidth/model/bxml/verbs/gather.py

@@ -0,0 +1,87 @@
+"""
+gather.py
+
+Bandwidth's Gather BXML verb
+
+@copyright Bandwidth INC
+"""
+from typing import Union, List
+from ..verb import Verb
+from .play_audio import PlayAudio
+from .speak_sentence import SpeakSentence
+
+
+class Gather(Verb):
+
+    def __init__(
+        self, audio_verbs: List[Union[PlayAudio, SpeakSentence]] = [],
+        gather_url: str=None, gather_method: str=None, 
+        gather_fallback_url: str=None, gather_fallback_method: str=None, 
+        username: str=None, password: str=None,
+        fallback_username: str=None, fallback_password: str=None, 
+        tag: str=None, terminating_digits: str=None,
+        max_digits: str=None, inter_digit_timeout: str=None, 
+        first_digit_timeout: str=None, repeat_count: str=None
+    ):
+        """Initialize a <Gather> verb
+
+        Args:
+            gather_url (str, optional): URL to send Gather event to and request new BXML. May be a relative URL.
+            gather_method (str, optional): The HTTP method to use for the request to gather_url. GET or POST. Default value is POST.
+            gather_fallback_url (str, optional): A fallback url which, if provided, will be used to retry the Gather event callback delivery in case gather_url fails to respond.
+            gather_fallback_method (str, optional): The HTTP method to use to deliver the Gather event callback to gather_fallback_url. GET or POST. Default value is POST.
+            username (str, optional): The username to send in the HTTP request to gather_url.
+            password (str, optional): The password to send in the HTTP request to gather_url.
+            fallback_username (str, optional): The username to send in the HTTP request to gather_fallback_url.
+            fallback_password (str, optional): The password to send in the HTTP request to gather_fallback_url.
+            tag (str, optional): A custom string that will be sent with this and all future callbacks unless overwritten by a future tag attribute or <Tag> verb, or cleared. 
+                May be cleared by setting tag="". Max length 256 characters.
+            terminating_digits (str, optional): When any of these digits are pressed, it will terminate the Gather. Default value is "", which disables this feature.
+            max_digits (str, optional): Max number of digits to collect. Default value is 50. Range: decimal values between 1 - 50.
+            inter_digit_timeout (str, optional): Time (in seconds) allowed between digit presses before automatically terminating the Gather. Default value is 5. Range: decimal values between 1 - 60.
+            first_digit_timeout (str, optional): Time (in seconds) to pause after any audio from nested <SpeakSentence> or <PlayAudio> verb is played (in seconds) before terminating the Gather. 
+                Default value is 5. Range: decimal values between 0 - 60.
+            repeat_count (str, optional): The number of times the audio prompt should be played if no digits are pressed. For example, if this value is 3, the nested audio clip will be played a maximum of three times. 
+                The delay between repetitions will be equal to first_digit_timeout. Default value is 1. repeat_count * number of verbs must not be greater than 20.
+
+        Nested Verbs:
+            PlayAudio: (optional) Using the PlayAudio inside the Gather verb will play the media until a digit is received.
+            SpeakSentence: (optional) Using the SpeakSentence inside the Gather verb will speak the text until a digit is received.
+        """
+        self.gather_url = gather_url
+        self.gather_method = gather_method
+        self.gather_fallback_url = gather_fallback_url
+        self.gather_fallback_method = gather_fallback_method
+        self.username = username
+        self.password = password
+        self.fallback_username = fallback_username
+        self.fallback_password = fallback_password
+        self.tag = tag
+        self.terminating_digits = terminating_digits
+        self.max_digits = max_digits
+        self.inter_digit_timeout = inter_digit_timeout
+        self.first_digit_timeout = first_digit_timeout
+        self.repeat_count = repeat_count
+        self.audio_verbs = audio_verbs
+        super().__init__(
+            tag="Gather", 
+            nested_verbs=self.audio_verbs)
+
+    @property
+    def _attributes(self):
+        return {
+            "gatherUrl": self.gather_url,
+            "gatherMethod": self.gather_method,
+            "gatherFallbackUrl": self.gather_fallback_url,
+            "gatherFallbackMethod": self.gather_fallback_method,
+            "username": self.username,
+            "password": self.password,
+            "fallbackUsername": self.fallback_username,
+            "fallbackPassword": self.fallback_password,
+            "tag": self.tag,
+            "terminatingDigits": self.terminating_digits,
+            "maxDigits": self.max_digits,
+            "interDigitTimeout": self.inter_digit_timeout,
+            "firstDigitTimeout": self.first_digit_timeout,
+            "repeatCount": self.repeat_count,
+        }

bandwidth/model/bxml/verbs/hangup.py

@@ -0,0 +1,19 @@
+"""
+hangup.py
+
+Bandwidth's Hangup BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class Hangup(TerminalVerb):
+
+    def __init__(self):
+        """Initialize a <Hangup> verb
+
+        Args:
+            None
+        """
+        super().__init__(tag="Hangup")

bandwidth/model/bxml/verbs/pause.py

@@ -0,0 +1,23 @@
+"""
+pause.py
+
+Bandwidth's Pause BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+class Pause(TerminalVerb):
+    def __init__(self, duration:str=None):
+        """Initialize a <Pause> verb
+        Args:
+            duration (str, optional): The time in seconds to pause. Default value is 1.
+        """
+        self.duration = duration
+
+        super().__init__(tag="Pause")
+    
+    @property
+    def _attributes(self):
+        return {
+            "duration": self.duration
+        }

bandwidth/model/bxml/verbs/pause_recording.py

@@ -13,4 +13,4 @@ class PauseRecording(TerminalVerb):
     def __init__(self):
         """Initialize a <PauseRecording> verb
         """
-        super().__init__(tag="PauseRecording", content=None, attributes=None)
+        super().__init__(tag="PauseRecording")

bandwidth/model/bxml/verbs/play_audio.py

@@ -0,0 +1,37 @@
+"""
+play_audio.py
+
+Bandwidth's PlayAudio BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class PlayAudio(TerminalVerb):
+
+    def __init__(
+        self, audio_uri: str, 
+        username: str=None, password: str=None
+    ):
+        """Initialize a <PlayAudio> verb
+
+        Args:
+            audio_uri (str): The URL of the audio file to play. May be a relative URL.
+            username (str, optional): The username to send in the HTTP request to audio_uri.
+            password (str, optional): The password to send in the HTTP request to audio_uri.
+        """
+        self.audio_uri = audio_uri
+        self.username = username
+        self.password = password
+        super().__init__(
+            tag="PlayAudio",
+            content=self.audio_uri,
+        )
+
+    @property
+    def _attributes(self):
+        return {
+            "username": self.username,
+            "password": self.password,
+        }

bandwidth/model/bxml/verbs/resume_recording.py

@@ -0,0 +1,21 @@
+"""
+record.py
+
+Bandwidth's ResumeRecording BXML verb
+
+@copyright Bandwidth INC
+"""
+from ..terminal_verb import TerminalVerb
+
+
+class ResumeRecording(TerminalVerb):
+
+    def __init__(
+        self
+    ):
+        """Initialize a <ResumeRecording> verb
+
+        Args: There are no args or text content for ResumeRecording
+        """
+
+        super().__init__(tag="ResumeRecording", content=None)