messagebird

README

MessageBird's REST API for Go

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

Requirements

• 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

Installation

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

$ go get github.com/messagebird/go-rest-api/v7

Examples

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 "github.com/messagebird/go-rest-api/v7"

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.
	return
}

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

Errors

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 "github.com/messagebird/go-rest-api/v7"
import "github.com/messagebird/go-rest-api/v7/sms"

// ...

_, 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 "github.com/messagebird/go-rest-api/v7/voice"

// ...

_, 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.

	client.EnableFeatures(messagebird.FeatureConversationsAPIWhatsAppSandbox)

Documentation

Complete documentation, instructions, and examples are available at: https://developers.messagebird.com.

Upgrading

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

License

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

Documentation

Overview

Package messagebird is an official library for interacting with MessageBird.com API. The MessageBird API connects your website or application to operators around the world. With our API you can integrate SMS, Chat & Voice. More documentation you can find on the MessageBird developers portal: https://developers.messagebird.com/

Index

• Constants
• Variables
• func SetVoiceErrorReader(r errorReader)
• type Client
  • func New(accessKey string) *Client
  • func (c *Client) DisableFeatures(feature Feature)
  • func (c *Client) EnableFeatures(feature Feature)
  • func (c *Client) IsFeatureEnabled(feature Feature) bool
  • func (c *Client) Request(v interface{}, method, path string, data interface{}) error
• type Error
  • func (e Error) Error() string
• type ErrorResponse
  • func (r ErrorResponse) Error() string
• type Feature
• type Recipient
• type Recipients

Constants

const (
	// ClientVersion is used in User-Agent request header to provide server with API level.
	ClientVersion = "7.1.0"

	// Endpoint points you to MessageBird REST API.
	Endpoint = "https://rest.messagebird.com"
)

Variables

var (
	// ErrUnexpectedResponse is used when there was an internal server error and nothing can be done at this point.
	ErrUnexpectedResponse = errors.New("The MessageBird API is currently unavailable")
)

Functions

func SetVoiceErrorReader

func SetVoiceErrorReader(r errorReader)

SetVoiceErrorReader takes an errorReader that must parse raw JSON errors returned from the Voice API.

Types

type Client

type Client struct {
	AccessKey  string       // The API access key.
	HTTPClient *http.Client // The HTTP client to send requests on.
	DebugLog   *log.Logger  // Optional logger for debugging purposes.
	// contains filtered or unexported fields
}

Client is used to access API with a given key. Uses standard lib HTTP client internally, so should be reused instead of created as needed and it is safe for concurrent use.

func New

func New(accessKey string) *Client

New creates a new MessageBird client object.

func (*Client) DisableFeatures

func (c *Client) DisableFeatures(feature Feature)

DisableFeatures disables a feature.

func (*Client) EnableFeatures

func (c *Client) EnableFeatures(feature Feature)

EnableFeatures enables a feature.

func (*Client) IsFeatureEnabled

func (c *Client) IsFeatureEnabled(feature Feature) bool

IsFeatureEnabled checks if a feature is enabled.

func (*Client) Request

func (c *Client) Request(v interface{}, method, path string, data interface{}) error

Request is for internal use only and unstable.

type Error

type Error struct {
	Code        int
	Description string
	Parameter   string
}

Error holds details including error code, human readable description and optional parameter that is related to the error.

func (Error) Error

func (e Error) Error() string

Error implements error interface.

type ErrorResponse

type ErrorResponse struct {
	Errors []Error `json:"errors"`
}

ErrorResponse represents errored API response.

func (ErrorResponse) Error

func (r ErrorResponse) Error() string

Error implements error interface.

type Feature

type Feature int

A Feature can be enabled

const (
	// FeatureConversationsAPIWhatsAppSandbox Enables the WhatsApp sandbox for conversations API.
	FeatureConversationsAPIWhatsAppSandbox Feature = iota
)

type Recipient

type Recipient struct {
	Recipient      int64
	Status         string
	StatusDatetime *time.Time
}

Recipient struct holds information for a single msisdn with status details.

type Recipients

type Recipients struct {
	TotalCount               int
	TotalSentCount           int
	TotalDeliveredCount      int
	TotalDeliveryFailedCount int
	Items                    []Recipient
}

Recipients holds a collection of Recepient structs along with send stats.