Set Up a Go Dev Environment for Messaging

    Using this guide, you can set up a development environment in five minutes to trigger API requests related to our Messaging API. It also shows how to send and receive messages using tunneling software to expose the local dev server to the public internet.

    Install Go, Gin, and the Plivo Go SDK

    To get started, install and set up Go, the Gin web framework, and Plivo’s Go SDK.

    You can install Go from the official installer. To set up the other packages, first create a project directory using the command mkdir mygoapp, then change to that directory and install the Gin and Plivo packages using the go command.

    go get github.com/gin-gonic/gin
    go get github.com/plivo/plivo-go
    

    Alternatively, you can install them by cloning the Plivo Go repository and Gin repository into your GOPATH.

    Trigger an API request

    Now you can create a file in the project directory and execute code to trigger any Plivo API. Here’s some example code that sends an SMS message. Create a file called SendSMS.go and paste into it this code.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    
    package main
    
    import (
    	"fmt"
    
    	"github.com/gin-gonic/gin"
    	"github.com/plivo/plivo-go"
    )
    
    func main() {
    	r := gin.Default()
    	r.GET("/outbound-sms", func(c *gin.Context) {
    		c.Header("Content-Type", "application/JSON")
    		client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    		if err != nil {
    			panic(err)
    		}
    		response, err := client.Messages.Create(
    			plivo.MessageCreateParams{
    				Src:  "<Caller_ID>",
    				Dst:  "<Destination_Number>",
    				Text:  "Hello from Go-gin",
    			},
    		)
    		if err != nil {
    			panic(err)
    		}
    		fmt.Printf("Response: %#v\n", response)
    		c.JSON(200, response)
    	})
    	r.Run() // listen and serve on 0.0.0.0:8080 (for windows "localhost:8080")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    
    package main
    
    import (
    	"fmt"
    
    	"github.com/gin-gonic/gin"
    	"github.com/plivo/plivo-go"
    )
    
    func main() {
    	r := gin.Default()
    	r.GET("/outbound-mms", func(c *gin.Context) {
    		c.Header("Content-Type", "application/JSON")
    		client, err := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})
    		if err != nil {
    			panic(err)
    		}
    		response, err := client.Messages.Create(
    			plivo.MessageCreateParams{
    				Src:  "<Caller_ID>",
    				Dst:  "<Destination_Number>",
    				Text:  "Hello from Go-gin",
    				Type: "mms",
                    MediaUrls: []string{"https://media.giphy.com/media/26gscSULUcfKU7dHq/source.gif"},
                    MediaIds: []string{"801c2056-33ab-499c-80ef-58b574a462a2"},
    			},
    		)
    		if err != nil {
    			panic(err)
    		}
    		fmt.Printf("Response: %#v\n", response)
    		c.JSON(200, response)
    	})
    	r.Run() // listen and serve on 0.0.0.0:8080 (for Windows "localhost:8080")
    }
    
    Note:
    • Replace the placeholders <auth_id> and <auth_token> with your authentication credentials, which you can find on the overview page of the Plivo console.
    • We recommend that you store your credentials in the auth_id and 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 the values from the environment variables.
    • Replace the placeholder <Caller_ID> with a phone number you’ve purchased, and <Destination_Number> with the phone number you’ll be calling. Both phone numbers should be in E.164 format.

    Save the file and run it.

    go run SendSMS.go
    

    You should see your basic server application in action on http://localhost:8080/receive_sms/.

    You can follow the same approach to trigger any other API requests. Please refer to the detailed API reference to check all the API requests available on the Voice API platform.

    Set up a Gin-Gonic server to serve XML and manage callbacks

    Now that we’ve sent a message, let’s set up an Gin server to handle incoming messages.

    Plivo supports receiving SMS text messages in several countries (see complete SMS API coverage). When someone sends a text message to a Plivo phone number, you can receive it on your server by setting a Message URL in your Plivo application. Plivo sends the message, along with other parameters, to your Message URL.

    Set up a Gin server

    Use this code snippet to start a local server.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    
    package main
    
    import (
      "net/http"
      "github.com/gin-gonic/gin"
    )
    
    func main() {
      r := gin.Default()
      r.GET("/receive_sms", func(c *gin.Context) {
         fromnumber := c.Query("From")
         tonumber := c.Query("To")
         text := c.Query("Text")
         c.String(http.StatusOK, "Message Received %s %s %s", fromnumber, tonumber, text)
      })
      r.Run() // listen and serve on 0.0.0.0:8080 (for Windows "localhost:8080")
    }
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    
    package main
    
    import (
      "net/http"
      "github.com/gin-gonic/gin"
    )
    
    func main() {
      r := gin.Default()
      r.GET("/receive_mms", func(c *gin.Context) {
         fromnumber := c.Query("From")
         tonumber := c.Query("To")
         text := c.Query("Text")
         media := c.Query("Media0")
         c.String(http.StatusOK, "Message Received %s %s %s %s", fromnumber, tonumber, text, media)
      })
      r.Run() // listen and serve on 0.0.0.0:8080 (for Windows "localhost:8080")
    }
    

    Save this code in any file — we called ours receive_sms.go. To run this file on the server, go to the folder where the file resides and enter

    go run receive_sms.go
    
    Note:
    • Replace the placeholders <auth_id> and <auth_token> with your authentication credentials, which you can find on the overview page of the Plivo console.
    • We recommend that you store your credentials in the auth_id and 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 the values from the environment variables.
    • You can use the Environment.SetEnvironmentVariable method to store environment variables, and fetch them using the Environment.GetEnvironmentVariable method while initializing the client.
    • Replace the placeholder <Caller_ID> with a phone number you’ve purchased, and <Destination_Number> with the phone number you’ll be calling. Both phone numbers should be in E.164 format.

    Ngrok setup

    To serve XML documents, your local server must connect with Plivo API services. For that, we recommend using ngrok, which exposes local servers running behind NATs and firewalls to the public internet over secure tunnels. Using ngrok, you can set webhooks that can talk to the Plivo server.

    ngrok block diagram

    Install ngrok and run it on the command line, specifying the port that hosts the application on which you want to receive messages (8080 in this case):

    ./ngrok http 8080
    

    This starts the ngrok server on your local server. Ngrok will display a forwarding link that you can use as a webhook to access your local server over the public network. You should be able to see your basic server application in action at https://<nrgok_URL>/inbound/.

    Sample ngrok CLI

    Now people can send messages to your Plivo number.

    You can follow the same approach to serve other XML documents to manage call flows. Refer to our detailed XML reference to see all the XML elements available on the Messaging API platform.