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/v7

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/v7"
 )

 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)
 }

    Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phlo_id placeholder with your PHLO ID from 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/v7"

func main()  {
  client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
  if err != nil {
    panic(err)
  }
}

Replace the auth placeholders with your authentication credentials from the Plivo console.

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

package main

import "github.com/plivo/plivo-go/v7"

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/v7"

func main()  {
  client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
  if err != nil {
    panic(err)
  }
  client.Messages.Create(plivo.MessageCreateParams{
    Src: "<caller_id>",
    Dst: "<destination_number>",
    Text: "Hello, world!",
  })
}

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phone number placeholders with actual phone numbers in E.164 format (for example, +12025551234).

Make a call

package main

import "github.com/plivo/plivo-go/v7"

func main()  {
  client, err := plivo.NewClient("<auth_id>","<auth_token>", &plivo.ClientOptions{})
  if err != nil {
    panic(err)
  }
  client.Calls.Create(plivo.CallCreateParams{
    From: "<caller_id>",
    To: "<destination_number>",
    AnswerURL: "https://<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 {
			fmt.Print("Error", err.Error())
			return
		}
	phloGet, err := phloClient.Phlos.Get(phloId)
	if err != nil {
			fmt.Print("Error", err.Error())
			return
		}
	//pass corresponding from and to values
	type params map[string]interface{}
	response, err := phloGet.Run(params{
		"from": "<caller_id>",
		"to": "<destination_number>",
	})

	if (err != nil) {
		println(err)
	}
	fmt.Printf("Response: %#v\n", response)
}

Replace the auth placeholders with your authentication credentials from the Plivo console. Replace the phlo_id placeholder with your PHLO ID from the Plivo console. Replace the phone number placeholders with actual phone numbers in E.164 format (for example, +12025551234).

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 expose that server to the internet.

Reporting issues

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