9.4. mollom.getImageCaptcha

Note

The Mollom XML-RPC API interface has been deprecated, and is included here for archival purposes.

To develop clients and services that connect to Mollom, use the Mollom REST API.

mollom.getImageCaptcha
Required Name Type Description
required public_key string Site public key
required time string Site server time in this format: yyyy-MM-dd'T'HH:mm:ss-.SSSZ
required hash string HMAC-SHA1 digest
required nonce string One time nonce
optional session_id string Current session ID
optional author_ip string Submitting user's current IP address
optional ssl boolean use SSL to send the CAPTCHA to the user
returns session_id string Session ID associated with this CAPTCHA
returns url string URL of the CAPTCHA

An image CAPTCHA is an image that can be used to tell whether the poster of a comment or message is a human or a computer. To do so, the image displays a distorted text message that is hard to read for computer programs but still readable for humans. CAPTCHAs aim to stop spambots or automated scripts from posting comments or messages. The mollom.getImageCaptcha call instructs Mollom to generate an image CAPTCHA on the server-side.

The CAPTCHA APIs can be used in combination with mollom.checkContent or as a stand-alone API -- i.e., it can be used to protect a registration form without having to use Mollom's content analysis features.

If there is an active session ID for this operation because mollom.checkContent was already called or CAPTCHAs have already been called for a visitor's previous operations, it should be specified as the session id parameter. A session ID is a unique token that the Mollom server assigns to a session and specific operation that a site visitor tries to perform. Note that the Mollom sessions are in no way related to HTTP sessions. The first in a series of requests to the Mollom server requires no session ID. Mollom generates and assigns a new session ID and returns it to the client. Any further operations performed on this message must include its unique session ID. For example, if a user edits a message previously checked by Mollom, the client needs to send the new message data to Mollom together with its previously assigned session ID.

For example, if a website needs to request three CAPTCHAs in a row for a particular visitor, it is important that the website keeps track of the session id assigned by the Mollom server. For each of the subsequent requests, that session ID must be specified as part of the mollom.getImageCaptcha call. This is important because it helps the Mollom server identify visitors trying to break a CAPTCHA through brute force attempts.

Furthermore, session IDs can and should be reused across different call types. For example, if mollom.checkContent returns unsure and a visitor is asked to solve a CAPTCHA, the session ID returned by mollom.checkContent should be included in the call to mollom.getImageCaptcha. Note that Mollom cannot guarantee that the same session id passed into Mollom will be returned.

Mollom will respond to a successful request with an XML-RPC response message containing a session id and the URL of the CAPTCHA.

Generating CAPTCHAs on a central server helps make them more effective. As soon as Mollom's servers notice that spammers are able to break the CAPTCHAs with automated scripts or programs, Mollom can alter the way in which these messages are distorted and presented.

Mollom removes image CAPTCHAs from its servers that are more than 30 minutes old. Also note that every time a site visitor reloads a CAPTCHA image from Mollom's servers on any given URL, a different CAPTCHA will be presented. Only the text of the most recently loaded CAPTCHA can be used to solve the CAPTCHA. Developers please note: CAPTCHAs or CAPTCHA URLs should never be cached or stored locally.

When the ssl parameter is set to true, the CAPTCHA will be send to the visitor over a secured connection. The ssl parameter is only effective for Mollom Plus and Mollom Premium users. CAPTCHAs for Mollom Free users will always be send over an unsecured connection.

When you display the image CAPTCHA, please do not assume that the CAPTCHAs will always have the same size because the Mollom servers can return variable sized CAPTCHAs. For example, never hard code the width and height attributes of the HTML image tag.