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://www.messagebird.com/developers/go.

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 := client.Balance()
if err != nil {
  // messagebird.ErrResponse means custom JSON errors.
  if err == messagebird.ErrResponse {
    for _, mbError := range balance.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://www.messagebird.com/developers/go.

License

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

Documentation

Index

• Constants
• Variables
• type Balance
• type Client
  • func New(AccessKey string) *Client
  • func (c *Client) Balance() (*Balance, error)
  • func (c *Client) HLR(id string) (*HLR, error)
  • func (c *Client) Lookup(phoneNumber string, params *LookupParams) (*Lookup, error)
  • func (c *Client) LookupHLR(phoneNumber string, params *LookupParams) (*HLR, error)
  • func (c *Client) Message(id string) (*Message, error)
  • func (c *Client) NewHLR(msisdn, reference string) (*HLR, error)
  • func (c *Client) NewLookupHLR(phoneNumber string, params *LookupParams) (*HLR, error)
  • func (c *Client) NewMessage(originator string, recipients []string, body string, msgParams *MessageParams) (*Message, error)
  • func (c *Client) NewVoiceMessage(recipients []string, body string, params *VoiceMessageParams) (*VoiceMessage, error)
  • func (c *Client) OtpGenerate(recipient string, params *OtpParams) (*OtpMessage, error)
  • func (c *Client) OtpVerify(recipient string, token string, params *OtpParams) (*OtpMessage, error)
  • func (c *Client) VoiceMessage(id string) (*VoiceMessage, error)
• type Error
• type Formats
• type HLR
• type Lookup
• type LookupParams
• type Message
• type MessageParams
• type OtpMessage
• type OtpParams
• type Recipient
• type Recipients
• type TypeDetails
• type VoiceMessage
• type VoiceMessageParams

Constants

const (
	ClientVersion = "2.3.0"
	Endpoint      = "https://rest.messagebird.com"
)

Variables

var (
	ErrResponse           = errors.New("The MessageBird API returned an error")
	ErrUnexpectedResponse = errors.New("The MessageBird API is currently unavailable")
)

Types

type Balance

type Balance struct {
	Payment string
	Type    string
	Amount  float32
	Errors  []Error
}

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
}

func New

func New(AccessKey string) *Client

New creates a new MessageBird client object.

func (*Client) Balance

func (c *Client) Balance() (*Balance, error)

Balance returns the balance information for the account that is associated with the access key.

func (*Client) HLR

func (c *Client) HLR(id string) (*HLR, error)

HLR looks up an existing HLR object for the specified id that was previously created by the NewHLR function.

func (*Client) Lookup

func (c *Client) Lookup(phoneNumber string, params *LookupParams) (*Lookup, error)

Lookup performs a new lookup for the specified number.

func (*Client) LookupHLR

func (c *Client) LookupHLR(phoneNumber string, params *LookupParams) (*HLR, error)

LookupHLR performs a HLR lookup for the specified number.

func (*Client) Message

func (c *Client) Message(id string) (*Message, error)

Message retrieves the information of an existing Message.

func (*Client) NewHLR

func (c *Client) NewHLR(msisdn, reference string) (*HLR, error)

NewHLR retrieves the information of an existing HLR.

func (*Client) NewLookupHLR

func (c *Client) NewLookupHLR(phoneNumber string, params *LookupParams) (*HLR, error)

NewLookupHLR creates a new HLR lookup for the specified number.

func (*Client) NewMessage

func (c *Client) NewMessage(originator string, recipients []string, body string, msgParams *MessageParams) (*Message, error)

NewMessage creates a new message for one or more recipients.

func (*Client) NewVoiceMessage

func (c *Client) NewVoiceMessage(recipients []string, body string, params *VoiceMessageParams) (*VoiceMessage, error)

NewVoiceMessage creates a new voice message for one or more recipients.

func (*Client) OtpGenerate

func (c *Client) OtpGenerate(recipient string, params *OtpParams) (*OtpMessage, error)

OtpGenerate generates a new One-Time-Password for one recipient.

func (*Client) OtpVerify

func (c *Client) OtpVerify(recipient string, token string, params *OtpParams) (*OtpMessage, error)

OtpVerify verifies the token that was generated with OtpGenerate.

func (*Client) VoiceMessage

func (c *Client) VoiceMessage(id string) (*VoiceMessage, error)

VoiceMessage retrieves the information of an existing VoiceMessage.

type Error

type Error struct {
	Code        int
	Description string
	Parameter   string
}

type Formats

type Formats struct {
	E164          string
	International string
	National      string
	Rfc3966       string
}

type HLR

type HLR struct {
	Id              string
	HRef            string
	MSISDN          int
	Network         int
	Reference       string
	Status          string
	Details         map[string]interface{}
	CreatedDatetime *time.Time
	StatusDatetime  *time.Time
	Errors          []Error
}

type Lookup

type Lookup struct {
	Href          string
	CountryCode   string
	CountryPrefix int
	PhoneNumber   int64
	Type          string
	Formats       Formats
	HLR           *HLR
}

type LookupParams

type LookupParams struct {
	CountryCode string
	Reference   string
}

type Message

type Message struct {
	Id                string
	HRef              string
	Direction         string
	Type              string
	Originator        string
	Body              string
	Reference         string
	Validity          *int
	Gateway           int
	TypeDetails       TypeDetails
	DataCoding        string
	MClass            int
	ScheduledDatetime *time.Time
	CreatedDatetime   *time.Time
	Recipients        Recipients
	Errors            []Error
}

type MessageParams

type MessageParams struct {
	Type              string
	Reference         string
	Validity          int
	Gateway           int
	TypeDetails       TypeDetails
	DataCoding        string
	ScheduledDatetime time.Time
}

type OtpMessage

type OtpMessage struct {
	Id                 string
	Recipient          string
	Reference          string
	Status             string
	Href               map[string]string `json:"href"`
	CreatedDatetime    *time.Time
	ValidUntilDatetime *time.Time
	Errors             []Error
}

type OtpParams

type OtpParams struct {
	Reference  string
	Originator string
	Type       string
	Language   string
	Voice      string
	Template   string
	DataCoding string
}

type Recipient

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

type Recipients

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

type TypeDetails

type TypeDetails map[string]interface{}

type VoiceMessage

type VoiceMessage struct {
	Id                string
	HRef              string
	Originator        string
	Body              string
	Reference         string
	Language          string
	Voice             string
	Repeat            int
	IfMachine         string
	ScheduledDatetime *time.Time
	CreatedDatetime   *time.Time
	Recipients        Recipients
	Errors            []Error
}

type VoiceMessageParams

type VoiceMessageParams struct {
	Originator        string
	Reference         string
	Language          string
	Voice             string
	Repeat            int
	IfMachine         string
	ScheduledDatetime time.Time
}