github.com/wyc/utwil

utwil: Go Utilities for Twilio

utwil is currently under heavy development, so expect breakage.

Documentation can be found at: https://godoc.org/github.com/wyc/utwil

Made with gojson.

Installation

In your terminal:

$ go get github.com/wyc/utwil

In your code:

import "github.com/wyc/utwil"

Features

Make a utwil.Client

client := utwil.NewClient(AccoutSID, AuthToken)

Send an SMS

// type client.SendSMS func(from, to, msg string) (utwil.Message, error)
msg, err := client.SendSMS("[phone]", "[phone]", "Hello, world!")

Send an MMS

// type client.SendMMS func(from, to, msg, mediaURL string) (utwil.Message, error)
mediaURL := "http://i.imgur.com/sZPem77.png"
body := "Hello, world!"
msg, err := client.SendMMS("[phone]", "[phone]", body, mediaURL)

Make a Call

callbackPostURL := fmt.Sprintf(
        "http://twimlets.com/forward?PhoneNumber=%s",
        "[phone]",
)
// type client.Call func(from, to, callbackPostURL string) (utwil.Call, error)
call, err := client.Call("[phone]", "[phone]", callbackPostURL)

Make a Recorded Call

// type client.RecordedCall func(from, to, callbackURL string) (utwil.Call, error)
call, err := client.RecordedCall("[phone]", "[phone]", callbackPostURL)

Lookups

// type client.Lookup func(phoneNumber string) (utwil.Lookup, error)
lookup, err := client.Lookup("[phone]")
// handle err
fmt.Println(lookup.Carrier.Type) // "mobile", "landline", or "voip"

Custom requests

For more complicated requests, populate the respective XxxxxReq struct and call the client.SubmitXxxxx(XxxxxReq) (Xxxxx, error) method:

msgReq := utwil.MessageReq{
        From:           "[phone]",
        To:             "[phone]",
        Body:           "Hello, world!",
        StatusCallback: "https://post.here.com/when/msg/status/changes.twiml",
}
msg, err := client.SubmitMessage(msgReq)

Query Messages (SMS/MMS)

weekAgo := time.Now().Add(-7 * 24 * time.Hour)
iter := client.Messages(
                utwil.SentBeforeYMD(weekAgo),
                utwil.To("[phone]")).Iter()
var msg utwil.Message
for iter.Next(&msg) {
        // do something with utwil.Message
}
if iter.Err() != nil {
        // handle err
}

Query Calls

iter := client.Calls(
                utwil.From("[phone]"),
                utwil.StartedAfter("2015-04-01")).Iter()
var call utwil.Call
for iter.Next(&call) {
        // do something with utwil.Call
}
if iter.Err() != nil {
        // handle err
}

Testing

First, populate env vars TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_DEFAULT_TO, TWILIO_DEFAULT_FROM. Then run go test and expect many annoyances to TWILIO_DEFAULT_TO:

• Phone call and second forwarded phone call to the same number
• One SMS message

Run go test -test.v instead if you want more details to the console.

To do

• Better testing harness...maybe we can borrow a testing AccountSID/AuthToken pair and commit them to the repo >:)
• Fetching additional resources from a call/msg such as recording or MMS
• Tools for responding with TwiML, including changing live call state
• CRUD for managerial records such as accounts, addresses, phone numbers, queues, SIP, etc
• More comments in src
• Investigate STUN, TURN, and ICE offerings

Feel free to request features by opening an issue.

Alternatives

• https://github.com/sfreiberg/gotwilio (No lookup or call/msg listing)
• https://bitbucket.org/ckvist/twilio (Has tools for generating TwiML, but no lookup or call/msg listing)