Overview

Messaging Overview

The messaging system has a few different components that work together to send messages. Today, we support 3 different services: Email, Twitter, and Facebook. Each service has different requirements, and as such are a bit different. But, messaging is basically build and sent across all 3 of our repos, so it's a bit of a drag. :-)

So, to start, there is the connections to the APIs (the actual sending). The classes that do this are:

• Email: Oma::Mail::ServiceMailer / (as you will always send from a service). This encapsulates mapping both provider types of SMTP and ContextIO into a single mailer (both services work). This service uses Sendgrid. Sendgrid expects to do callbacks as well, and there is an API method that can be called by Sendgrid to give status updates on messages sent.

• Twitter: Oma::Api::Twitter / This is our API connection to Twitter. All twitter connections to the API should go through this service.

• Facebook: Oma::Api::Facebook.put_wall_post / Right now, all we can do is post to a wall.But, as we add additional actions, these should come through here.

For each message that is sent, it is backed by a document in our "Message" model. This document serves two useful purposes: first, this is what we show for messages that are sent and received in the system on the front end. And, second, it tracks the state of the message.

The key idea of "messaging addressing" is basically this: you can send from a service to a profile. Or receive a message from a profile to a service. Or, have a message to and from a profile. When you're building the message, you will set a from or to service (and it will handle setting names), and you will set a from and/or to profile (service and username).

The message model expect to have at least 1 username to send to.

I recently introduced MessageBuilder classes to build messages, to simplify building a message and make the messages more consistent. MessageBuilder::Twitter, MessageBuilder::Email, MessageBuilder::Facebook. Look at these, and their tests, for examples.

How "sharing" works

When someone on the front end clicks "share" and types something, it goes through the shares_controller.share_post. This method finds the service (that is sending), then builds a message to send them, writing it to our database. Then, it queues on the appropriate MessagingPipeline::Out::MessageToX Resque queue the message id for sending. When this queue picks up the job, it finds the message, then sends it.

Sending a Message Later

There is a queuer for messages that looks for messages that are pending publishing in the future, using their published_at. So, if you set a message to a state of "pending" and a published_at at a later time, do NOT push it to the MessagingPipeline::Out::MessagetoX queue.. that will sending it immediately. (by the way, this might not actually be implemented, as I can't find the queuer job on the cron).

Message states

Each message type has a unique set of states it can be in. All share "pending", and "sent" as a state. Messages, as they go through various states (like being sent, open, click, reply, in the case of email), the most recent state is set to the state attribute on the message. The previous state should be pushed to the events (as well as the current state). This is so other system that track state (like Automation) can do a comparison of this state to the previous state, and notify or take action when these items change.

Sendgrid (in the case of email) sends back api calls that give us updates. The class that manages this is Callbacks::Sendgrid. This updates the message with its new states. I am currently working on the same thing for Twitter, which is done by checking the general messaging on a service, and handling new things that come into those accounts. Nothing is built for Facebook as of yet.