Go SDK

    The Plivo Go SDK makes it simpler to integrate voice and SMS communications into your Go applications using the Plivo REST APIs. Using the SDK, you’ll be able to make voice calls, send SMS messages, and generate Plivo XML documents to control your call flows.

    Prerequisites

    • Go >= 1.7.x

    Installation

    To install the stable release

    You can install the stable release using the go command.

    $ go get github.com/plivo/plivo-go
    

    You can also install by cloning the github.com/plivo/plivo-go repository into your GOPATH.

    To install a beta release

    Note: You can see the full list of Go SDK releases on GitHub.

    1. In terminal, create a new folder called test-plivo-beta.

       $ mkdir test-plivo-beta
      

      Note: Make sure the new folder is outside your GOPATH.

    2. Change your directory to the new folder.
    3. Using the following command, initialize a new module:

       $ go mod init github.com/plivo/beta
      

      You’ll see the following return:

       $ go mod init github.com/plivo/beta
      
    4. Next, create a new go file with this code:

       package main
      
       import (
       "fmt"
       "github.com/plivo/plivo-go"
       )
      
       const authId  = "auth_id"
       const authToken = "auth_token"
      
       func main() {
       	testPhloGetter()
       }
      
       func testPhloGetter() {
       	phloClient,err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{})
       	if err != nil {
       		panic(err)
       	}
       	response, err := phloClient.Phlos.Get("phlo_id")
       	if err != nil {
       		panic(err)
       	}
       	fmt.Printf("Response: %#v\n", response)
       }
      

      Note: Replace the placeholder strings in this listing with your auth_id and auth_token before you initialize the code. You can find your authentication credentials on the Overview page of the Plivo console.

    5. Run the go build command to build the packages:

       $ go build
      

      payload_defined

      A file named go.mod will be generated.

    6. Edit go.mod using the command vim go.mod and change the plivo-go version to the beta version you want to download.

      payload_defined

      For example, change

       github.com/plivo/plivo-go v4.0.5+incompatible
      

      to

       github.com/plivo/plivo-go v4.0.6-beta1
      
    7. Save the go.mod file.

    8. Run go build to build the packages.

      go.mod will be updated with the beta version.

    You can now use the features available in the beta branch.

    Getting started

    Authentication

    To make API requests, you need to create a Client and provide it with authentication credentials, which you can find on the Overview page of the Plivo console.

    We recommend that you store your credentials in the PLIVO_AUTH_ID and the PLIVO_AUTH_TOKEN environment variables, to avoid the possibility of accidentally committing them to source control. If you do this, you can initialize the client with no arguments and it will automatically fetch them from the environment variables:

    package main
    
    import "github.com/plivo/plivo-go"
    
    func main()  {
      client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
      if err != nil {
        panic(err)
      }
    }
    

    Alternatively, you can specify the authentication credentials while initializing the Client.

    package main
    
    import "github.com/plivo/plivo-go"
    
    func main()  {
     client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
     if err != nil {
       panic(err)
     }
    }
    

    The basics

    The SDK uses consistent interfaces to create, retrieve, update, delete, and list resources. The pattern is:

    client.Resources.Create(Params{}) // Create
    client.Resources.Get(Id) // Get
    client.Resources.Update(Id, Params{}) // Update
    client.Resources.Delete(Id) // Delete
    client.Resources.List() // List all resources, max 20 at a time
    

    Using client.Resources.List() lists the first 20 resources by default (the first page, with limit as 20, and offset as 0). Use limit and offset to get more pages of resources.

    Examples

    Send a message

    package main
    
    import "github.com/plivo/plivo-go"
    
    func main()  {
      client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
      if err != nil {
        panic(err)
      }
      client.Messages.Create(plivo.MessageCreateParams{
        Src: "the_source_number",
        Dst: "+14157654321",
        Text: "Hello, world!",
      })
    }
    

    Make a call

    package main
    
    import "github.com/plivo/plivo-go"
    
    func main()  {
      client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
      if err != nil {
        panic(err)
      }
      client.Calls.Create(plivo.CallCreateParams{
        From: "the_source_number",
        To: "+14157654321",
        AnswerURL: "http://answer.url",
      })
    }
    

    Generate Plivo XML

    package main
    
    import "github.com/plivo/plivo-go/plivo/xml"
    
    func main()  {
      println(xml.ResponseElement{
        Contents: []interface{}{
          new(xml.SpeakElement).AddSpeak("Hello, world!"),
        },
        }.String())
    }
    

    This generates the XML code:

    <Response>
      <Speak>Hello, world!</Speak>
    </Response>
    

    Run a PHLO

    package main
    
    import (
    	"fmt"
    	"plivo-go"
    )
    
    // Initialize these params with corresponding values to trigger resources
    
    const authId  = "auth_id"
    const authToken = "auth_token"
    const phloId = "phlo_id"
    
    // with payload in request
    
    func main() {
    	testPhloRunWithParams()
    }
    
    func testPhloRunWithParams() {
    	phloClient,err := plivo.NewPhloClient(authId, authToken, &plivo.ClientOptions{})
    	if err != nil {
    		panic(err)
    	}
    	phloGet, err := phloClient.Phlos.Get(phloId)
    	if err != nil {
    		panic(err)
    	}
    	//pass corresponding from and to values
    	type params map[string]interface{}
    	response, err := phloGet.Run(params{
    		"from": "111111111",
    		"to": "2222222222",
    	})
    
    	if (err != nil) {
    		println(err)
    	}
    	fmt.Printf("Response: %#v\n", response)
    }
    

    More examples

    Refer to the Plivo API Reference documentation for more examples. Also refer to our guide to setting up a dev environment for details on how to set up a simple Go server and use it to test out your integration in under 5 minutes.

    Reporting issues

    Report feedback or problems with this SDK by opening an issue on GitHub.