Platform SMS

[Rob LaRubbio]

We need to start thinking about how to expose SMS functionality within the platform.  I've taken a stab at it below if people have comments, suggestions or alternate proposals I'd love to hear them.

-Rob

Platform SMS

The platform should provide a standard api that allows all modules to send SMS messages and be notified when a message is received.  This API is modeled after SMSLib.

The platform SMS module should be able to execute in process with a direct connection to the modem when a single MOTECH server is in use.  It also should be able to communicate with and external process when MOTECH is running in a load balanced or multi-server environment.  Client code should not have to change when the deployment configuration changes.  API behavior should be exactly the same in both scenarios.

The module should be able to handle both SMS & USSD messages.  MMS messages are not required at this time.

All interactions with the Platform SMS module should be async.

Registration:

• Clients should be able to register an event to be published when a regex or search string matches an incoming message.  Incoming messages are matched against the registrations and on match the supplied event is augmented with the sms message and published.

APIs:

∘ register(Regex matcher, Event event)
∘ register(String phone, Regex matcher,Event event)
∘ register(String phone, Event event)

Inbound:

• When any incoming SMS message is received an event should be published on a well known subject (i.e. motech.sms.received).  The event should contain the originating number, message txt, session id if one exists
• Additionally any registrations should be checked and messages published if matches are found

Outgoing:

• a single method that allows a caller to provide a phone number, message and event to publish when sending is complete.  The published event will be augmented with message status.
• an alternate method that takes a session or thread id which adds this message to an existing thread.  Should this message also accept a boolean replyExpected so the system knows to add any response to the thread.  Should it take a thread id so it knows it's in a thread?  Lame that the API for the first message in a thread is different from sending the second.  I'm not sold on threads.

API:

∘ sendMessage(Msg message)
∘ sendMessage(Msg message, Event statusEvent)
∘ sendMessage(Msg, message, Bool replyExpected)
∘ sendMessage(Msg, message, Bool replyExpected, Event statusEvent)

Thread or Session management
    Provide APIs that allow clients to add or remove message to threads.  Also allow the closing of a thread.  Threads are a chronological ordering of messages.  A thread should only contain messages to a single phone number. 

API:

∘ Thread getThread(Int threadId)
∘ Thread.close()
∘ Thread.getMessages()
∘ Thread.removeMessage(Msg message)
∘ Thread.addMessage(Msg message)

Delivery Reports & Message status

The system should generate a uniq id for each message.  Status can be queried for a message by its ID, or published as an event when the module receives status from the gateway.

Questions:

• SMSLib exposes the gateway the message was routed through.  Do we want to propagate that information up?
• Do we need to differentiate between SMS and USSD or can then just be presented to clients as a "message"?
• I'm not sold on the concepts of a thread or a session.  We do have use cases where a reply is expected, perhaps we kill the thread concept and provide an easy way to implement a state machine.