Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Release 3.0.0 #4

Merged
merged 3 commits into from
Oct 24, 2024
Merged

Release 3.0.0 #4

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
07cb9fc
Update to version 3.0.0
Oct 24, 2024
f0e1275
Removed obsolete files.
lvukadinovic-ib Oct 24, 2024
f7f2dc4
Updated release date.
lvukadinovic-ib Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
1 change: 0 additions & 1 deletion .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,6 @@
# Folders
_obj
_test
.scannerwork

# Architecture specific extensions/prefixes
*.[568vq]
Expand Down
17 changes: 17 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,22 @@ All notable changes to the library will be documented in this file.
The format of the file is based on [Keep a Changelog](http://keepachangelog.com/)
and this library adheres to [Semantic Versioning](http://semver.org/) as mentioned in [README.md][readme] file.

## [[3.0.0](https://github.com/infobip/infobip-api-go-client/releases/tag/3.0.0)] - 2024-10-XX

🎉 **NEW Major Version of `infobip`.**

⚠ IMPORTANT NOTE: This release contains breaking changes! From this point onward `Go` 1.13 is no longer supported. The minimum supported version is `Go` 1.18.

In this release, we updated and modernized the infobip library. It is auto-generated and different from the previous version.

### Added
* Most recent [Infobip SMS API](https://www.infobip.com/docs/api/channels/sms) feature set.
* Support for [Infobip Messages API](https://www.infobip.com/docs/api/platform/messages-api).
* Added mock tests to verify the correctness of request payloads and response handling.

### Changed
* To improve maintainability and organization, we have separated the models for each Infobip product into their own directories. This means that each product —such as `SMS`, `Messages API`, or other services— will now have its own dedicated folder for models, making it easier to manage dependencies and clearly see which models are tied to each specific product. Users will now find a more structured, modular design, allowing easier integration and upgrades in the future.

## [[2.1.0](https://github.com/infobip/infobip-api-go-client/releases/tag/2.1.0)] - 2023-04-12

### Added
Expand Down Expand Up @@ -41,3 +57,4 @@ In this release, we updated and modernized the infobip library. It is auto-gener
- `README.md` which contains necessary data and examples for quickstart as well as some other important pieces of information on versioning, licensing, etc.

[readme]: README.mustache

145 changes: 64 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
# Infobip API Go Client

<img src="https://cdn-web.infobip.com/uploads/2023/01/Infobip-logo.svg" height="93px" alt="Infobip" />

[![Go Reference](https://pkg.go.dev/badge/github.com/infobip/infobip-api-go-client.svg)](https://pkg.go.dev/github.com/infobip/infobip-api-go-client)
[![MIT License](https://badgen.net/github/license/infobip/infobip-api-go-client)](https://opensource.org/licenses/MIT)

This is a Go module for Infobip API and you can use it as a dependency when you want to consume [Infobip APIs][apidocs] in your application.
To use this, you'll need an Infobip account. You can create a [free trial][freetrial] account [here][signup].
To use this, you'll need an Infobip account. You can create a free trial account [here][signup].

`infobip-api-go-client` is built on top of [OpenAPI Specification](https://swagger.io/specification/), powered by [OpenAPI Generator](https://openapi-generator.tech/).

<img src="https://udesigncss.com/wp-content/uploads/2020/01/Infobip-logo-transparent.png" height="48px" alt="Infobip" />

#### Table of contents:
* [Documentation](#documentation)
* [General Info](#general-info)
Expand All @@ -22,23 +22,24 @@ To use this, you'll need an Infobip account. You can create a [free trial][freet
Detailed documentation about Infobip API can be found [here][apidocs].
The current version of this library includes this subset of Infobip products:
* [SMS](https://www.infobip.com/docs/api/channels/sms)
* [Messages API](https://www.infobip.com/docs/api/platform/messages-api)

## General Info
For `infobip-api-go-client` versioning we use [Semantic Versioning][semver] scheme.

Published under [MIT License][license].

Minimum Go version supported by this library is 1.13.
Minimum `Go` version supported by this library is `1.18`.

## Installation
Pull the library by using the following command:
```shell
go get github.com/infobip/infobip-api-go-client/v2
go get github.com/infobip/infobip-api-go-client/v3
```

To use our library you have to import it in your project files:
```shell
import "github.com/infobip/infobip-api-go-client/v2"
import "github.com/infobip/infobip-api-go-client/v3"
```

Afterwards, to update your `go.mod` and `go.sum` files, simply run the following:
Expand All @@ -60,87 +61,84 @@ To see your base URL, log in to the [Infobip API Resource][apidocs] hub with you
Let's first set the configuration field.
```go
configuration := infobip.NewConfiguration()
configuration.Host = "<put your base URL here>"
configuration.Host = "<YOUR_BASE_URL>"
```

Now you can initialize the API client.
```go
infobipClient := infobip.NewAPIClient(configuration)
infobipClient := api.NewAPIClient(configuration)
```

For details, check the [client](https://github.com/infobip/infobip-api-go-client/blob/master/v2/client.go) source code.
For details, check the [client](https://github.com/infobip/infobip-api-go-client/blob/master/v3/pkg/infobip/client.go) source code.

#### Authentication
After that is done, we should set the authentication method.
There are several ways how that can be done.

* If you prefer to use Basic Auth:
```go
auth := context.WithValue(context.Background(), infobip.ContextBasicAuth, infobip.BasicAuth{
UserName: "<put your username here>",
Password: "<put your password here>",
})
```

* If you prefer to use Api Key:
```go
auth := context.WithValue(context.Background(), infobip.ContextAPIKey, "<put your Infobip Api key here>")
auth := context.WithValue(
context.Background(),
infobip.ContextAPIKeys,
map[string]infobip.APIKey{
"APIKeyHeader": {Key: "<YOUR_API_KEY>", Prefix: "<YOUR_API_PREFIX>"},
},
)
```

To understand how to generate above mentioned tokens, check [this](https://www.infobip.com/docs/essentials/api-authentication) page.

In order to use the `auth` you need to provide it as a param to the endpoint you are triggering, eg.
```go
apiResponse, httpResponse, err := infobipClient.
SendSmsApi.
GetOutboundSmsMessageLogs(auth).
From("<put your From field filter here>").
Execute()
```

That is it, now you are set to use the API.

#### Send an SMS
See below, a simple example of sending a single SMS message to single recipient.
Here's a basic example of sending the SMS message.

```go
request := infobip.NewSmsAdvancedTextualRequest()

destination := infobip.NewSmsDestination("41793026727")

from := "InfoSMS"
text := "This is a dummy SMS message"
message := infobip.NewSmsTextualMessage()
message.From = &from
message.Destinations = &[]infobip.SmsDestination{*destination}
message.Text = &text

request.SetMessages([]infobip.SmsTextualMessage{*message})
import (
"context"
"fmt"

"github.com/infobip/infobip-api-go-client/v3/pkg/infobip"
"github.com/infobip/infobip-api-go-client/v3/pkg/infobip/api"
"github.com/infobip/infobip-api-go-client/v3/pkg/infobip/models/sms"
)

...

destinations := []sms.Destination{
{To: "421907372599"},
}

content := sms.LogContent{
TextMessageContent: sms.NewTextMessageContent("Congratulations on sending your first message with GO library."),
}

givenMessage := sms.NewMessage(destinations, content)
givenMessage.SetSender("421902028966")

request := sms.NewRequestEnvelope([]sms.Message{
*givenMessage,
})

// Send the SMS message
apiResponse, httpResponse, err := infobipClient.
SmsAPI.
SendSmsMessages(auth).
RequestEnvelope(*request).
Execute()
```

Send the message and inspect the `err` field for more information in case of failure.
You can get the HTTP status code from `httpResponse` property, and more details about error from `ErrorContent` property.

```go
apiResponse, httpResponse, err := infobipClient.
SendSmsApi.
SendSmsMessage(auth).
SmsAdvancedTextualRequest(*request).
Execute()

// If, for any reason, you don't want to use some of the response fields, feel free to replace them with an underscore wildcard, eg.
// apiResponse, _, _ := ...
```

In order to be able to access our generated `Expecption` models, you will have to do a little bit of type casting.
In order to be able to access our generated `Exception` models, you will have to do a little bit of type casting.
Methods provided within `ServiceException` object are `GetMessageId()` and `GetText()` referring to the nature of the exception.
Withing the `_nethttp.Response` response field (in example labeled as `httpResponse`) you can find pretty much everything that is referring to the HTTP status, e.g. `Status`, `StatusCode`, `Body`, `Header`, etc.
Withing the `http.Response` response field (in example labeled as `httpResponse`) you can find pretty much everything that is referring to the HTTP status, e.g. `Status`, `StatusCode`, `Body`, `Header`, etc.

```go
if err != nil {
apiErr, isApiErr := err.(infobip.GenericOpenAPIError)
apiErr, isApiErr := err.(*api.GenericOpenAPIError)
if isApiErr {
ibErr, isIbErr := apiErr.Model().(infobip.SmsApiException)
ibErr, isIbErr := apiErr.Model().(sms.ApiException)
if isIbErr {
errMessageId := ibErr.RequestError.ServiceException.GetMessageId()
errText := ibErr.RequestError.ServiceException.GetText()
Expand All @@ -164,15 +162,16 @@ messageId := *apiResponse.Messages[0].MessageId
```

#### Receive sent SMS report

For each SMS that you send out, we can send you a message delivery report in real time. All you need to do is specify your endpoint when sending SMS in `notifyUrl` field of `SmsTextualMessage`, or subscribe for reports by contacting our support team.
e.g. `https://{yourDomain}/delivery-reports`

Example of webhook implementation:

```go
func deliveryReports(w http.ResponseWriter, req *http.Request) {
reqBody, _ := ioutil.ReadAll(req.Body)
var report infobip.SmsDeliveryResult
reqBody, _ := io.ReadAll(req.Body)
var report sms.DeliveryResult
err := json.Unmarshal(reqBody, &report)
if err != nil {
fmt.Println("Error:", err)
Expand All @@ -196,35 +195,17 @@ func main() {
If you prefer to use your own serializer, please pay attention to the supported [date format](https://www.infobip.com/docs/essentials/integration-best-practices#date-formats).
In this library, we are wrapping around the `time.Time` model with our own `infobip.Time` in order to enforce the time format to be serialized properly.

#### Fetching delivery reports
If you are for any reason unable to receive real time delivery reports on your endpoint, you can use `messageId` or `bulkId` to fetch them.
Each request will return a batch of delivery reports - only once.

```go
limit := int32(10)
bulkId := "bulk-1234"
messageId := "msg-123"

apiResponse, httpResponse, err := infobipClient.
SendSmsApi.
GetOutboundSmsMessageDeliveryReports(auth).
BulkId(bulkId).
MessageId(messageId).
Limit(limit).
Execute()
```

#### Unicode & SMS preview
Infobip API supports Unicode characters and automatically detects encoding. Unicode and non-standard GSM characters use additional space, avoid unpleasant surprises and check how different message configurations will affect your message text, number of characters and message parts.

```go
text := "Let's see how many characters will remain unused in this message."
request := *infobip.NewSmsPreviewRequest(text)
request := sms.NewPreviewRequest(text)

apiResponse, httpResponse, err := infobipClient.
SendSmsApi.
PreviewSmsMessage(auth).
SmsPreviewRequest(request).
SmsPreviewRequest(*request).
Execute()
```

Expand All @@ -236,8 +217,8 @@ Example of webhook implementation:

```go
func incomingSms(w http.ResponseWriter, req *http.Request) {
reqBody, _ := ioutil.ReadAll(req.Body)
var result infobip.SmsInboundMessageResult
reqBody, _ := io.ReadAll(req.Body)
var result sms.InboundMessageResult
err := json.Unmarshal(reqBody, &result)
if err != nil {
fmt.Println("Error:", err)
Expand All @@ -260,14 +241,16 @@ func main() {
#### Two-Factor Authentication (2FA)
For 2FA quick start guide please check [these examples](two-factor-authentication.md).

#### Messages API
For Messages API quick start guide, view [these examples](messages-api.md).

## Ask for help

Feel free to open issues on the repository for any issue or feature request. As per pull requests, for details check the `CONTRIBUTING` [file][contributing] related to it - in short, we will not merge any pull requests, this code is auto-generated.

If it is, however, something that requires our imminent attention feel free to contact us @ [support@infobip.com](mailto:support@infobip.com).

[apidocs]: https://www.infobip.com/docs/api
[freetrial]: https://www.infobip.com/docs/freetrial
[signup]: https://www.infobip.com/signup
[semver]: https://semver.org
[license]: LICENSE
Expand Down
1 change: 0 additions & 1 deletion docs.go
View file
Open in desktop

This file was deleted.

Loading