The Moodgeist pinger protocol

The moodgeist pinger protocol is how Moodgeist collects its mood messages. We provide a reference Python client (see below), but you are more than welcome to contribute a pinger of your own, or embed MoodGeist into any of your Skype add-ons. There’s also an alpha Win32 GUI client — if you want it, ask Jaanus or Kevin.

Essentially, the ping is a simple HTTP POST request to the following URL: http://www.moodgeist.com/do/ping/. The POST must have these parameters. All parameters must be present.

All parameters except mood_text should be plain ASCII. mood_text supports international characters — it the POST, it must be a simple URL-encoded UTF-8 bytestream. UTF-8 also happens to be the encoding that the Skype API returns messages in, so you can just “pass them through” from the API to the POST (after proper URL-encoding, of course).

The ping URL returns a simple string with the numeric code and text explanation. The numeric code is also the HTTP response code.

• 200 OK. The server successfully received the ping and stored the mood message.
• 200 Duplicate. The server successfully received the ping, but this mood message was already recently captured for this Skype Name. It is possible to ping the same mood message twice if there were different moods set and pinged inbetween them, but recent duplicates are filtered out.
• 200 Too Similar. Ping received OK and the mood is slightly different from previously known, but still too similar to be considered.
• 200 SkypeWeb not enabled. That Skype Name has not opted in to SkypeWeb. Mood not saved. Read more on this update.
• 400 Invalid Protocol. Protocol number was invalid or unknown.
• 400 Parameters Missing. Some of the required parameters were missing.
• 400 Parameters Invalid. Some parameters had invalid contents (like Skype Name being too long).
• 400 Parameters Empty. Some of the required parameters had empty contents.
• 403 Forbidden. For various reasons, access to the ping node may have been denied to this pinger.
• 500 Server Error. There was a server-side error (like the database being down or crowded for a second).

Reference client

There’s a reference (example) Python client available: moodgeist-reference-pinger.py.txt. To run it, you also need the Skype Python API wrapper, although I patched a bit for my purposes: around line 170, disable all the self._send commands so that it wouldn’t send any “startup” commands on its own. Here’s my patched version — just drop it to Python’s “site-packages” folder.

The reference client illustrates how it should work — first you ping over everyone’s current mood from your contact list, and then you sit around processing ongoing mood change events.

You can leave the reference client running also for daily use if you’re of the hacker type, but for daily use, it’s not very practical, so we welcome friendlier versions of the Pinger, and also non-Win32 ones. The API connection sometimes dies for no apparent reason and it won’t inform you, so it’s not very resilient — if you notice the API connection was lost, just re-run it.