twilio

twilio-go

Project Status

This project is currently in PILOT and in active development. If you've identified an issue, please open an issue. If you would like to particulate in the pilot, please sign up for Twilio Insiders twil.io/insider.

All the code here was generated by twilio-oai-generator by leveraging openapi-generator and twilio-oai. If you find an issue with the generation or the openapi specs, please go ahead and open an issue or a PR against the relevant repositories.

Documentation

The documentation for the Twilio API can be found here.

The Go library documentation can be found here.

Supported Go Versions

This library supports the following Go implementations:

• 1.15
• 1.16

Installation

To use twilio-go in your project initialize go modules then run:

go get github.com/twilio/twilio-go

Getting Started

Getting started with the Twilio API couldn't be easier. Create a Client and you're ready to go.

API Credentials

The Twilio Client needs your Twilio credentials. You should pass these directly to the constructor (see the code below).

package main
import "github.com/twilio/twilio-go"

func main(){
    accountSid := "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    authToken := "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
    client := twilio.NewRestClient(accountSid, authToken)
}

package main
import "github.com/twilio/twilio-go/twilio"

func main(){
    accountSid := "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
    authToken := "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
	subaccountSid := "ACYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
	client := twilio.NewRestClientWithParams(accountSid, authToken, twilio.RestClientParams{
		AccountSid: subaccountSid,
	})
}

We suggest storing your credentials as environment variables and then use it in your code. Why? You'll never have to worry about committing your credentials and accidentally posting them somewhere public.

package main
import (
	"github.com/twilio/twilio-go"
	"os"
)

func main(){
    accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
    authToken := os.Getenv("TWILIO_AUTH_TOKEN")
    client := twilio.NewRestClient(accountSid, authToken)
}

Specify a Region and/or Edge

package main

import (
	"github.com/twilio/twilio-go"
	"os"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_TOKEN")
	client := twilio.NewRestClient(accountSid, authToken)
	client.SetRegion("au1")
	client.SetEdge("sydney")
}

This will result in the hostname transforming from api.twilio.com to api.sydney.au1.twilio.com.

A Twilio client constructed without these parameters will also look for TWILIO_REGION and TWILIO_EDGE variables inside the current environment.

Buy a phone number

package main
import (
	"fmt"
	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/api/v2010"
	"os"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_TOKEN")
	phoneNumber := "AVAILABLE_TWILIO_PHONE_NUMBER"
	subaccountSid := os.Getenv("TWILIO_SUBACCOUNT_SID")

	client := twilio.NewRestClientWithParams(accountSid, authToken, twilio.RestClientParams{
		AccountSid: subaccountSid,
	})

	params := &openapi.CreateIncomingPhoneNumberParams{}
	params.SetPhoneNumber(phoneNumber)

	resp, err := client.ApiV2010.CreateIncomingPhoneNumber(params)
	if err != nil {
		fmt.Println(err.Error())
		err = nil
	} else {
		fmt.Println("Phone Number Status: " + *resp.Status)
	}
}

Send a text message

package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/api/v2010"
	"os"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_TOKEN")
	from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
	to := os.Getenv("TWILIO_TO_PHONE_NUMBER")
	subaccountSid := os.Getenv("TWILIO_SUBACCOUNT_SID")

	client := twilio.NewRestClientWithParams(accountSid, authToken, twilio.RestClientParams{
		AccountSid: subaccountSid,
	})

	params := &openapi.CreateMessageParams{}
	params.SetTo(to)
	params.SetFrom(from)
	params.SetBody("Hello there")

	resp, err := client.ApiV2010.CreateMessage(params)
	if err != nil {
		fmt.Println(err.Error())
		err = nil
	} else {
		response, _ := json.Marshal(*resp)
		fmt.Println("Response: " + string(response))
    }
}

Make a call

package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/api/v2010"
	"os"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_TOKEN")
	from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
	to := os.Getenv("TWILIO_TO_PHONE_NUMBER")

	client := twilio.NewRestClient(accountSid, authToken)

	params := &openapi.CreateCallParams{}
	params.SetTo(to)
	params.SetFrom(from)
	params.SetUrl("http://twimlets.com/holdmusic?Bucket=com.twilio.music.ambient")

	resp, err := client.ApiV2010.CreateCall(params)
	if err != nil {
		fmt.Println(err.Error())
		err = nil
	} else {
		fmt.Println("Call Status: " + *resp.Status)
		fmt.Println("Call Sid: " + *resp.Sid)
		fmt.Println("Call Direction: " + *resp.Direction)
	}
}

Create a Serverless Function

package main

import (
	"fmt"
	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/serverless/v1"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_SID")
	serviceSid := "ZSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
	friendlyName := "My Serverless func"

	client := twilio.NewRestClient(accountSid, authToken)

	params := &openapi.CreateFunctionParams{
		FriendlyName: &friendlyName,
	}

	resp, err := client.ServerlessV1.CreateFunction(serviceSid, params)
	if err != nil {
		fmt.Println(err.Error())
		err = nil
	} else {
		fmt.Println(*resp.Sid)
	}
}

Create a Studio Flow

package main

import (
	"encoding/json"
	"fmt"
	"os"

	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/studio/v2"
)

func main() {
	accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
	authToken := os.Getenv("TWILIO_AUTH_TOKEN")

	var jsonStr = `{
   "description":"Twilio Studio flow service",
   "initial_state":"Trigger",
   "states":[
      {
         "properties":{
            "offset":{
               "y":0,
               "x":0
            }
         },
         "transitions":[
            
         ],
         "name":"Trigger",
         "type":"trigger"
      }
   ]
}`

	definition := make(map[string]interface{})
	_ = json.Unmarshal([]byte(jsonStr), &definition)

	client := twilio.NewRestClient(accountSid, authToken)
	params := &openapi.CreateFlowParams{
		Definition: &definition,
	}
	params.SetCommitMessage("commit")
	params.SetFriendlyName("Studio flow from Go")
	params.SetStatus("draft")

	resp, err := client.StudioV2.CreateFlow(params)
	if err != nil {
		fmt.Println(err.Error())
	} else {
		fmt.Println(*resp.Sid)
	}
}

Handling Exceptions

package main
import (
	"fmt"
	"os"

	"github.com/twilio/twilio-go/framework/error"
	"github.com/twilio/twilio-go"
	openapi "github.com/twilio/twilio-go/rest/api/v2010"
)

func main() {
    accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
    authToken := os.Getenv("TWILIO_AUTH_TOKEN")
    phoneNumber := os.Getenv("TWILIO_PHONE_NUMBER")

    client := twilio.NewRestClient(accountSid, authToken)

    params := &openapi.CreateIncomingPhoneNumberParams{}
    params.SetPhoneNumber(phoneNumber)

    resp, err := client.ApiV2010.CreateIncomingPhoneNumber(accountSid, params)
    if err != nil {
        twilioError := err.(*error.TwilioRestError)
        fmt.Println(twilioError.Error())
    }
}

For more descriptive exception types, please see the Twilio documentation.

Building

To build twilio-go run:

go build ./...

Testing

To execute the test suite run:

go test ./...

Generating Local Documentation

To generate documentation, from the root directory:

godoc -http=localhost:{port number}

Then, navigate to http://localhost:{port number}/pkg/github.com/twilio/twilio-go in your local browser.

Example:

godoc -http=localhost:6060

http://localhost:6060/pkg/github.com/twilio/twilio-go