feat: add twiml support (#186)

Co-authored-by: cchua <[email protected]>

Author: JenniferMah

README.md

@@ -69,7 +69,7 @@ func main() {
 }
 ```
 
-If you don't want to use environment variables, you can also pass the credentials directly to the constructor as below. 
+If you don't want to use environment variables, you can also pass the credentials directly to the constructor as below.
 
 ```go
 package main
@@ -427,6 +427,56 @@ func main() {
 For more descriptive exception types, please see
 the [Twilio documentation](https://www.twilio.com/docs/libraries/go/usage-guide#exceptions).
 
+### Generating TwiML
+
+To control phone calls, your application needs to output [TwiML](https://www.twilio.com/docs/voice/twiml).
+
+Use the `twiml` package to easily create such responses.
+
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/twilio/twilio-go/twiml"
+)
+
+func main() {
+	//Construct Verbs
+	dial := &twiml.VoiceDial{}
+	say := &twiml.VoiceSay{
+		Message:            "Welcome to Twilio!",
+		Voice:              "woman",
+		Language:           "en-gb",
+		OptionalAttributes: map[string]string{"input": "test"},
+	}
+	pause := &twiml.VoicePause{
+		Length: "10",
+	}
+	//Construct Noun
+	queue := &twiml.VoiceQueue{
+		Url: "www.twilio.com",
+	}
+	//Adding Queue to Dial
+	dial.Nouns = []twiml.Element{queue}
+
+	//Adding all Verbs to twiml.Voice
+	verbList := []twiml.Element{dial, say, pause}
+	twimlResult := twiml.Voice(verbList)
+	fmt.Println(twimlResult)
+}
+```
+This will print the following:
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+    <Dial>
+        <Queue url="www.twilio.com"/>
+    </Dial>
+    <Say voice="woman" language="en-gb" input="test">Welcome to Twilio!</Say>
+    <Pause length="10"/>
+</Response>
+```
 ## Advanced Usage
 
 ### Using Request Validator
@@ -555,7 +605,7 @@ func main() {
 ```
 
 ## Building Access Tokens
-This library supports [access token](https://www.twilio.com/docs/iam/access-tokens) generation for use in the Twilio Client SDKs. 
+This library supports [access token](https://www.twilio.com/docs/iam/access-tokens) generation for use in the Twilio Client SDKs.
 
 Here's how you would generate a token for the Voice SDK:
 ```go
@@ -616,7 +666,6 @@ capabilityToken := taskrouter.CreateCapabilityToken(Params)
 token, err := capabilityToken.ToJwt()
 ```
 
-
 ## Local Usage
 
 ### Building

go.mod

@@ -3,11 +3,12 @@ module github.com/twilio/twilio-go
 go 1.16
 
 require (
+	github.com/beevik/etree v1.1.0
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/golang-jwt/jwt v3.2.2+incompatible
 	github.com/golang/mock v1.6.0
 	github.com/kr/text v0.2.0 // indirect
-	github.com/localtunnel/go-localtunnel v0.0.0-20170326223115-8a804488f275 // indirect
+	github.com/localtunnel/go-localtunnel v0.0.0-20170326223115-8a804488f275
 	github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e // indirect
 	github.com/pkg/errors v0.9.1
 	github.com/stretchr/testify v1.7.0

go.sum

@@ -1,3 +1,5 @@
+github.com/beevik/etree v1.1.0 h1:T0xke/WvNtMoCqgzPhkX2r4rjY3GDZFi+FjpRZY2Jbs=
+github.com/beevik/etree v1.1.0/go.mod h1:r8Aw8JqVegEf0w2fDnATrX9VpkMcyFeM0FhwO62wh+A=
 github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=

twiml/messaging_response.go

@@ -0,0 +1,133 @@
+//This code was generated by
+//\ / _    _  _|   _  _
+// | (_)\/(_)(_|\/| |(/_  v1.0.0
+//      /       /
+
+package twiml
+
+func Messages(verbs []Element)(TwimlXml string){
+    doc, response := CreateDocument()
+    if verbs != nil {
+        AddAllVerbs(response, verbs)
+    }
+    return ToXML(doc)
+}
+
+//MessagingRedirect <Redirect> TwiML Verb
+type MessagingRedirect struct {
+    // url: Redirect URL
+    // method: Redirect URL method
+    // OptionalAttributes: additional attributes
+    Url string
+    Method string
+    Nouns []Element
+    OptionalAttributes map[string]string
+}
+
+func (m MessagingRedirect) GetName() string {
+    return "Redirect"
+}
+
+func (m MessagingRedirect) GetText() string {
+    return m.Url
+}
+
+func (m MessagingRedirect) GetAttr() (map[string]string, map[string]string) {
+    paramsAttr := map[string]string{
+    	"Method": m.Method,
+    }
+    return m.OptionalAttributes, paramsAttr
+}
+
+func (m MessagingRedirect) GetNouns() []Element {
+    return m.Nouns
+}
+//MessagingMessage <Message> TwiML Verb
+type MessagingMessage struct {
+    // body: Message Body
+    // to: Phone Number to send Message to
+    // from: Phone Number to send Message from
+    // action: Action URL
+    // method: Action URL Method
+    // status_callback: Status callback URL. Deprecated in favor of action.
+    // OptionalAttributes: additional attributes
+    Body string
+    To string
+    From string
+    Action string
+    Method string
+    StatusCallback string
+    Nouns []Element
+    OptionalAttributes map[string]string
+}
+
+func (m MessagingMessage) GetName() string {
+    return "Message"
+}
+
+func (m MessagingMessage) GetText() string {
+    return m.Body
+}
+
+func (m MessagingMessage) GetAttr() (map[string]string, map[string]string) {
+    paramsAttr := map[string]string{
+    	"To": m.To,
+    	"From": m.From,
+    	"Action": m.Action,
+    	"Method": m.Method,
+    	"StatusCallback": m.StatusCallback,
+    }
+    return m.OptionalAttributes, paramsAttr
+}
+
+func (m MessagingMessage) GetNouns() []Element {
+    return m.Nouns
+}
+//MessagingMedia <Media> TwiML Noun
+type MessagingMedia struct {
+    // url: Media URL
+    // OptionalAttributes: additional attributes
+    Url string
+    Nouns []Element
+    OptionalAttributes map[string]string
+}
+
+func (m MessagingMedia) GetName() string {
+    return "Media"
+}
+
+func (m MessagingMedia) GetText() string {
+    return m.Url
+}
+
+func (m MessagingMedia) GetAttr() (map[string]string, map[string]string) {
+    return m.OptionalAttributes, nil
+}
+
+func (m MessagingMedia) GetNouns() []Element {
+    return m.Nouns
+}
+//MessagingBody <Body> TwiML Noun
+type MessagingBody struct {
+    // message: Message Body
+    // OptionalAttributes: additional attributes
+    Message string
+    Nouns []Element
+    OptionalAttributes map[string]string
+}
+
+func (m MessagingBody) GetName() string {
+    return "Body"
+}
+
+func (m MessagingBody) GetText() string {
+    return m.Message
+}
+
+func (m MessagingBody) GetAttr() (map[string]string, map[string]string) {
+    return m.OptionalAttributes, nil
+}
+
+func (m MessagingBody) GetNouns() []Element {
+    return m.Nouns
+}

twiml/twiml.go

@@ -0,0 +1,67 @@
+package twiml
+
+import (
+	"github.com/beevik/etree"
+	"strings"
+)
+
+type Element interface {
+	GetName() string
+	GetText() string
+	GetAttr() (map[string]string, map[string]string)
+	GetNouns() []Element
+}
+
+func AddAllVerbs(response *etree.Element, verbs []Element) {
+	for _, verb := range verbs {
+		verbEl := createElement(verb)
+		response.AddChild(verbEl)
+	}
+}
+
+func createElement(tag Element) *etree.Element {
+	el := etree.NewElement(tag.GetName())
+	optAttr, paramAttr := tag.GetAttr()
+	addPropertyToElement(el, tag.GetText(), optAttr, paramAttr)
+	//Loop through all Nouns
+	if len(tag.GetNouns()) != 0 {
+		for _, noun := range tag.GetNouns() {
+			child := createElement(noun)
+			el.AddChild(child)
+		}
+	}
+	return el
+}
+
+func CreateDocument() (*etree.Document, *etree.Element) {
+	doc := etree.NewDocument()
+	doc.CreateProcInst("xml", `version="1.0" encoding="UTF-8"`)
+	element := doc.CreateElement("Response")
+	return doc, element
+}
+
+func ToXML(document *etree.Document) string {
+	xml, err := document.WriteToString()
+	if err == nil {
+		return xml
+	}
+	return err.Error()
+}
+
+func addPropertyToElement(treeElement *etree.Element, text string, optAttr map[string]string, paramAttr map[string]string) {
+	if text != "" {
+		treeElement.SetText(text)
+	}
+
+	for _, attr := range []map[string]string{paramAttr, optAttr} {
+		for k, v := range attr {
+			if v != "" {
+				treeElement.CreateAttr(formatAttrKey(k), v)
+			}
+		}
+	}
+}
+
+func formatAttrKey(s string) string {
+	return strings.ToLower(string(s[0])) + s[1:]
+}