{"id":18737407,"url":"https://github.com/mikesafonov/spring-boot-starter-smpp","last_synced_at":"2025-04-12T19:32:22.581Z","repository":{"id":38778014,"uuid":"173094146","full_name":"MikeSafonov/spring-boot-starter-smpp","owner":"MikeSafonov","description":"Spring boot starter to send SMS via SMPP","archived":false,"fork":false,"pushed_at":"2023-03-06T15:01:24.000Z","size":414,"stargazers_count":33,"open_issues_count":23,"forks_count":19,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-23T01:01:51.980Z","etag":null,"topics":["java","smpp","spring-boot","starter"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikeSafonov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"patreon":"MikeSafonov"}},"created_at":"2019-02-28T10:46:51.000Z","updated_at":"2024-12-06T15:57:32.000Z","dependencies_parsed_at":"2025-03-23T01:01:51.773Z","dependency_job_id":"367b60fe-3db6-464c-8349-494bce49dbbf","html_url":"https://github.com/MikeSafonov/spring-boot-starter-smpp","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeSafonov%2Fspring-boot-starter-smpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeSafonov%2Fspring-boot-starter-smpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeSafonov%2Fspring-boot-starter-smpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeSafonov%2Fspring-boot-starter-smpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikeSafonov","download_url":"https://codeload.github.com/MikeSafonov/spring-boot-starter-smpp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248621274,"owners_count":21134793,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","smpp","spring-boot","starter"],"created_at":"2024-11-07T15:25:02.910Z","updated_at":"2025-04-12T19:32:22.192Z","avatar_url":"https://github.com/MikeSafonov.png","language":"Java","funding_links":["https://patreon.com/MikeSafonov"],"categories":[],"sub_categories":[],"readme":"# spring-boot-starter-smpp\n[![Maven Central](https://img.shields.io/maven-central/v/com.github.mikesafonov/spring-boot-starter-smpp.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22com.github.mikesafonov%22%20AND%20a:%22spring-boot-starter-smpp%22)\n[![codecov](https://codecov.io/gh/MikeSafonov/spring-boot-starter-smpp/branch/master/graph/badge.svg)](https://codecov.io/gh/MikeSafonov/spring-boot-starter-smpp)\n[![Travis-CI](https://travis-ci.com/MikeSafonov/spring-boot-starter-smpp.svg?branch=master)](https://travis-ci.com/MikeSafonov/spring-boot-starter-smpp)\n[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org)\n\n[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=alert_status)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=reliability_rating)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=sqale_rating)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=security_rating)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n\n[![Bugs](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=bugs)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Code Smells](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=code_smells)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=vulnerabilities)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n\n[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=duplicated_lines_density)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=ncloc)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n[![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=MikeSafonov_spring-boot-starter-smpp\u0026metric=sqale_index)](https://sonarcloud.io/dashboard?id=MikeSafonov_spring-boot-starter-smpp)\n\n\nThis Spring Boot starter can be used by any Spring Boot application that wants to send SMS messages \nusing [SMPP](https://en.wikipedia.org/wiki/Short_Message_Peer-to-Peer). [SMPP v3.4 spec](http://docs.nimta.com/SMPP_v3_4_Issue1_2.pdf)\n\n## Features\n\n- Sending message with delivery receipt \n- Sending datagram message (without delivery receipt)\n- Sending silent message\n- Sending flash message\n- Cancel message\n- Multiply SMPP connection\n- SMPP connection load balancing\n\n## Usage\n\nAdd the following dependency to your project:\n\nMaven:\n    \n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.mikesafonov\u003c/groupId\u003e\n      \u003cartifactId\u003espring-boot-starter-smpp\u003c/artifactId\u003e\n      \u003cversion\u003elatest\u003c/version\u003e\n    \u003c/dependency\u003e\n    \nGradle:\n\n    dependencies {\n        implementation 'com.github.mikesafonov:spring-boot-starter-smpp:latest'\n    }\n    \nConfigure spring-boot application via properties (see [Configuration](#Configuration) section).\n\nUse [SenderManager](#SenderManager) to send SMS:\n\n    public class RoundRobinApplicationService {\n        private final SenderManager senderManager;\n    \n        public void sendMessage(String from, String to, String text) {\n            Message message = Message.simple(text)\n                    .from(from)\n                    .to(to)\n                    .build();\n            senderManager.getClient().send(message);\n        }\n    }\n\n## Configuration\n\nThe following tables show the available configuration:\n\n| Configuration                                   | Description                                                                              | Default                                                              |\n|-------------------------------------------------|------------------------------------------------------------------------------------------|----------------------------------------------------------------------|\n| `smpp.defaults`                                 | Default smpp connection properties                                                       |                                                                      |\n| `smpp.defaults.ucs2Only`                        | Using ucs2 encoding only or not                                                          | `false`                                                              |\n| `smpp.defaults.maxTry`                          | Number of attempts to reconnect if smpp session is closed                                | `5`                                                                  |\n| `smpp.defaults.connectionMode`                  | Client connection mode ([`STANDARD`](#DefaultSenderClient), [`TEST`](#TestSenderClient), [`MOCK`](#MockSenderClient))   | `STANDARD`                          |\n| `smpp.defaults.windowSize`                      | Smpp connection window size                                                              | `90`                                                                 |\n| `smpp.defaults.loggingPdu`                      | Is logging smpp pdu                                                                      | `false`                                                              |\n| `smpp.defaults.loggingBytes`                    | Is logging smpp bytes                                                                    | `false`                                                              |\n| `smpp.defaults.rebindPeriod`                    | Connection rebind period (Duration)                                                      | `90s`                                                                |\n| `smpp.defaults.requestTimeout`                  | Request timeout (Duration)                                                               | `5s`                                                                 |\n| `smpp.defaults.allowedPhones`                   | Array of phones to send. Using only if `connectionMode` is `TEST`                        | `[]`                                                                 |\n| `smpp.defaults.connectionType`                  | Type of smpp connections(`TRANSCEIVER` or `TRANSMITTER_RECEIVER`)                        | `TRANSMITTER_RECEIVER`                                                                 |\n| `smpp.connections`                              | Map of SMSC connections                                                                  |                                                                      |\n| `smpp.connections.\u003cname\u003e.credentials`           | SMSC connection credentials                                                              |                                                                      |\n| `smpp.connections.\u003cname\u003e.credentials.host`      | SMSC host                                                                                |                                                                      |\n| `smpp.connections.\u003cname\u003e.credentials.port`      | SMSC port                                                                                |                                                                      |\n| `smpp.connections.\u003cname\u003e.credentials.username`  | SMSC username                                                                            |                                                                      |\n| `smpp.connections.\u003cname\u003e.credentials.password`  | SMSC password                                                                            |                                                                      |\n| `smpp.connections.\u003cname\u003e.ucs2Only`              | Using ucs2 encoding only or not                                                          | `false`                                                              |\n| `smpp.connections.\u003cname\u003e.maxTry`                | Number of attempts to reconnect if smpp session is closed                                | `5`                                                                  |\n| `smpp.connections.\u003cname\u003e.connectionMode`        | Client`s connection mode                                                                 | `STANDARD`   see `com.github.mikesafonov.smpp.config.ConnectionMode` |\n| `smpp.connections.\u003cname\u003e.windowSize`            | Smpp connection window size                                                              | `90`                                                                 |\n| `smpp.connections.\u003cname\u003e.loggingPdu`            | Is logging smpp pdu | `false`                                                            |                                                                      |\n| `smpp.connections.\u003cname\u003e.loggingBytes`          | Is logging smpp bytes | `false`                                                          |                                                                      |\n| `smpp.connections.\u003cname\u003e.rebindPeriod`          | Connection rebind period (Duration)                                                      | `90s`                                                                |\n| `smpp.connections.\u003cname\u003e.requestTimeout`        | Request timeout (Duration)                                                               | `5s`                                                                 |\n| `smpp.connections.\u003cname\u003e.allowedPhones`         | Array of phones to send. Using only if `connectionMode` is `TEST`                        | `[]`                                                                 |\n| `smpp.connections.\u003cname\u003e.connectionType`        | Type of smpp connections(`TRANSCEIVER` or `TRANSMITTER_RECEIVER`)                        |                                                                  |\n| `smpp.connections.\u003cname\u003e.systemType`        | The systemType parameter is used to categorize the type of ESME that is binding to the SMSC.                    |                                                                  |\n| `smpp.setupRightAway`                           | Should setup smpp clients after creation and fail fast if connection cant be established | `true`                                                               |\n\nConfiguration example for `.properties` file:\n\n    smpp.connections.one.credentials.host=localhost\n    smpp.connections.one.credentials.username=user\n    smpp.connections.one.credentials.password=pass\n    smpp.connections.one.credentials.port=1111\n    smpp.connections.two.credentials.host=localhost\n    smpp.connections.two.credentials.username=user2\n    smpp.connections.two.credentials.password=pass2\n    smpp.connections.two.credentials.port=2222\n\nConfiguration example for `.yaml` file:\n\n    smpp:\n        default:\n            maxTry: 10\n            ucs2Only: true\n        connections:\n            one:\n               credentials:\n                    host: localhost\n                    username: user\n                    password: pass\n                    port: 1111\n            two:\n               credentials:\n                    host: localhost\n                    username: user2\n                    password: pass2\n                    port: 2222\n\n## Build\n\n### Build from source\n\nYou can build application using following command:\n\n    ./gradlew clean build -x signArchives\n    \n#### Requirements:\n\nJDK \u003e= 1.8\n\n### Unit tests\n\nYou can run unit tests using following command:\n\n    ./gradlew test\n    \n### Mutation tests\n\nYou can run mutation tests using following command:\n\n    ./grdlew pitest\n\nYou will be able to find pitest report in `build/reports/pitest/` folder.\n\n### Integration tests\n\nYou can run integration tests using following command:\n\n    ./grdlew testIntegration\n\n## Key abstractions\n\nThis starter provides several abstractions:\n\n### SenderClient\n\nThis interface represents smpp protocol _TRANSMITTER_ or _TRANSCEIVER_ (see `connectionType` property) client. \nThis is entry point to sending any messages.\nSpring-boot-starter-smpp comes with several implementations:\n\n![class diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/MikeSafonov/spring-boot-starter-smpp/master/diagrams/senderclient_class.txt)\n\n#### DefaultSenderClient\n\nThis is `default` implementation. `DefaultSenderClient` creates real smpp connection and performing all requests.\n\n#### TestSenderClient\n\n`TestSenderClient` should be used for testing purpose. \n`TestSenderClient` client may provide real smpp connection via proxy implementation of `SenderClient`. \nEvery incoming request will be redirected to real `SenderClient` only if destination phone contains in list of allowed phone (`smpp.connections.\u003cname\u003e.allowedPhones` property). \nOtherwise response will be generated by [SmppResultGenerator](#SmppResultGenerator).\n  \n#### MockSenderClient\n\n`MockSenderClient` does not perform any connection via smpp and only generate response using [SmppResultGenerator](#SmppResultGenerator).\n\n### SmppResultGenerator\n\nImplementations of this interface is used by [MockSenderClient](#MockSenderClient) and [TestSenderClient](#TestSenderClient) clients\n to generate request response. \n\nStarter `by default` use **AlwaysSuccessSmppResultGenerator** which always generate success response with random smsc message id.\n\nYou can implement own **SmppResultGenerator** to add custom logic.\n\n### TypeOfAddressParser\n\n[DefaultSenderClient](#DefaultSenderClient) use implementation of `TypeOfAddressParser` \nto detect TON and NPI parameters for source and destination address of message.\nStarter provide **DefaultTypeOfAddressParser** and **UnknownTypeOfAddressParser** implementations. \n\n`By default` starter use **DefaultTypeOfAddressParser**. \n**DefaultTypeOfAddressParser** supports international and alphanumeric ton parameters, otherwise return UNKNOWN ton/npi. \n\n**UnknownTypeOfAddressParser** always return _UNKNOWN_ ton/npi. This means what your SMS center must detect this parameters by himself.\n\n### ResponseClient\n\nThis abstraction represent connection via SMPP with _RECEIVER_ or _TRANSCEIVER_ (see `connectionType` property) type. \nKey purpose is listening delivery receipts. \n`By default` starter use **DefaultResponseClient**. This class keeping smpp connection and pushing all incoming PDU to [SmppSessionListener](#SmppSessionListener).\n\n### SmppSessionListener\n\nThis class dedicated to listening all incoming PDU traffic. `By default` starter use **ResponseSmppSessionHandler**. This class \nfind delivery receipts and push to **DeliveryReportConsumer**.\n\n**DeliveryReportConsumer** dedicated to handle _DeliveryReport_ on client side. Client may build custom logic on receiving delivery receipts by implementing this interface.\nStarter use `by default` **NullDeliveryReportConsumer** if client doesnt provide any implementation of **DeliveryReportConsumer**.\n**NullDeliveryReportConsumer** ignore any delivery receipts.\n\nYou can use custom **SmppSessionListener** by creating appropriate bean.\n\n### SenderManager\n\nThis is high level abstraction over sender clients.\n\n![class diagram](http://www.plantuml.com/plantuml/proxy?src=https://raw.github.com/MikeSafonov/spring-boot-starter-smpp/master/diagrams/sendermanager_class.txt)\n\nThis starter comes with one default implementation - **StrategySenderManager**. **StrategySenderManager** holds\nlist of smsc connections and return sender client based on some rules which implemented by **IndexDetectionStrategy**\n\nThere are two default implementation of **IndexDetectionStrategy** - **RandomIndexDetectionStrategy**(return random sender client) and **RoundRobinIndexDetectionStrategy**\n(return sender client based on round and robbin algorithm). **RoundRobinIndexDetectionStrategy** strategy used `by default`.\n\n## Contributing\n\nFeel free to contribute. \nNew feature proposals and bug fixes should be submitted as GitHub pull requests. \nFork the repository on GitHub, prepare your change on your forked copy, and submit a pull request.\n\n**IMPORTANT!**\n\u003eBefore contributing please read about [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) / [Conventional Commits RU](https://www.conventionalcommits.org/ru/v1.0.0-beta.2/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikesafonov%2Fspring-boot-starter-smpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikesafonov%2Fspring-boot-starter-smpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikesafonov%2Fspring-boot-starter-smpp/lists"}