Skip to content
MessageBird's REST API for Go
Branch: master
Clone or download
marcelcorso Merge pull request #69 from mariuspot/master
Add WhatsApp Sandbox support to Conversations API
Latest commit 6215e0d Aug 20, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
balance Rename package messagebirdtest to mbtest Jul 27, 2018
contact Make all occurences of time.Time pointers Aug 27, 2018
conversation Fixed the case on whatsappSandboxAPIRoot Aug 20, 2019
group Merge branch 'master' into add-conversations Feb 14, 2019
internal/mbtest Changed the test code to use the New method to create the object Aug 19, 2019
lookup Fix error: lookup uses GET Aug 20, 2018
mms Rename package messagebirdtest to mbtest Jul 27, 2018
number Added read, list, search methods for numbers API (#67) Aug 15, 2019
signature Style: Typo Jan 22, 2019
sms fix(api): change method name Jan 29, 2019
verify Add support for Verify retrieval and deletion. Sep 18, 2018
voice Merge pull request #66 from ali-sattari/grow-1091_create-transcript Aug 19, 2019
voicemessage Rename package messagebirdtest to mbtest Jul 27, 2018
.travis.yml Add Travis 1.7 to build jobs. Aug 27, 2018
LICENSE Update the LICENSE file Jan 6, 2015 Added Features to enable Whatsapp Sandbox Aug 16, 2019 Add "other improvements" to Jul 31, 2018
client.go Fixed comment Aug 20, 2019
error.go Changes after review Jul 16, 2018
recipient.go Fix unmarshal error for recipient Oct 29, 2017

MessageBird's REST API for Go

This repository contains the open source Go client for MessageBird's REST API. Documentation can be found at:

Build Status GoDoc


  • Sign up for a free MessageBird account
  • Create a new access key in the dashboard.
  • An application written in Go to make use of this API


The easiest way to use the MessageBird API in your Go project is to install it using go get:

$ go get


Here is a quick example on how to get started. Assuming the go get installation worked, you can import the messagebird package like this:

import ""

Then, create an instance of messagebird.Client. It can be used to access the MessageBird APIs.

// Access keys can be managed through our dashboard.
accessKey := "your-access-key"

// Create a client.
client := messagebird.New(accessKey)

// Request the balance information, returned as a balance.Balance object.
balance, err := balance.Read(client)
if err != nil {
	// Handle error.

// Display the results.
fmt.Println("Payment: ", balance.Payment)
fmt.Println("Type:", balance.Type)
fmt.Println("Amount:", balance.Amount)

This will give you something like:

$ go run example.go
Payment: prepaid
Type: credits
Amount: 9

Please see the other examples for a complete overview of all the available API calls.


When something goes wrong, our APIs can return more than a single error. They are therefore returned by the client as "error responses" that contain a slice of errors.

It is important to notice that the Voice API returns errors with a format that slightly differs from other APIs. For this reason, errors returned by the voice package are of type voice.ErrorResponse. It contains voice.Error structs. All other packages return messagebird.ErrorResponse structs that contain a slice of messagebird.Error.

An example of "simple" error handling is shown in the example above. Let's look how we can gain more in-depth insight in what exactly went wrong:

import ""
import ""

// ...

_, err := sms.Read(client, "some-id")
if err != nil {
	mbErr, ok := err.(messagebird.ErrorResponse)
	if !ok {
		// A non-MessageBird error occurred (no connection, perhaps?) 
		return err
	fmt.Println("Code:", mbErr.Errors[0].Code)
	fmt.Println("Description:", mbErr.Errors[0].Description)
	fmt.Println("Parameter:", mbErr.Errors[0].Parameter)

voice.ErrorResponse is very similar, except that it holds voice.Error structs - those contain only Code and Message (not description!) fields:

import ""

// ...

_, err := voice.CallFlowByID(client, "some-id")
if err != nil {
	vErr, ok := err.(voice.ErrorResponse)
	if !ok {
    		// A non-MessageBird (Voice) error occurred (no connection, perhaps?) 
    		return err
	fmt.Println("Code:", vErr.Errors[0].Code)
	fmt.Println("Message:", vErr.Errors[0].Message)

Conversations WhatsApp Sandbox

To use the whatsapp sandbox you need to enable the FeatureConversationsAPIWhatsAppSandbox feature.



Complete documentation, instructions, and examples are available at:


If you're upgrading from older versions, please read the Messagebird go-rest-api upgrading guide.


The MessageBird REST Client for Go is licensed under The BSD 2-Clause License. Copyright (c) 2014, 2015, MessageBird

You can’t perform that action at this time.