Go API & SDK Docs v7.4.0

This guide walks you through a simple "Hello, World" application that demonstrates the core concepts of PubNub:

• Setting up a connection
• Sending messages
• Receiving messages in real-time

Overview

This guide helps you get up and running with PubNub in your Go application. The Go software development kit (SDK) provides a simple interface for integrating PubNub real-time messaging into your Go applications.

Go's concurrency model with goroutines and channels makes it an excellent choice for building real-time applications that can handle many connections efficiently. Whether you're building a web service, CLI application, or backend system, this guide will show you how to get started with PubNub in Go.

Prerequisites

Before we dive in, make sure you have:

• A basic understanding of Go programming
• Go installed on your machine (version 1.11 or later)
• Your preferred Go IDE or text editor
• A PubNub account (we'll help you set this up!)

Setup

Get your PubNub keys

First, get your PubNub keys:

• Sign in or create an account on the PubNub Admin Portal.
• Create an app (or use an existing one).
• Find your publish and subscribe keys in the app dashboard.

When you create an app, PubNub automatically generates a keyset. You can use the same keyset for development and production, but we recommend separate keysets for each environment to improve security and management.

Install the SDK

SDK version

Always use the latest SDK version to have access to the newest features and avoid security vulnerabilities, bugs, and performance issues.

go get

To integrate PubNub into your Go project using the go get command:

1go get github.com/pubnub/go/v7

If you encounter dependency issues, use the go mod tidy command to resolve them.

go.mod

For projects using Go modules, add the dependency to your go.mod file:

1require github.com/pubnub/go/v7 v7.4.0

Then run:

1go mod tidy

Source code

Clone the GitHub repository:

1git clone https://github.com/pubnub/go.git

View the supported platforms for more information about compatibility.

Steps

Initialize PubNub

In your Go project, create a new file named pubnub_example.go with the following content. This is the minimum configuration you need to send and receive messages with PubNub.

Make sure to replace the demo keys with your app's publish and subscribe keys from the Admin Portal.

1// Import required packages
2package main
3

4import (
5	"fmt"
6

7	pubnub "github.com/pubnub/go/v7"
8)
9

10func main() {
11	// Set up PubNub configuration
12	config := pubnub.NewConfigWithUserId("go-user")
13	config.SubscribeKey = "demo" // Replace with your subscribe key
14	config.PublishKey = "demo"   // Replace with your publish key
15

16	// Create a new PubNub instance
17	pn := pubnub.NewPubNub(config)
18	
19	// Now we can use pn to publish and subscribe
20	fmt.Println("PubNub instance initialized")
21}

show all 21 lines

For more information, refer to the Configuration section of the SDK documentation.

Set up event listeners

Listeners help your application react to events and messages. You can implement custom logic to respond to each type of message or event.

In Go, we use channels to handle asynchronous events. Let's set up listeners for status updates and incoming messages:

1// Create a listener
2listener := pubnub.NewListener()
3

4// Create channels to signal events
5doneConnect := make(chan bool)
6donePublish := make(chan bool)
7

8// Start a goroutine to process events
9go func() {
10	for {
11		select {
12		case status := <-listener.Status:
13			// Handle status events
14			switch status.Category {
15			case pubnub.PNConnectedCategory:
16				// Connected to the PubNub network
17				fmt.Println("Connected to PubNub!")
18				doneConnect <- true
19			case pubnub.PNDisconnectedCategory:
20				// Disconnected from the PubNub network
21				fmt.Println("Disconnected from PubNub!")
22			case pubnub.PNReconnectedCategory:
23				// Reconnected to the PubNub network
24				fmt.Println("Reconnected to PubNub!")
25			}
26			
27		case message := <-listener.Message:
28			// Handle new message
29			fmt.Println("Received message:", message.Message)
30			
31			// Message received, signal to unblock main goroutine
32			donePublish <- true
33			
34		case presence := <-listener.Presence:
35			// Handle presence
36			fmt.Println("Presence event:", presence.Event)
37		}
38	}
39}()
40

41// Add the listener to PubNub
42pn.AddListener(listener)

show all 42 lines

For more information, refer to the Listeners section of the SDK documentation.

Create a subscription

To receive messages sent to a particular channel, you need to subscribe to it. This allows you to receive messages published to that channel in real-time:

1// Define the channel you want to subscribe to
2channel := "my-channel"
3

4// Subscribe to the channel
5pn.Subscribe().
6	Channels([]string{channel}).
7	Execute()
8

9// Wait for the connection to establish
10<-doneConnect
11fmt.Println("Subscribed to channel:", channel)

Publish messages

When you publish a message to a channel, PubNub delivers that message to everyone who is subscribed to that channel.

A message can be any type of JavaScript Object Notation (JSON)-serializable data (such as objects, arrays, integers, strings) that is smaller than 32 KiB.

For more information, refer to the Subscribe section of the SDK documentation.

1// Create a message
2message := map[string]interface{}{
3	"text": "Hello, world!",
4	"sender": "go-sdk",
5}
6

7fmt.Println("Publishing message:", message)
8

9// Publish the message to the channel
10response, _, err := pn.Publish().
11	Channel(channel).
12	Message(message).
13	Execute()
14

15if err != nil {
16	// Handle publish error
17	fmt.Println("Publish error:", err)
18} else {
19	// Handle successful publish
20	fmt.Println("Publish successful! Timetoken:", response.Timestamp)
21}
22

23// Wait for the message to be received (via our listener)
24<-donePublish

show all 24 lines

Run the app

To test your Go application, save the file and run it using:

go run pubnub_example.go

When you run the application, you should see output similar to the following:

1PubNub instance initialized
2Connected to PubNub!
3Subscribed to channel: my-channel
4Publishing message: map[sender:go-sdk text:Hello, world!]
5Publish successful! Timetoken: 16967543908123456
6Received message: map[sender:go-sdk text:Hello, world!]

Complete example

1package main
2

3import (
4	"fmt"
5	"time"
6

7	pubnub "github.com/pubnub/go/v7"
8)
9

10func main() {
11	// Step 1: Initialize PubNub with configuration
12	config := pubnub.NewConfigWithUserId("go-user")
13	config.SubscribeKey = "demo" // Replace with your subscribe key
14	config.PublishKey = "demo"   // Replace with your publish key
15

16	pn := pubnub.NewPubNub(config)
17	fmt.Println("PubNub instance initialized")
18

19	// Step 2: Create event listeners
20	listener := pubnub.NewListener()
21	doneConnect := make(chan bool)
22	donePublish := make(chan bool)
23

24	// Step 3: Set up listener for events
25	go func() {
26		for {
27			select {
28			case status := <-listener.Status:
29				switch status.Category {
30				case pubnub.PNConnectedCategory:
31					fmt.Println("Connected to PubNub!")
32					doneConnect <- true
33				case pubnub.PNDisconnectedCategory:
34					fmt.Println("Disconnected from PubNub!")
35				case pubnub.PNReconnectedCategory:
36					fmt.Println("Reconnected to PubNub!")
37				}
38

39			case message := <-listener.Message:
40				fmt.Println("Received message:", message.Message)
41				donePublish <- true
42			
43			case presence := <-listener.Presence:
44				fmt.Println("Presence event:", presence.Event)
45			}
46		}
47	}()
48

49	// Add the listener to PubNub
50	pn.AddListener(listener)
51

52	// Step 4: Define the channel and subscribe
53	channel := "my-channel"
54	pn.Subscribe().
55		Channels([]string{channel}).
56		Execute()
57

58	// Wait for connection to establish
59	<-doneConnect
60	fmt.Println("Subscribed to channel:", channel)
61

62	// Optional: Wait a moment to ensure subscription is fully set up
63	time.Sleep(1 * time.Second)
64

65	// Step 5: Create and publish a message
66	message := map[string]interface{}{
67		"text":   "Hello, world!",
68		"sender": "go-sdk",
69	}
70

71	fmt.Println("Publishing message:", message)
72

73	// Publish the message
74	response, _, err := pn.Publish().
75		Channel(channel).
76		Message(message).
77		Execute()
78

79	if err != nil {
80		fmt.Println("Publish error:", err)
81	} else {
82		fmt.Println("Publish successful! Timetoken:", response.Timestamp)
83	}
84

85	// Wait for the message to be received
86	<-donePublish
87

88	// Step 6: Clean up (optional)
89	// In a real application, you might want to unsubscribe and clean up resources
90	fmt.Println("Example completed successfully!")
91}

show all 91 lines

Troubleshooting

If you don't see the expected output, here are some common issues and how to fix them:

Issue	Possible Solutions
No connection message	Check your internet connection. Verify your publish and subscribe keys are correct. Make sure you're not behind a firewall blocking PubNub's connections.
Message not received	Double-check that you're subscribed to the correct channel. Verify that the message was actually sent (check for any error messages). Make sure you're waiting long enough for the message to be delivered.
Build errors	Ensure your Go version is up to date. Run go mod tidy to fix dependency issues. Make sure all imports are correct.

Next steps

Great job! 🎉 You've successfully created your first PubNub application with Go. Here are some exciting things you can explore next:

Realtime features

• Set up Presence to track who's online
• Implement channel groups to organize your channels
• Use Signals for lightweight notifications

Advanced features

• Try out Access Manager to secure your channels
• Implement Message Persistence to store and retrieve messages
• Use Push Notifications for mobile devices

Real examples

• Build a chat app in Go
• Explore our GitHub repository for more code samples

More help

• Check out our SDK reference documentation for detailed API information
• Visit our support portal for additional resources
• Ask our AI assistant (the looking glass icon at the top of the page) for help