Text Notifications

Submitted	May 5, 2026
Approved
Status	PROPOSED
Impact	MEDIUM
Arch Ticket	https://folio-org.atlassian.net/browse/ARCH-351
Prod ticket	https://folio-org.atlassian.net/browse/UXPROD-1532

Executive Summary

Purpose: Enable SMS notifications for patrons via the existing app-notifications flow in FOLIO.
Approach: Introduce a new backend module, mod-sms, that abstracts SMS sending and integrates with external providers.
Providers: Support pluggable connectors for AWS SNS, Vonage, and Twilio; choose per-tenant via configuration.
Scope (initial): Outbound SMS only triggered by app-notifications; message templating and localization reused from existing notifications.

Folio platform is able to send Text (SMS) notifications using app-notifications modules
one-way notifications (from Folio to patrons)

Documentation	https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-simple-notification-service.html https://docs.aws.amazon.com/sns/latest/dg/example_sns_UsageSmsTopic_section.html
Credentials	https://docs.aws.amazon.com/java/api/latest/software/amazon/awssdk/auth/credentials/DefaultCredentialsProvider.html
SDK	https://mvnrepository.com/artifact/com.vonage/server-sdk/9.3.1
Pricing	https://aws.amazon.com/sns/sms-pricing/ https://aws.amazon.com/end-user-messaging/pricing/

URL shortener is not part of default implementation in SNS API or newer AWS End User Messaging

Documentation	https://developer.vonage.com/en/messaging/sms/overview?source=messaging
SMS API Documentation	SMS API Documentation
SDK	https://mvnrepository.com/artifact/com.vonage/server-sdk/9.3.1
Pricing	https://www.vonage.com/communications-apis/sms/pricing/

Required configuration values

Configuration Key	Description

Configuration Key	Description
`VONAGE_API_KEY`	Secure Value: API key - retrieved using dashboard
`VONAGE_API_SECRET`	Secure Value: API secret - retrieved using dashboard

URL shortener is not part of default implementation in SMS API

Documentation	https://www.twilio.com/docs/messaging
API Documentation	https://www.twilio.com/docs/messaging/api/message-resource
SDK	https://mvnrepository.com/artifact/com.twilio.sdk/twilio
Pricing	https://www.twilio.com/en-us/sms/pricing/us

Provides an ability to send not only SMS messages, but RCS, What’s App notification and Facebook notifications\

Provides internal ability to shorten URL links using shortenUrls request body parameter

Configuration Key	Description

Configuration Key	Description
`TWILIO_ACCOUNT_SID`	Secure Value: API key - retrieved using dashboard
`TWILIO_AUTH_TOKEN`	Secure Value: API secret - retrieved using dashboard

Module will be implemented using Spring. Message connectors must be provided as conditional singleton beans per tenant.

New app-sms containing UI and backend changes for SMS functionality; depends on app-notification

mod-audit supports auditing patron notifications
An additional table in mod-sms will track new and ongoing notifications with retry policies based on ENV variables, if needed
mod-sms tables will store PII such as patron phone numbers and notification text for retries. The Timer API endpoint should clear all unsent records based on event TTL, configured by ENV variables or per tenant via the Settings API.

Checkstyle from https://github.com/folio-org/folio-java-checkstyle/tree/master/src/main/resources/folio-checkstyle
JUnit 6 for unit testing
Wiremock validates API requests
Localstack validates integration with AWS SDK (community version only)

Local Settings API will be provided by mod-sms service and it will provide to configure a provider and general settings related to it.