Messaging, for Melody and Movable Type
The Messaging plugin provides an implementation of a Twitter-like messaging system which allows an MT/Melody user to post and view status updates stored locally in the MT/Melody database and perform other actions supported by Twitter, such as following other users, sending direct messages, etc. Most timeline views can also be published to the published blogs for the benefit of site visitors who are not registered users.
In essence, this plugin provides features which enable MT/Melody to act as a standalone clone of Twitter.com in terms of the service’s functionality.
Enables MT/Melody users to post local status updates from the administrative interface via a Dashboard widget.
Provides a number of public, private and user-specific timeline views of existing updates, also accessible from the dashboard widget
Enables users to post and view status updates using any third-party Twitter client that supports alternate Twitter-API-compatible endpoint URLs
Provides a set of template tags for outputting the timeline views of the status updates to the published site, if desired
What it doesn’t do
To clear up the inevitable confusion, the following is a list of things this plugin does not do:
- Allow users to post status updates to Twitter.com
- Allow users to read status updates from Twitter.com
- Enable social actions (following, direct messages, etc) with Twitter.com users
- Movable Type 4.x or 5.1+
After downloading and unpacking the distribution archive, follow the directions in the standard plugin installation tutorial.
Next, for the API to operate properly, the following SetEnvIfNoCase directive is a required addition to the Apache config:
SetEnvIfNoCase ^Authorization$ "(.+)" HTTP_AUTHORIZATION=$1
The line above can be included in any part of the Apache configuration that
governs access to (i.e. is evaluated and executed upon request of) the
Messaging API script (
msg.cgi) though, if you are unsure, we would suggest
Apache server config (sudo or root access required)
If you have write access to your Apache configuration files, enclose the line above in a Directory block targeting the script’s parent directory (which is probably
If your site is running as a virtual host, the
Directoryblock should be created or already exist within a VirtualHost block.
If you do not have the necessary permissions to edit your Apache server config files but they contain the minimum required AllowOverride setting (
FileInfo), you can add the line to a file named .htaccess (that you will likely have to create) in the same directory as the script (which, again, is probably
NOTE: If you can access
$CGIPATH/msg.cgifrom your web browser, replacing
$CGIPATHwith the value of your installation’s
mt-config.cgidirective by the same name, you can skip this entire section!
This plugin provides a new
MessagingScript configuration directive which
msg.cgi and informs the system how to access the Messaging API
script relative to the
If you’ve renamed the script to something other than
msg.cgi, simply set
MessagingScript to the new script filename. For example, if you renamed it
message.cgi, you would add:
Or, if you moved the script with its original name, down into the plugin envelope, you would use:
Alternate API URL configuration
The plugin also supports an alternate method of defining the Messaging API URL
as a special accommodation for a wide myriad of niche cases and advanced
webserver configurations in which using
CGIPath as the root of the API URL
is either undesirable or not possible.
In this case, you can set the
MESSAGINGAPIURL environment variable to
the desired fully-qualified URL and this value will take precedence over
MessagingScript and will be used directly with no modifications.
Like the instructions in the Apache Configuration section above for
SetEnvIfNoCase directive, this can be set by adding the
following like to either in the Apache server config or in
SetEnv MESSAGINGAPIURL http://example.com/path/to/messaging.fcgi
You may notice that your Messages have a time stamp several hours off from what you expect.
Melody and Movable Type always save content with the date-time stamp set to GMT, then applies a time zone shift based upon your blog settings (the Timezone option in Preferences > General). Messaging is a system-level tool that doesn’t know about your blog timezone preference. You can make Melody and Movable Type aware of your preference with the [
TimeOffset Configuration Directive]. Example:
Republish a Template after Message Submission
If you’re using the Messaging template tags, you may want to force an index template to republish when a new Message is received. In the blog where your template can be found, visit Tools > Plugins and find the Messaging plugin. Within the plugin’s Settings you can find the option to republish a template. Select the index template to republish and save.
The selected template will be published (in the background) whenever a new Message is received.
Simple: The Messaging Dashboard Widget
As noted in the overview, this plugin provides an interface to the basics of Messaging: a Dashboard Widget which gives the user a view of the [public timeline] and allows them to update it with their own messages.
The widget can be added to either the blog- or system-level dashboard. Simply navigate to either page, select the “Messaging” widget from the “Select a Widget…” dropdown menu.
Administrative: Message listing and moderation screen
System administrators also have access to a message listing screen through which they can perform moderation duties, toggling a message’s visibility or deleting it outright. This screen can be accessed via:
- System Overview header nav dropdown » Messages, or
- System dashboard » Manage » Messages
Advanced: Third-party client access
The Messaging plugin’s programmatic interface conforms to the [Twitter API]. which also enables a user to interface with the system through any third-party Twitter client (e.g. the official Twitter client, Tweetie, TweetDeck, etc) which supports alternate Twitter-compatible services.
The default API URL endpoint to use in supporting clients is very similar to the main MT admin URL:
Messaging works with Basic authentication (not OAuth). The following Twitter API methods have been implemented and tested in Messaging:
The Dashboard Widget uses Ajax to access
statuses/update so if you want to use Ajax you can find those examples in
 - Not all methods are fully supported yet. See KNOWN ISSUES AND LIMITATIONS for details.
Authenticating with the Messaging API
For security reasons, an MT author’s password is never used to authenticate with the Messaging API. Instead, the user’s credentials are comprised of and validated against their username and API password.
The API Password is a special-use password automatically generated by the application when a user is first created and intended only for use with third-party web services and authoring tools such as blogging clients.
Use of the API password provides greater security because it causes the application to establish a restricted session which provides no access to the administrative interface and only a small subset of the functionality normally available to a user but that which is completely sufficient for executing a complete authoring-specific workflow.
The API Password can be found, retrieved and reset, if desired, on the user’s profile page.
Behind the Scenes
The Messaging plugin allows for long and short status messages: if you use the
Dashboard Widget you’ll see a 140-character counter. However, this limit is
mt_tw_message.tw_message_text field is a
“mediumtext” field, meaning it is limited to about 16 million characters.
Hashtags (example: #messaging) included in a message are abstracted out of the message and converted into Tags. “Private” hashtags are also supported (example: #@privatemessaging).
The Messaging plugin includes a search feature, just as the Twitter API does. Refer to the Twitter API documentation to use the search feature; below is some implementation information discovered during use that may not be clear from the Twitter docs.
use the required
q parameter to make keyword and hashtag searches. The
page (“limit” and “offset” in MT parlance) are also implemented for
keyword searches. Additional valid parameters:
Search results contain the following keys:
max_idis set to the highest ID in of the messages shown in the current results set if no
max_idparameter was supplied in the query. This means that if you do something like
q=foobar&page=2, you will get the highest ID on page 2, not the highest ID from the (invisible) page 1.
max_idis set in the query string, the
max_idin the result set will match with it, even if the message with that actual ID is not visible on the current page. Example:
q=foobar&page=2&max_id=30will show items from 15 on down, as item 30 is on page 1.
next_pageparameter always contains the
max_idstring, to guarantee a continuous list, even if new messages are inserted in the stream between queries.
Note that if you keep going for “next page” url the
max_idalways remains the same, since the ‘next page’ URL contains a
refresh_urlparameter will put you at the most recent message in the stream matching the query, but results are guaranteed to be more recent than the
since_idspecified. Note that you may have to query page=2, page=3… and so on to get all the messages, until no more messages are returned. Also note that each of these pages will have its own
refresh_urlwith a different
since_id, and that you shouldn’t “follow” them like the
next_pageURL if you are attempting to pull in a list of updates more recent than a specific
since_id. To do that you have to stick with the same
since_idand keep incrementing the page number until you run out of results.
The most common mechanism for status retrieval will undoubtedly be repeated polling through the Messaging API because it allows you to retrieve and display the latest update messages in real-time, as quickly as you can connect and retrieve them.
However if you want to do something like publish an message archive or collate messages and blog entries for interleaved display using the template tags provided by the plugin may be easier.
To publish any detail about a Message use the block tag
<mt:Messages>...</mt:Messages>. This block has the meta loop variables
has several valid arguments:
Specify the ID of a message to grab only that message.
An integer used to limit the number of results.
Start the results “n” topics from the start of the list.
If a message contains hashtags, they can be published as tags using the
<mt:MessageTags>...</mt:MessageTags> block tag. Within this block the
familiar Tag function tags can be used:
Valid arguments for this block tag are:
glueA text string that is used to join each of the items together.
include_privateSet to “1” to include both public and private (#@example) tags.
Most of these function tags act just as you’d expect:
Returns the ID of this message.
Returns the text of the message.
Returns the ID of the author associated with the message. Feed this to an Authors block to access the author context.
Returns the date of the message. Use any of MT’s date formatting modifiers when publishing.
Display the 10 newest messages:
<mt:Messages limit="10"> <mt:If name="__first__"> <h3>My awesome messages!</h3> <ul> </mt:If> <li id="message-<mt:MessageID>"> <div class="text"> <mt:MessageText> </div> <div class="author"> <mt:MessageAuthorID setvar="author_id"> <mt:Authors id="$author_id"> <mt:AuthorDisplayName> </mt:Authors </div>' <div class="created"> <mt:MessageDate format="%d/%m/%Y"> </div> </li> <mt:If name="__last__"> </ul> </mt:If> </mt:Messages>
KNOWN ISSUES AND LIMITATIONS
The Twitter API supports many other methods (and by extension features) that have not been implemented in Messaging. Some of these methods have had their implementation started (or even completed), but haven’t been tested or integrated with the rest of the capabilities of Messaging.
Search API Methods
search- Implemented according to the notes above.
POST lists id(update)
GET list id(show)
DELETE list id(destroy)
GET list statuses
GET list memberships
GET list subscriptions
List Members Methods
GET list members
POST list members
DELETE list members
GET list members id
List Subscribers Methods
GET list subscribers
POST list subscribers
DELETE list subscribers
GET list subscribers id
Direct Message Methods
Social Graph Methods - 0%
Spam Reporting Methods
Saved Searches Methods
SUPPORT, BUGS AND FEATURE REQUESTS
Please see http://help.endevver.com/ for all of the above.
Movable Type versions: 220.127.116.11