clickatell

README

Clickatell GO Library

This package provides integration with the Clickatell SMS gateway.

Installation

To acquire the library in your project, simply run:

    go get github.com/arcturial/clickatell-go

Basic Usage

Sending messages relies on the Message object discussed further down. You can integrate either with the HTTP or REST API Clickatell provides. The API objects both provide the same methods and can be used interchangeably.

package main

import (
    "log"
    "github.com/arcturial/clickatell-go"
)

func main() {

    http := clickatell.Http(apiId, "user", "password", nil)

    m := clickatell.Message{
        Destination:    []string{"2"},
        Body:           "Testing",
    }

    httpResp, err := http.Send(m)

    log.Println(err)
    log.Println(httpResp)

    rest := clickatell.Rest("apiToken", nil)

    restResp, err := rest.Send(m)

    log.Println(err)
    log.Println(restResp)
}

Send Response

The Send() function will return a SendResponse object. The response objects are defined as response_[method].go files.

type SendResponse struct {
    Error ErrorResponse `json:"error"`

    Data struct {
        Message []SendResponseMessage `json:"message"`
    } `json:"data"`
}

type SendResponseMessage struct {
    To          string          `json:"to"`
    MessageId   string          `json:"apiMessageId"`
    Error       ErrorResponse   `json:"error"`
}

Interfacing with these response objects can be done as follows:

func main() {

    http := clickatell.Http(apiId, "user", "password", nil)

    m := clickatell.Message{
        Destination:    []string{"2"},
        Body:           "Testing",
    }

    httpResp, err := http.Send(m)

    for _, entry := range httpResp.Data.Message {
        log.Println(entry.Error)
        log.Println(entry.To)
        log.Println(entry.MessageId)
    }
}

Message Object

The message struct represents a Clickatell message and maps to the appropriate API parameters.

type Message struct {
    Binary          bool        // Send the message as binary (optional)
    ClientMsgId     string      // Specify the clientMessageId (optional)
    Concat          int         // Max concatenation value (optional)
    DeliveryQueue   int         // The user queue priority. (optional)
    Destination     []string    // The destination value. (required)
    Callback        int         // The callback type. (optional)
    Escalate        bool        // Specify the escalate value. (optional)
    MaxCredits      int         // The maximum amount of credits to use. (optional)
    Body            string      // The message body (required)
    Mo              bool        // Wether to use MO or not. (optional)
    ScheduledTime   int         // Scheduled delivery time. (optional)
    From            string      // The sender ID or "from" address. (optional)
    Unicode         bool        // Should the message be sent with unicode. (optional)
    ValidityPeriod  int         // How long the message is valid if queued. (optional)
}

Available Methods

Current available methods are:

Send(m Message)

GetBalance()

Note: These will be extended with future versions

Contributing

The library is still in it's initial release and is missing some methods/parameters. Contributions to the available methods or the way the source code is structured or optimized are welcome.

Documentation

Overview

The clickatell package provides integration with the Clickatell SMS gateway.

URL: http://www.clickatell.com

Index

• func Concat(args ...string) string
• func CreateRequest(url string) (*http.Request, error)
• func GetContent(r *http.Response) string
• func MakeQueryString(c *HttpClient, v url.Values) url.Values
• type ClickatellError
  • func MakeError(err ErrorResponse) *ClickatellError
  • func (e *ClickatellError) Error() string
• type ErrorResponse
  • func (e *ErrorResponse) GetError() *ClickatellError
  • func (e *ErrorResponse) HasError() bool
• type GetBalanceResponse
• type HttpClient
  • func Http(apiId int, username string, password string, client *http.Client) *HttpClient
  • func (c *HttpClient) GetBalance() (*GetBalanceResponse, error)
  • func (c *HttpClient) Send(m Message) (*SendResponse, error)
• type LegacyUnwrap
  • func UnwrapLegacyLine(line string) *LegacyUnwrap
  • func (l *LegacyUnwrap) GetError() *ClickatellError
  • func (l *LegacyUnwrap) HasError() bool
• type Message
• type RestClient
  • func Rest(apiToken string, client *http.Client) *RestClient
  • func (c *RestClient) GetBalance() (*GetBalanceResponse, error)
  • func (c *RestClient) Send(in Message) (*SendResponse, error)
• type SendResponse
• type SendResponseMessage

Functions

func Concat

func Concat(args ...string) string

Concat() function will concat all arguments into one string.

func CreateRequest

func CreateRequest(url string) (*http.Request, error)

CreateRequest() function creates a new HTTP get request based on the URL passed to it. It will attach the user agent defined by the "userAgent" constant variable.

func GetContent

func GetContent(r *http.Response) string

GetContent() function will return the http.Response content as a string.

func MakeQueryString

func MakeQueryString(c *HttpClient, v url.Values) url.Values

MakeQueryString() function will create a usable query string prepopulated with the HTTP API credentials.

Types

type ClickatellError

type ClickatellError struct {
	Code string
	// contains filtered or unexported fields
}

The ClickatellError struct is an extension of normal golang errors that allows us to add a Clickatell API error code to error objects

func MakeError

func MakeError(err ErrorResponse) *ClickatellError

MakeError takes an ErrorResponse object from the API and turns it into a golang error

func (*ClickatellError) Error

func (e *ClickatellError) Error() string

Error() function formats the error object to include the API error code as part of the error string

type ErrorResponse

type ErrorResponse struct {
	Description string `json:"description"`
	Code        string `json:"code"`
}

The Clickatell API can return certain errors and these errors are represented by an ErrorResponse object.

func (*ErrorResponse) GetError

func (e *ErrorResponse) GetError() *ClickatellError

GetError() function will return a golang error if the ErrorResponse object has been populated.

func (*ErrorResponse) HasError

func (e *ErrorResponse) HasError() bool

HasError() function will check if an error response has been populated or not.

type GetBalanceResponse

type GetBalanceResponse struct {
	Error ErrorResponse `json:"error"`

	Data struct {
		Balance float64 `json:"balance,string"`
	} `json:"data"`
}

GetBalanceResponse struct represents the response of a "getbalance" API call.

type HttpClient

type HttpClient struct {
	// contains filtered or unexported fields
}

HttpClient represents the Clickatell HTTP API and the credentials required to connect to it.

func Http

func Http(apiId int, username string, password string, client *http.Client) *HttpClient

Http() function will create a new HttpClient based on the authentication credentials and HTTP connection provided. The http.Client is optional and will use a default client if not defined.

func (*HttpClient) GetBalance

func (c *HttpClient) GetBalance() (*GetBalanceResponse, error)

GetBalance() function returns the users balance as per Clickatell account status.

func (*HttpClient) Send

func (c *HttpClient) Send(m Message) (*SendResponse, error)

Send() function allows a user to send a message as defined by the Message object passed to it.

type LegacyUnwrap

type LegacyUnwrap struct {
	Error     string
	ErrorCode string
	Data      string
	To        string
}

LegacyUnwrap struct represents the result that was parsed from the Clickatell HTTP API. The API is older and does not always return consistent results.

func UnwrapLegacyLine

func UnwrapLegacyLine(line string) *LegacyUnwrap

Since the HTTP API contains some inconsistent results, the UnwrapLegacyLine() function will parse these responses and return them as a struct with "known" properties. This function is used to create a bridge between the legacy response and a predictable response object.

func (*LegacyUnwrap) GetError

func (l *LegacyUnwrap) GetError() *ClickatellError

GetError() function will return a golang error object (ClickatellError) if the response was unsuccessful.

func (*LegacyUnwrap) HasError

func (l *LegacyUnwrap) HasError() bool

HasError() function will check if the unwrapped response was successful or not.

type Message

type Message struct {
	Binary         bool     `url:"binary,omitempty" json:"binary,omitempty"`
	ClientMsgId    string   `url:"cliMsgId,omitempty" json:"clientMessageId,omitempty"`
	Concat         int      `url:"concat,omitempty" json:"maxMessageParts,omitempty"`
	DeliveryTime   int      `url:"deliv_time,omitempty" json:"-,omitempty"`
	DeliveryQueue  int      `url:"queue,omitempty" json: "userPriorityQueue,omitempty"`
	Destination    []string `url:"-" json:"to"`
	Callback       int      `url:"callback,omitempty" json:"callback,omitempty"`
	Escalate       bool     `url:"escalate,omitempty" json:"escalate,omitempty"`
	MaxCredits     int      `url:"max_credits,omitempty" json:"maxCredits,omitempty"`
	Body           string   `url:"text" json:"text"`
	Mo             bool     `url:"mo,omitempty" json:"mo,omitempty"`
	ScheduledTime  int      `url:"scheduled_time,omitempty" json:"scheduledDeliveryTime,omitempty"`
	From           string   `url:"from,omitempty" json:"from,omitempty"`
	Unicode        bool     `url:"unicode,omitempty" json:"unicode,omitempty"`
	ValidityPeriod int      `url:"validity,omitempty" json:"validityPeriod,omitempty"`
}

The Message struct is a representation of a Clickatell SMS message. The properties of the message can be altered before using it to submit to the Send() method.

type RestClient

type RestClient struct {
	// contains filtered or unexported fields
}

RestClient struct represents an instance of a REST API connection based on the API token provided.

func Rest

func Rest(apiToken string, client *http.Client) *RestClient

Rest() funciton creates a new REST connection instance based on the token and http.Client. The http.Client is optional and will use a default implementation if nil.

func (*RestClient) GetBalance

func (c *RestClient) GetBalance() (*GetBalanceResponse, error)

GetBalance() function returns the users balance as per Clickatell account status.

func (*RestClient) Send

func (c *RestClient) Send(in Message) (*SendResponse, error)

Send() function allows a user to send a message as defined by the Message object passed to it.

type SendResponse

type SendResponse struct {
	Error ErrorResponse `json:"error"`

	Data struct {
		Message []SendResponseMessage `json:"message"`
	} `json:"data"`
}

SendReponse struct represents the response of a "send" API call.

type SendResponseMessage

type SendResponseMessage struct {
	To        string        `json:"to"`
	MessageId string        `json:"apiMessageId"`
	Error     ErrorResponse `json:"error"`
}

SendResponseMessage struct represents the response of a message contained withing a "send" API call.