The messaging module allows you to send all kinds of messages, including email and SMS. It also helps you handle various ancillary aspects of messaging, including managing addresses and browsing past conversations. Lastly, it has an easy-to-use API so that other modules can incorporate messaging into their own projects.
To send an SMS message, use the following code:
This sends the message "Hello, world!" to the number 18007654321 via SMS. If the supplied phone number or message are badly formatted, an exception will be thrown.
To send a message to multiple recipients, you must create a Message object and add messaging addresses as recipients. You should retrieve
To register a listener that will receive alerts when a message comes in, use this line of code:
The listener must implement the IncomingMessageListener interface.
The MessagingService is the starting point for all messaging related tasks. Inside the MessagingService are a family of methods known as the "sendMessage" methods. They all look mostly like this:
This method's parameters contain the 3 basic things that you need to send a message: a message, a destination, and a protocol. A protocol is a set of standards that govern how addresses and messages can be formatted. In the real world we know that "billybones" is not a phone number and that Twitter messages must be less than 140 characters. Protocol objects contain this formatting information and validate your messages when you send them. In general, you should not interact directly with protocols, as they are only used by the MessagingService to make sure that your messages are well formed.
When you ask the MessagingService to send a message, it is checked for validity and then saved to the database with a status of "Outbox". Every 5 seconds, a scheduler task (called DispatchMessagesTask) grabs the new outbox messages from the database and sends them via "Gateways". Gateways are the messaging module's connections to the outside world - they are where the actual message sending takes place. For example, the Google Voice gateway maintains a connection to the Google Voice server using credentials provided in the management interface. Then, when it is told to send a message, it hands it off to Google Voice via an HTTP request.
At any given time there will be several gateways running. The messaging Module currently has 3 different gateways for sending SMS, one for sending Email, and one for sending OMail. You can check the status of your gateways and start or stop them in the "Manage Messaging Gateways" page. If there is a type of messaging that you would like to support, please feel free to implement a Gateway and a Protocol yourself.
When using or developing on the Messaging module, it's helpful to have an overview of exactly what happens when you send a message, what fields are set where, etc... The 'Architecture Overview' section above details some of this, but this section talks about the lifecycle of a message in more detail.
Below is a diagram of the data model of the Messaging Module. The MySQL Workbench file is included so you can play around with it and edit it if you want.