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/Bijles-aan-Huis-B-V/messagebird-go-rest-api

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/Bijles-aan-Huis-B-V/messagebird-go-rest-api"

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/Bijles-aan-Huis-B-V/messagebird-go-rest-api"
import "github.com/Bijles-aan-Huis-B-V/messagebird-go-rest-api/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/Bijles-aan-Huis-B-V/messagebird-go-rest-api/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)
}

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) 2022 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 SetErrorReader(r errorReader)
• type Client
• type DefaultClient
  • func New(accessKey string) *DefaultClient
  • func (c *DefaultClient) 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 PaginationRequest
  • func (cpr *PaginationRequest) QueryParams() string
• type Price
• type Recipient
• type Recipients
• type Secret

Constants

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

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

Variables

var DefaultPagination = &PaginationRequest{
	Limit:  20,
	Offset: 0,
}

DefaultPagination provides reasonable values for List requests.

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 SetErrorReader

func SetErrorReader(r errorReader)

SetErrorReader takes an errorReader that must parse raw JSON errors

Types

type Client

type Client interface {
	Request(v interface{}, method, path string, data interface{}) error
}

type DefaultClient

type DefaultClient 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.
}

DefaultClient 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) *DefaultClient

New creates a new MessageBird client object.

func (*DefaultClient) Request

func (c *DefaultClient) 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

type PaginationRequest

type PaginationRequest struct {
	Limit, Offset int
}

PaginationRequest can be used to set pagination options in List().

func (*PaginationRequest) QueryParams

func (cpr *PaginationRequest) QueryParams() string

type Price

type Price struct {
	Amount   int
	Currency string
}

type Recipient

type Recipient struct {
	Recipient              int64
	Status                 string
	StatusDatetime         *time.Time
	RecipientCountry       *string
	RecipientCountryPrefix *int
	RecipientOperator      *string
	MessageLength          *int
	StatusErrorCode        *int
	StatusReason           *string
	Price                  *Price
	Mccmnc                 *string
	Mcc                    *string
	Mnc                    *string
	MessagePartCount       int
}

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.

type Secret

type Secret struct {
	Key      string            `json:"key"`
	Channels map[string]string `json:"channels"`
}