Merge pull request #93 from Bandwidth/SWI-2789

SWI-2789 Added Start/Stop Transcription

src/main/java/com/bandwidth/voice/bxml/verbs/Bxml.java

@@ -48,7 +48,11 @@ public class Bxml {
             @XmlElement(name = SipUri.TYPE_NAME, type = SipUri.class),            
             @XmlElement(name = StartStream.TYPE_NAME, type = StartStream.class),            
             @XmlElement(name = StopStream.TYPE_NAME, type = StopStream.class),            
-            @XmlElement(name = StreamParam.TYPE_NAME, type = StreamParam.class)            
+      	@XmlElement(name = StreamParam.TYPE_NAME, type = StreamParam.class),            
+            @XmlElement(name = StartTranscription.TYPE_NAME, type = StartTranscription.class),            
+            @XmlElement(name = StopTranscription.TYPE_NAME, type = StopTranscription.class),            
+            @XmlElement(name = CustomParam.TYPE_NAME, type = CustomParam.class),            
+
     })
     private final List<Verb> verbs = new ArrayList<>();
 

src/main/java/com/bandwidth/voice/bxml/verbs/CustomParam.java

@@ -0,0 +1,27 @@
+
+package com.bandwidth.voice.bxml.verbs;
+
+import javax.xml.bind.annotation.XmlType;
+import javax.xml.bind.annotation.XmlAttribute;
+import lombok.Builder;
+
+/**
+ * You may specify up to 12 <CustomParam/> elements nested within a <StartTranscription> tag. These elements define optional user specified parameters that will be sent to the destination URL when the real-time transcription is first started.
+ */
+@Builder
+@XmlType(name = CustomParam.TYPE_NAME)
+public class CustomParam implements Verb {
+    public static final String TYPE_NAME = "CustomParam";
+
+    /**
+     * <b>(required)</b> The name of this parameter, up to 256 characters.
+     */
+    @XmlAttribute
+    private String name;
+
+    /**
+     * <b>(required)</b> The value of this parameter, up to 2048 characters.
+     */
+    @XmlAttribute
+    private String value;
+}

src/main/java/com/bandwidth/voice/bxml/verbs/Response.java

@@ -47,7 +47,12 @@ public class Response {
             @XmlElement(name = Tag.TYPE_NAME, type = Tag.class),
             @XmlElement(name = SipUri.TYPE_NAME, type = SipUri.class),
             @XmlElement(name = StartStream.TYPE_NAME, type = StartStream.class),            
-            @XmlElement(name = StopStream.TYPE_NAME, type = StopStream.class)  
+		@XmlElement(name = StopStream.TYPE_NAME, type = StopStream.class),  
+            @XmlElement(name = StartTranscription.TYPE_NAME, type = StartTranscription.class),            
+            @XmlElement(name = StopTranscription.TYPE_NAME, type = StopTranscription.class),            
+            @XmlElement(name = CustomParam.TYPE_NAME, type = CustomParam.class),            
+
+
     })
     private final List<Verb> verbs = new ArrayList<>();
 

src/main/java/com/bandwidth/voice/bxml/verbs/StartTranscription.java

@@ -0,0 +1,139 @@
+
+package com.bandwidth.voice.bxml.verbs;
+
+import lombok.Builder;
+
+import java.net.URI;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.List;
+
+import javax.xml.bind.annotation.XmlAttribute;
+import javax.xml.bind.annotation.XmlType;
+import javax.xml.bind.annotation.XmlElement;
+
+
+/**
+ * The StartTranscription verb allows a segment of a call to be transcribed and optionally for the live transcription to be sent off to another destination for additional processing.
+ */
+@Builder
+@XmlType(name = StartTranscription.TYPE_NAME)
+public class StartTranscription implements Verb {
+    public static final String TYPE_NAME = "StartTranscription";
+
+    @XmlElement(name = CustomParam.TYPE_NAME)
+    private final List<CustomParam> customParams;
+
+    /**
+     * <i>(optional)</i> A name to refer to this transcription by. Used when sending <StopTranscription>. If not provided, it will default to the generated transcription id as sent in the Real-Time Transcription Started webhook.
+     */
+    @XmlAttribute
+    private String name;
+
+    /**
+     * <i>(optional)</i> the part of the call to send a transcription from. `inbound`, `outbound` or `both`. default is `inbound`. 
+     */
+    @XmlAttribute
+    private String tracks;
+
+    /**
+     * <i>(optional)</i> a websocket uri to send the real-time transcription to. the audio from the specified tracks will be sent via websocket to this url encoded as base64 encoded pcmu/g711 audio. see below for more details on the websocket packet format.
+     */
+    @XmlAttribute
+    private URI destination;
+
+    /**
+     * <i>(optional)</i> Whether to send transcription update events to the specified destination only after they have become stable. Requires destination. Defaults to true.
+     */
+    @XmlAttribute
+    private Boolean stabilized;
+
+    /**
+     * <i>(optional)</i> url to send the associated webhook events to during this real-time transcription's lifetime. Does not accept bxml. May be a relative URL. 
+     */
+    @XmlAttribute
+    private URI transcriptionEventUrl;
+
+    /**
+     * <i>(optional)</i> the http method to use for the request to `transcriptioneventurl`. get or post. default value is post.
+     */
+    @XmlAttribute
+    private Method transcriptionEventMethod;
+
+    /**
+     * <i>(optional)</i> the username to send in the http request to `transcriptioneventurl`. if specified, the urls must be tls-encrypted (i.e., `https`). 
+     */
+    @XmlAttribute
+    protected String username;
+
+    /**
+     * <i>(optional)</i> the password to send in the http request to `transcriptioneventurl`. if specified, the urls must be tls-encrypted (i.e., `https`).
+     */
+    @XmlAttribute
+    protected String password;
+
+
+    public static class StartTranscriptionBuilder {
+
+        /**
+         * <b>(optional)</b> url to send the associated webhook events to during this real-time transcription's lifetime. does not accept bxml. may be a relative url.
+         */
+        public StartTranscriptionBuilder transcriptionEventUrl(URI uri ){
+            this.transcriptionEventUrl = uri;
+            return this;
+        }
+
+        /**
+         * <b>(optional)</b> url to send the associated webhook events to during this real-time transcription's lifetime. does not accept bxml. may be a relative url.
+         */
+        public StartTranscriptionBuilder transcriptionEventUrl(String uri ){
+            return transcriptionEventUrl(URI.create(uri));
+        } 
+
+        /**
+         * <b>(required)</b> a websocket uri to send the real-time transcription to. the audio from the specified tracks will be sent via websocket to this url encoded as base64 encoded pcmu/g711 audio. see below for more details on the websocket packet format.
+         */
+        public StartTranscriptionBuilder destination(URI uri ){
+            this.destination = uri;
+            return this;
+        }
+
+        /**
+         * <b>(optional)</b> a websocket uri to send the real-time transcription to. the audio from the specified tracks will be sent via websocket to this url encoded as base64 encoded pcmu/g711 audio. see below for more details on the websocket packet format.
+         */
+        public StartTranscriptionBuilder destination(String uri ){
+            return destination(URI.create(uri));
+        }        
+
+        /**
+         * <i>(optional)</i> the http method to use for the request to `transcriptioneventurl`. get or post. default value is post.
+         */
+        public StartTranscriptionBuilder transcriptionEventMethod(Method method){
+            this.transcriptionEventMethod = method;
+            return this;
+        }
+
+        /**
+         * <i>(optional)</i> the http method to use for the request to `transcriptionEventUrl`. GET or POST. Default value is POST.
+         */
+        public StartTranscriptionBuilder transcriptionEventMethod(String method){
+            return transcriptionEventMethod(Method.fromValue(method));
+        }
+
+        /**
+         * <i>(optional)</i> you may specify up to 12 <customParam/> elements nested within a <startTranscription> tag. these elements define optional user specified parameters that will be sent to the destination url when the real-time transcription is first started.
+         */
+        public StartTranscriptionBuilder customParams(CustomParam ... customParams){
+            this.customParams = Arrays.asList(customParams);
+            return this;
+        }
+
+        /**
+         * <i>(optional)</i> you may specify up to 12 <customParam/> elements nested within a <startTranscription> tag. these elements define optional user specified parameters that will be sent to the destination url when the real-time transcription is first started.
+         */
+        public StartTranscriptionBuilder customParams(List<CustomParam> customParams){
+            this.customParams = customParams;
+            return this;
+        }        
+    }
+}

src/main/java/com/bandwidth/voice/bxml/verbs/StopTranscription.java

@@ -0,0 +1,22 @@
+
+package com.bandwidth.voice.bxml.verbs;
+
+import lombok.Builder;
+import javax.xml.bind.annotation.XmlAttribute;
+import javax.xml.bind.annotation.XmlType;
+
+
+/**
+ *  The Stoptranscription verb is used to stop the real-time transcription previously started by a `<StartTranscriptionm>` verb.
+ */
+@Builder
+@XmlType(name = StopTranscription.TYPE_NAME)
+public class StopTranscription implements Verb {
+    public static final String TYPE_NAME = "StopTranscription";
+
+    /**
+     * <i>(required)</i> The name of the real-time transcription to stop. This is either the user selected name when sending the <StartTranscription> verb, or the system generated name returned in the Real-Time Transcription Started webhook if <StartTranscription> was sent with no name attribute. If no name is specified, then all active call transcriptions will be stopped.
+     */
+    @XmlAttribute
+    private String name;
+}

src/test/java/com/bandwidth/BxmlTest.java

@@ -583,4 +583,51 @@ public void testGenerateBxmlVerb() {
                 + "</Transfer>";
         assertEquals("BXML strings are equal", expected, response);
     }
+
+    @Test
+    public void testStartTranscriptionBxmlVerb() {
+        CustomParam customParam1 = CustomParam.builder()
+                .name("name1")
+                .value("value1")
+                .build();
+        CustomParam customParam2 = CustomParam.builder()
+                .name("name2")
+                .value("value2")
+                .build();
+        ArrayList<CustomParam> customParams = new ArrayList<CustomParam>();
+        customParams.add(customParam1);
+        customParams.add(customParam2);
+        StartTranscription startTranscription = StartTranscription.builder()
+                .destination("https://url.com")
+                .transcriptionEventMethod("POST")
+                .username("user")
+                .password("pass")
+                .name("test_transcription")
+                .tracks("inbound")
+                .transcriptionEventUrl("https://url.com")
+                .customParams(customParams)
+                .build();
+
+        String response = new Response()
+                .add(startTranscription)
+                .toBXML();
+
+        String expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><StartTranscription name=\"test_transcription\" tracks=\"inbound\" destination=\"https://url.com\" transcriptionEventUrl=\"https://url.com\" transcriptionEventMethod=\"POST\" username=\"user\" password=\"pass\"><CustomParam name=\"name1\" value=\"value1\"/><CustomParam name=\"name2\" value=\"value2\"/></StartTranscription></Response>";
+        assertEquals("BXML strings are equal", expected, response);
+    }
+
+    @Test
+    public void testStopTranscription() {
+        StopTranscription stopTranscription = StopTranscription.builder()
+                .name("test")
+                .build();
+
+        String response = new Response()
+                .add(stopTranscription)
+                .toBXML();
+
+        String expected = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><Response><StopTranscription name=\"test\"/></Response>";
+
+        assertEquals("BXML strings not equal", expected, response);
+    }
 }