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 developers sections
• 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

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"

Then, create an instance of messagebird.Client:

client := messagebird.New("test_gshuPaZoeEG6ovbc8M79w0QyM")

Now you can query the API for information or send data. For example, if we want to request our balance information you'd do something like this:

// Request the balance information, returned as a Balance object.
balance, err := balance.Read(client)
if err != nil {
	switch errResp := err.(type) {
	case messagebird.ErrorResponse:
		for _, mbError := range errResp.Errors {
			fmt.Printf("Error: %#v\n", mbError)
		}
	}

	return
}

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.

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 uprading 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
• type Client
  • func New(accessKey string) *Client
  • 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 Recipient
• type Recipients

Constants

const (
	// ClientVersion is used in User-Agent request header to provide server with API level.
	ClientVersion = "5.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")
)

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
}

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