SMS Outbound

Functional Spec

Platform should have an API to allow ability to send an SMS to a client or a staff. 

Discussions have identified that to prevent abuse and ensure traceability, we would would NOT want the REST API to expose a send(String phoneNumber, …) kind of semantics, only send Client or Staff.

Note: There are also many cases (e.g loan enters delinquent state, meeting notification) where the platform itself internally would/may want to send SMS automatically to Clients/Staff. It would/may not use the REST API itself but its underlying Java service implementation directly.

Tech Spec

API Level

In mailing thread, Michael Vorburger offered some suggestions on possible API to expose. Mainly Michael focussed on a generic or abstract api whereas my preference is for something less abstract. The apigee ebook on web apis that we reference in our API documentation goes into explanation of why staying away from abstract apis would be a good idea.

So to start with something as simple as:

The POST /sms will have EITHER a clientId OR a staffId, but never both (should return an error if it does).

The GET /sms should allow usual paging, and filtering notably by clientId or staffId (major use case), and other fields.

Some questions that arise straightaway:

Q: Do we want to attempt to send the SMS straightaway of offer ability to indicate when the SMS could be sent?
A: Let's keep it simple, and add this later, if needed? (I don't immediately see a burning use case need for it.) 

Note: In terms of response, we won't be waiting around for third party service to respond to us, we will just make entry into our database, attempt to send sms and respond back to api caller that SMS entry made successfully (or not) and any extra information that might be useful like 'status'.

Use Cases / API usage examples

Q: To help understand API usage can we identify some possible example ways that application developers would use this API on their screens/workflows?

Manually Send SMS to Client

First UC for POST /sms would be a "Send SMS" action on client details view UI - a new button saying "SMS" would show up along with the other Client Action. A user could enter a text message and send the same to the Client.

The client details view UI would also get a new tab or section or something listening all (with paging) previously sent SMS to that specific client - using the GET /sms REST API.

Database Schema

No problem with modelling for more abstract 'messages' functionality here if you want to e.g. not just sms but other forms of messages/notification event but for now theres no problem with just creating a table to track sms only messages. We dont need to split them up into client and staff (no real help) and we can still have proper foreign keys, just create client_id and staff_id column - if we think there will be many entities in the system associated with 'mobile numbers' and are sms-able then we would just go with the entity type, entity id approach.

Discussions have identified that for traceability for client and staff's frequently changing phone numbers, we do want to store the client's / staff's actual current phone number at the time the respective SMS was sent out in the database table (and expose it in the REST API).

The needed fields themselves will become very obvious when padding this out... typical examples of what we'll like want to include sooner or later likely include e.g. a createdTimestamp and an enum Pending/Sent/ Delivered/Declined  status.

Batch processing

We probably want to be able to:

1. Send SMS straightaway, or
2. let some batch or scheduled process check for SMS entries that require sending