Twizo Go API

Connect to the Twizo API using Go. This API includes functions to send verifications (2FA), SMS and Number Lookup.

Requirements

• Go >= 1.9

Get application secret and choose api region

To use the Twizo API client, the following things are required:

• Create a Twizo account
• Login on the Twizo portal
• Find your application secret
• Find your nearest api region

Versioning

Each revision of the library is tagged and the version is updated accordingly.

Given Go's lack of built-in versioning, it is highly recommended you use a package management tool in order to ensure a newer version of the binding does not affect backwards compatibility.

Installation

$ go get github.com/twizoapi/lib-api-go

Getting started

Require the library using import, here we use twizo as an alias

import (
	twizo "github.com/twizoapi/lib-api-go"
)

Set the api key that was retrieved from the application section of the portal.

func main() {
	twizo.ApiKey = "43reFDSrewrfet425rtefdGDSGds54twegdsgHaFST2refwd"
	// the default region is 'eu'
	twizo.RegionCurrent = "asia"
	// rest of code
}

Verification

Create and send new verification

verificationResponse, err := twizo.VerificationSubmit("610123456789")
if err != nil {
    // handle error
}

Verify token, based on the response above

err = verificationResponse.Verify("12345")
if err != nil {
    // handle error
}

if verificationResponse.IsTokenSuccess() {
     // Token was correct
} else {
    // Token was not correct, expired, or other error
}

For more examples please see Verification Examples

Sms

Submit the request using the simple method. Using this method the Twizo Api will autodetect some of the settings for us. The api will split up the message if the body is too long for one SMS as well as some other settings.

smsResponses, err := twizo.SmsSubmit("610123456789", "Greetings from Twizo", "TwizoDemo")
if err != nil {
    // handle error
}

Optional retrieve status of all sent sms using the response above, an smsResponses is a collection of smsResponse

err = smsResponses.Status()
if err != nil {
    // handle error
}
for _, smsResponse := range smsResponses.GetItems() {
    fmt.Printf(
        "Sms [%s] to recipient [%s] has status [%s]\n",
        smsResponse.GetMessageID(),
        smsResponse.GetRecipient(),
        smsResponse.GetStatusMsg(),
    )
}

Optional retrieve status of sent sms using only the messageId, please note that this function can only be used to retieve the status of one sms, using the response above will allow checking all messages in that request.

smsResponse, err := twizo.SmsStatus("<MessageId>")
if err != nil {
        if (err.(*twizo.APIError).NotFound()) {
        	// Not found, it might have expired, or was never sent
        } else {
        	// handle other error
        }
} else {
        // smsResponse object was updated
}

For more examples please see Sms Examples

Numberlookup

Create and submit a new numberlookup

numberlookupResponse, err := twizo.NumberLookupSubmit("610123456789")
if err != nil {
    // handle error
}

Retrieve the result of the numberlookup

err = numberlookupResponse.Status()
if err != nil {
    // handle error
}
for _, nlR := range numberlookupResponse.GetItems() {
    fmt.Printf(
        "- Numberlookup result for [%s] has status [%s] operator [%s]\n",
        nlR.GetNumber(),
        nlR.GetStatusMsg(),
        utils.AsString(nlR.GetOperator(), "-unknown-"),
    )
}

For more examples please see Numberlookup Examples

Examples

In the examples directory you can find a collection of examples of how to use the api. All examples can be run using the following commands.

go run examples/verification/verificationSimple.go --key <key> --region <region>
go run examples/verification/verificationAdvanced.go --key <key> --region <region>
go run examples/sms/smsSimple.go --key <key> --region <region>
go run examples/sms/smsPoll.go --key <key> --region <region>
go run examples/numberlookupSimple.go --key <key> --region <region>
go run examples/numberlookupPoll.go --key <key> --region <region>

Development

Pull requests from the community are welcome. If you submit one, please keep the following guidelines in mind:

1. Code must be go fmt compliant.
2. All types, structs and funcs should be documented.
3. Ensure that make test succeeds.

Code can best be checked out like this (as an example, replace where needed)

export GOPATH="<DIR>"
git clone git@github.com:twizoapi/lib-api-go.git $(GOPATH)/src/github.com/twizoapi/lib-api-go
cd $(GOPATH)/src/github.com/twizoapi/lib-api-go

This way will allow tests to work

ToDo

• Add example for number lookup
• Split up examples
• Add more tests for sms / verification / numberlookup
• Document all types / funcs / structs (point 2)

License

The MIT License.

Copyright (c) 2016-2017 Twizo

Support

Contact: www.twizo.com — support@twizo.com