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.
The documentation for the Twilio API can be found here.
The Go library documentation can be found here.
This library supports the following Go implementations:
- Go 1.15
- Go 1.16
- Go 1.17
To use twilio-go in your project initialize go modules then run:
go get github.com/twilio/twilio-goGetting started with the Twilio API couldn't be easier. Create a
RestClient and you're ready to go.
The Twilio RestClient needs your Twilio credentials. You can either pass these directly to the constructor (see the code below), or use environment variables.
package main
import "github.com/twilio/twilio-go"
func main() {
accountSid := "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
authToken := "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
client := twilio.NewRestClientWithParams(twilio.RestClientParams{
Username: accountSid,
Password: authToken,
})
}Alternatively, a RestClient constructor without these parameters will look for TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN variables inside the current environment.
We suggest storing your credentials as environment variables. 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"
func main() {
client := twilio.NewRestClient()
}Make API calls with a SubAccount by setting the AccountSid field in the twilio.RestClientParams:
package main
import "github.com/twilio/twilio-go"
func main() {
subaccountSid := "ACYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY"
client := twilio.NewRestClientWithParams(twilio.RestClientParams{
AccountSid: subaccountSid,
})
}package main
import (
"github.com/twilio/twilio-go"
"os"
)
func main() {
client := twilio.NewRestClient()
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.
package main
import (
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
"os"
)
func main() {
phoneNumber := "AVAILABLE_TWILIO_PHONE_NUMBER"
subaccountSid := os.Getenv("TWILIO_SUBACCOUNT_SID")
client := twilio.NewRestClientWithParams(twilio.RestClientParams{
AccountSid: subaccountSid,
})
params := &openapi.CreateIncomingPhoneNumberParams{}
params.SetPhoneNumber(phoneNumber)
resp, err := client.ApiV2010.CreateIncomingPhoneNumber(params)
if err != nil {
fmt.Println(err.Error())
} else {
fmt.Println("Phone Number Status: " + *resp.Status)
}
}package main
import (
"encoding/json"
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
"os"
)
func main() {
from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
to := os.Getenv("TWILIO_TO_PHONE_NUMBER")
subaccountSid := os.Getenv("TWILIO_SUBACCOUNT_SID")
client := twilio.NewRestClientWithParams(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())
} else {
response, _ := json.Marshal(*resp)
fmt.Println("Response: " + string(response))
}
}package main
import (
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
"os"
)
func main() {
from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
to := os.Getenv("TWILIO_TO_PHONE_NUMBER")
client := twilio.NewRestClient()
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())
} else {
fmt.Println("Call Status: " + *resp.Status)
fmt.Println("Call Sid: " + *resp.Sid)
fmt.Println("Call Direction: " + *resp.Direction)
}
}package main
import (
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/serverless/v1"
)
func main() {
serviceSid := "ZSxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
client := twilio.NewRestClient()
params := &openapi.CreateFunctionParams{}
params.SetFriendlyName("My Serverless func")
resp, err := client.ServerlessV1.CreateFunction(serviceSid, params)
if err != nil {
fmt.Println(err.Error())
} else {
fmt.Println(*resp.Sid)
}
}package main
import (
"encoding/json"
"fmt"
"os"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/studio/v2"
)
func main() {
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()
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)
}
}This library also offers paging functionality. Collections such as calls and messages have ListXxx and StreamXxx
functions that page under the hood. With both list and stream, you can specify the number of records you want to
receive (limit) and the maximum size you want each page fetch to be (pageSize). The library will then handle the task
for you.
List eagerly fetches all records and returns them as a list, whereas Stream streams the records and lazily retrieves
the pages as you iterate over the collection. You can also page manually using the PageXxx function in each of the
apis.
package main
import (
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
"os"
)
func main() {
from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
client := twilio.NewRestClient()
params := &openapi.ListMessageParams{}
params.SetFrom(from)
params.SetPageSize(20)
params.SetLimit(100)
resp, _ := client.ApiV2010.ListMessage(params)
for record := range resp {
fmt.Println("Body: ", *resp[record].Body)
}
channel, _ := client.ApiV2010.StreamMessage(params)
for record := range channel {
fmt.Println("Body: ", *record.Body)
}
}package main
import (
"encoding/json"
"fmt"
"github.com/twilio/twilio-go"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
"net/url"
"os"
)
func main() {
from := os.Getenv("TWILIO_FROM_PHONE_NUMBER")
client := twilio.NewRestClient()
params := &openapi.ListMessageParams{}
params.SetFrom(from)
params.SetPageSize(20)
var pageToken string
var pageNumber string
resp, err = client.ApiV2010.PageMessage(params, "", "")
if err != nil {
fmt.Println(err)
} else {
fmt.Println(resp.NextPageUri)
u, _ := url.Parse(resp.NextPageUri)
q := u.Query()
pageToken = q.Get("PageToken")
pageNumber = q.Get("Page")
}
resp, err := client.ApiV2010.PageMessage(params, pageToken, pageNumber)
if err != nil {
fmt.Println(err)
} else {
if resp != nil {
fmt.Println(*resp.Messages[0].Body)
}
}
}package main
import (
"fmt"
"os"
"github.com/twilio/twilio-go"
twilioclient "github.com/twilio/twilio-go/client"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
)
func main() {
phoneNumber := os.Getenv("TWILIO_PHONE_NUMBER")
client := twilio.NewRestClient()
params := &openapi.CreateIncomingPhoneNumberParams{}
params.SetPhoneNumber(phoneNumber)
resp, err := client.ApiV2010.CreateIncomingPhoneNumber(params)
if err != nil {
twilioError := err.(*twilioclient.TwilioRestError)
fmt.Println(twilioError.Error())
}
}For more descriptive exception types, please see the Twilio documentation.
Don't want to import the top-level Twilio RestClient with access to the full suite of Twilio products? Use standalone product services instead:
package main
import (
"github.com/twilio/twilio-go/client"
apiv2010 "github.com/twilio/twilio-go/rest/api/v2010"
serverless "github.com/twilio/twilio-go/rest/serverless/v1"
"os"
)
func main() {
accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
authToken := os.Getenv("TWILIO_AUTH_TOKEN")
// Create an instance of our default BaseClient implementation
// You will need to provide your API credentials to the Client manually
defaultClient := &client.Client{
Credentials: client.NewCredentials(accountSid, authToken),
}
defaultClient.SetAccountSid(accountSid)
coreApiService := apiv2010.NewApiServiceWithClient(defaultClient)
serverlessApiService := serverless.NewApiServiceWithClient(defaultClient)
}package main
import (
"fmt"
"net/http"
"net/url"
"os"
"github.com/twilio/twilio-go"
"github.com/twilio/twilio-go/client"
openapi "github.com/twilio/twilio-go/rest/api/v2010"
)
type MyClient struct {
client.Client
}
func (c *MyClient) SendRequest(method string, rawURL string, data url.Values, headers map[string]interface{}) (*http.Response, error) {
// Custom code to pre-process request here
resp, err := c.Client.SendRequest(method, rawURL, data, headers)
// Custom code to pre-process response here
fmt.Println(resp.StatusCode)
return resp, err
}
func main() {
accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
authToken := os.Getenv("TWILIO_AUTH_TOKEN")
customClient := &MyClient{
Client: client.Client{
Credentials: client.NewCredentials(accountSid, authToken),
},
}
customClient.SetAccountSid(accountSid)
twilioClient := twilio.NewRestClientWithParams(twilio.RestClientParams{Client: customClient})
// You may also use custom clients with standalone product services
twilioApiV2010 := openapi.NewApiServiceWithClient(customClient)
}This library supports access token generation for use in the Twilio Client SDKs.
Here's how you would generate a token for the Voice SDK:
package main
import
(
"os"
"github.com/twilio/twilio-go/client/jwt"
)
accountSid := os.Getenv("TWILIO_ACCOUNT_SID")
applicationSid := os.Getenv("TWILIO_TWIML_APP_SID")
apiKey := os.Getenv("TWILIO_API_KEY")
apiSecret := os.Getenv("TWILIO_API_SECRET")
identity := "fake123"
params := jwt.AccessTokenParams{
AccountSid: accountSid,
SigningKeySid: apiKey,
Secret: apiSecret,
Identity: identity,
}
jwtToken := jwt.CreateAccessToken(params)
voiceGrant := &jwt.VoiceGrant{
Incoming: jwt.Incoming{Allow: true},
Outgoing: jwt.Outgoing{
ApplicationSid: applicationSid,
},
}
jwtToken.AddGrant(voiceGrant)
token, err := jwtToken.ToJwt()Creating Capability Token for TaskRouter v1:
package main
import
(
"os"
"github.com/twilio/twilio-go/client/jwt/taskrouter"
)
AccountSid := os.Getenv("TWILIO_ACCOUNT_SID")
AuthToken := os.Getenv("TWILIO_AUTH_TOKEN")
WorkspaceSid := os.Getenv("TWILIO_WORKSPACE_SID")
ChannelID := os.Getenv("TWILIO_CHANNEL_ID")
Params = taskrouter.CapabilityTokenParams{
AccountSid: AccountSid,
AuthToken: AuthToken,
WorkspaceSid: WorkspaceSid,
ChannelID: ChannelID,
}
capabilityToken := taskrouter.CreateCapabilityToken(Params)
token, err := capabilityToken.ToJwt()To build twilio-go run:
go build ./...To execute the test suite run:
go test ./...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:6060http://localhost:6060/pkg/github.com/twilio/twilio-go
The Dockerfile present in this repository and its respective twilio/twilio-go Docker image are currently used by Twilio for testing purposes only.
If you need help installing or using the library, please check the Twilio Support Help Center first, and file a support ticket if you don't find an answer to your question.
If you've instead found a bug in the library or would like new features added, go ahead and open issues or pull requests against this repo!