Cloud Modules Guide

Cloud Modules are the easiest way to integrate your Parse app with third-party services and libraries. Read on to learn how to add amazing features to your Parse app, from text messaging to email.

Can't Find the Cloud Module You're Looking For?

We're always looking to build more great Cloud Modules for services our users are interested in. Let us know what Cloud Module you would like to see next!

Getting Started

Learn how to create your own modules!

Cloud Modules work just like the JavaScript modules you can create yourself but they are readily available to everyone. You just add require('cloudModuleName') to your Cloud Code and you are ready to go! This guide will help you get started with the current set of available Cloud Modules. But, if you don't see the service you're interested in, fill out the feedback form above to let us know! You can also take a look at the our tutorial on how to create your own modules to integrate with your favorite APIs.

CrowdFlower Real Time Foto Moderator

CrowdFlower's Real Time Foto Moderator (RTFM) service provides human-powered image moderation that makes it super easy to ensure the images in your app or website do not contain inappropriate content. You can check out RTFM and sign up for an account on their website. To use this Cloud Module, you will need to sign up for a CrowdFlower account and obtain your RTFM API credentials.

Submitting Images

To start using this module, require it and enter your CrowdFlower API key. This key can be found in your CrowdFlower account under "API Settings".

var Crowdflower = require('crowdflower'); Crowdflower.initialize('myAPIKey');

To submit an image for moderation, you can use the module's submitImage function. Following the format described in theCrowdFlower documentation, you'll have to provide the URL of the image and optional metadata. This metadata can include any additional information you want to have available when the results of the moderation are returned.

For example, in a photo sharing application, we could send an image for moderation every time a new Image object is created using an afterSave. We'll send the image's URL by accessing the field of type 'File' where our image is stored, and we'll use the optional metadata to send both the 'objectId' and the 'className' of our Parse object. This additional information will allow us to identify the object when CrowdFlower gets back to us with the moderation results.

Parse.Cloud.afterSave("Image", function(request) {   var imageObject = request.object;     // Check if the object was newly created   if (!imageObject.existed()) {     Crowdflower.submitImage({       image : {         url: imageObject.get("myImageField").url,         metadata: {           objectId : imageObject.id,           className: imageObject.className         }       }     }, {       success: function(httpResponse) {         console.log(httpResponse);       },       error: function(httpResponse) {         console.log(httpResponse);       }     });   } });

Receiving Moderation Results

Once the image is screened, you can ask CrowdFlower to call a Cloud Code function. In our current example, we passed the 'objectId' and the 'className' of a Parse Object along with the image. As described in the CrowdFlower documentation, the data sent to this Cloud Function will have the following format.

{   "image": {     "id": IMAGE_ID,     "url": IMAGE_URL,     "score": IMAGE_SCORE,     "rating": IMAGE_RATING,     "state": IMAGE_STATE,     "metadata": {       "className": parseObjectClass,       "objectId": parseObjectId     }   } }

In our CrowdFlower callback function, we can use to metadata to fetch the Parse object associated with the image and save the rating value returned. We don't need to use the module in this Cloud Function.

Parse.Cloud.define("crowdflowerCallback", function(request, response) {   // The results and metadata of our CrowdFlower analysis   var results = request.params.image;     // Fetch the Parse Object associated by looking at the metadata we saved   var imageObject = new (Parse.Object.extend(results.metadata.className))();   imageObject.id = results.metadata.objectId   imageObject.fetch({     success: function(object) {       // Save the moderation rating value       object.set("rating", results.rating);       object.save(null, {         success: function(object) {           response.success("Yay!")         },         error: function(error) {           response.error("Something went wrong.")         }       });     },     error: function(object) {       response.error("Something went wrong.")     }   }); });

After defining the Cloud Function, we'll need to let CrowdFlower know how to reach it. To do this, set the Cloud Function's URL in the API settings page of your CrowdFlower account.

Note that the URL used for specifying the end point uses basic HTTP authentication. You will therefore need to set the URL using your Parse credentials in the following format:

https://myAppID:javascript-key=myJavaScriptKey@api.parse.com/1/functions/myCloudFunction

Mailgun

Mailgun is a set of powerful APIs that allow you to send, receive, track and store email effortlessly. You can check out their service at www.mailgun.com. To use this Cloud Module, you will need to head over to the Mailgun website and create an account.

The current version of the Mailgun Cloud Module supports sending emails. To use it in your Cloud Code functions, start by requiring the module and initializing it with your credentials.

var Mailgun = require('mailgun'); Mailgun.initialize('myDomainName', 'myAPIKey');

You can then use the sendEmail function to fire off some emails. This function takes two parameters. The first is a hash with the Mailgun parameters you want to include in the request. The typical ones are from, to, subject and text, but you can find the full list on their documentation page. The second parameter to this function is an object with a success and an error field containing two callback functions.

Mailgun.sendEmail({   to: "email@example.com",   from: "Mailgun@CloudCode.com",   subject: "Hello from Cloud Code!",   text: "Using Parse and Mailgun is great!" }, {   success: function(httpResponse) {     console.log(httpResponse);     response.success("Email sent!");   },   error: function(httpResponse) {     console.error(httpResponse);     response.error("Uh oh, something went wrong");   } });

For additional information about the Mailgun Cloud Module, take a look at the API Reference.

Mandrill

Mandrill provides a great platform for sending transactional email. It runs on the delivery infrastructure that powers MailChimp. You can check out their service on their website. To use this Cloud Module, you will need to head over to the Mandrill website and create an account.

The current version of the Mandrill Cloud Module supports sending emails. To use it in your Cloud Code functions, start by requiring the module and initializing it with your credentials.

var Mandrill = require('mandrill'); Mandrill.initialize('myAPIKey');

You can then use the sendEmail function to fire off some emails. This function takes two parameters. The first is a hash with the Mandrill parameters you want to include in the request. A full list is available on their documentation page, but here is an example of the common ones. The message object is required with every request and contains the email's data such as the text, thesubject and an array of recipients. Optionally, the async boolean value can be provided to ensure the request returns once the email is queued instead of waiting until it is sent. If you are sending an email to multiple recipients, you should set async to true to ensure your cloud function does not timeout. The second parameter to this function is an object with a success and an error field containing two callback functions for the request.

Mandrill.sendEmail({   message: {     text: "Hello World!",     subject: "Using Cloud Code and Mandrill is great!",     from_email: "parse@cloudcode.com",     from_name: "Cloud Code",     to: [       {         email: "you@parse.com",         name: "Your Name"       }     ]   },   async: true },{   success: function(httpResponse) {     console.log(httpResponse);     response.success("Email sent!");   },   error: function(httpResponse) {     console.error(httpResponse);     response.error("Uh oh, something went wrong");   } });

For additional information about the Mandrill Cloud Module, take a look at the API Reference.

Moment

Moment.js is a small JavaScript date library for parsing, validating, manipulating, and formatting dates. You can learn more about Moment on their website. To use it, you simply need to require it.

var moment = require('moment');

For additional information about the Moment.js Cloud Module, take a look at their API reference.

Parse Image

Images are the most common kind of Parse.File. The parse-image module provides an Image class that makes working with images in Cloud Code easier.

Reading Images from Files

To get started, create an Image using a Buffer with image file data. Usually, this data comes from a Parse.File. To read in the data from a file and create the image object, you can use our networking functions.

var Image = require("parse-image");   Parse.Cloud.httpRequest({   url: object.get("profilePhoto").url(),   success: function(response) {     // The file contents are in response.buffer.     var image = new Image();     return image.setData(response.buffer, {       success: function() {         console.log("Image is " + image.width() + "x" + image.height() + ".");       },       error: function(error) {         // The image data was invalid.       }     })   },   error: function(error) {     // The networking request failed.   } });

Cropping Images

To extract a particular rectangle of an image, use the crop method. This lets you specify the area of the image you want to keep.

// Crop the image to the rectangle from (10, 10) to (30, 20). image.crop({   left: 10,   top: 10,   right: 30,   bottom: 20,   success: function(image) {     // The image was cropped.   },   error: function(error) {     // The image could not be cropped.   } });

Alternatively, you can supply a width and height instead of right and bottom.

// Crop the image to the rectangle from (10, 10) to (30, 20). image.crop({   left: 10,   top: 10,   width: 20,   height: 10,   success: function(image) {     // The image was cropped.   },   error: function(error) {     // The image could not be cropped.   } });

Scaling Images

You can also resize an image, scaling the graphic using interpolation. Images can be made either smaller or larger. Just specify the new width and height. If you leave either off, it will assume the current image size.

// Resize the image to 64x64. image.scale({   width: 64,   height: 64,   success: function(image) {     // The image was scaled.   },   error: function(error) {     // The image could not be scaled.   } });

Sometimes it's more convenient to specify a ratio to resize to, instead of absolute dimensions.

// Resize the image to 25% of its original size. image.scale({   ratio: 0.25,   success: function(image) {     // The image was scaled.   },   error: function(error) {     // The image could not be scaled.   } });

Changing Image Formats

You can even change the file format of an image file. For example, you may want to convert a file to a JPEG to reduce file size and bandwidth usage.

// Change the image to be a JPEG. image.setFormat("JPEG", {   success: function(image) {     // The image was changed to a JPEG.   },   error: function(error) {     // The image could not be reformatted.   } });

Image Thumbnail Example

Every Image method returns a Parse.Promise in addition to having callbacks. This makes it easy to chain together multiple operations. Consider the common case where a user supplies an image to use for their profile. It's nice to be able to automatically generate a thumbnail of that photo to use in some of your UI. This can be done using a beforeSave handler.

var Image = require("parse-image");   Parse.Cloud.beforeSave("_User", function(request, response) {   var user = request.object;   if (!user.get("profilePhoto")) {     response.error("Users must have a profile photo.");     return;   }     if (!user.dirty("profilePhoto")) {     // The profile photo isn't being modified.     response.success();     return;   }     Parse.Cloud.httpRequest({     url: user.get("profilePhoto").url()     }).then(function(response) {     var image = new Image();     return image.setData(response.buffer);     }).then(function(image) {     // Crop the image to the smaller of width or height.     var size = Math.min(image.width(), image.height());     return image.crop({       left: (image.width() - size) / 2,       top: (image.height() - size) / 2,       width: size,       height: size     });     }).then(function(image) {     // Resize the image to 64x64.     return image.scale({       width: 64,       height: 64     });     }).then(function(image) {     // Make sure it's a JPEG to save disk space and bandwidth.     return image.setFormat("JPEG");     }).then(function(image) {     // Get the image data in a Buffer.     return image.data();     }).then(function(buffer) {     // Save the image into a new file.     var base64 = buffer.toString("base64");     var cropped = new Parse.File("thumbnail.jpg", { base64: base64 });     return cropped.save();     }).then(function(cropped) {     // Attach the image file to the original object.     user.set("profilePhotoThumbnail", cropped);     }).then(function(result) {     response.success();   }, function(error) {     response.error(error);   }); });

SendGrid

SendGrid provides a cloud-based email infrastructure that relieves businesses of the cost and complexity of maintaining custom email systems. To use this Cloud Module, you will need to head over to SendGrid's website and create an account.

The current version of the SendGrid Cloud Module supports sending emails. To use it in your Cloud Code functions, start by requiring the module and initializing it with your credentials.

var SendGrid = require("sendgrid");  SendGrid.initialize("sendgrid_username", "sendgrid_password");

You can then use the sendEmail function to fire off some emails. This function takes two parameters. The first is a hash with the SendGrid parameters you want to include in the request. The typical ones are from, to, subject and text, but you can find the full list on their documentation page. The second parameter to this function is an object with a success and an error field which contain two callback functions.

SendGrid.sendEmail({   to: "email@example.com",   from: "SendGrid@CloudCode.com",   subject: "Hello from Cloud Code!",   text: "Using Parse and SendGrid is great!" }, {   success: function(httpResponse) {     console.log(httpResponse);     response.success("Email sent!");   },   error: function(httpResponse) {     console.error(httpResponse);     response.error("Uh oh, something went wrong");   } });

For additional information about the SendGrid Cloud Module, take a look at the API Reference.

Stripe

Check out the Parse Store sample app!

Stripe provides a very easy-to-use API for processing credit cards on the web or in your mobile app. You can take a look at their service at www.stripe.com. To use this Cloud Module, you will need to head over to the Stripe website and create an account. The current version of the Stripe Cloud Module supports the majority of their REST API.

To use this module in your Cloud Code functions, start by requiring and initializing it with your credentials.

var Stripe = require('stripe'); Stripe.initialize('mySecretKey');

Charging a Credit Card

Charging a credit card using Stripe and Parse will usually follow this flow.

1. Getting a Credit Card Token

The first step to charging a credit card is to generate a token using the Stripe API. You should do this from your mobile or web client using your "publishable key". This will ensure that only Stripe manipulates the sensitive credit card information. If you are using iOS, you can use the Stripe iOS SDK, otherwise take a look at the Creating a Token section of their REST API documentation.

2. Calling your Cloud Code Function

After successfully creating a token, you can send the card token to a Cloud Code function. For more on creating and calling Parse Cloud Functions from the client SDKs or REST API, take a look at the Cloud Code Guide.

3. Charging the Credit Card

From a Cloud Code function, you can then use the Stripe Cloud Module to charge the credit card token. Using theStripe.Charges.create function you can specify the amount, currency, and card token to use for the purchase. The full list of available parameters can be found in Stripe's API documentation, but the following example demonstrates the basic use case.

Stripe.Charges.create({   amount: 100 * 10, // $10 expressed in cents   currency: "usd",   card: "tok_3TnIVhEv9P24T0" // the token id should be sent from the client },{   success: function(httpResponse) {     response.success("Purchase made!");   },   error: function(httpResponse) {     response.error("Uh oh, something went wrong");   } });

Available Functionality

There are many more functions available from the Stripe Cloud Module. Please consult the Stripe Cloud Module API reference for the full list of available functions and consult Stripe's own REST documentation for more information on how their platform works.

Twilio

Parse provides the full functionality of the Twilio-node module including SMS, Voice, and Twiml features. Please refer to the documentation here: Twilio-node module documentation. You do not need to install the module, as it is already installed and hosted on Parse.

Usage Example

// Require and initialize the Twilio module with your credentials var client = require('twilio')('ACCOUNT_SID', 'AUTH_TOKEN');   // Send an SMS message client.sendSms({     to:'+16515556677',     from: '+14506667788',     body: 'Hello world!'   }, function(err, responseData) {     if (err) {       console.log(err);     } else {       console.log(responseData.from);       console.log(responseData.body);     }   } );

Inbound Requests

With Express in Cloud Code, you can define routes to handle incoming requests. See the example webhook here. After creating the route and deploying, configure the URL with Twilio and your webhook will begin handling requests from Twilio.

Alternatively, it is also possible to create a Cloud Function that will receive a request from Twilio. This does not require the use of the Twilio Cloud Module, since the endpoint is set on the Twilio website. Start by defining a new Cloud Function.

Parse.Cloud.define("receiveSMS", function(request, response) {   console.log("Received a new text: " + request.params.From);   response.success(); });

You can then set this Cloud Function as the endpoint in your Twilio dashboard.

Note that the URL used for specifying the end point uses basic HTTP authentication. You will therefore need to set the URL using your Parse credentials in the following format:

https://myAppID:javascript-key=myJavaScriptKey@api.parse.com/1/functions/myCloudFunction

You will have access to all of the request data through request.params in your Cloud Function. The full list of available data can be found in the Twilio documentation.

For additional information about the Twilio Cloud Module, take a look at the twilio-node Reference.

Underscore

Underscore.js is a utility-belt library for JavaScript that provides a lot of the functional programming support. You can learn more about Underscore on their website. The Parse SDK uses this library internally but it is also available in Cloud Code using the underscore Cloud Module. To use it, you simply need to require it.

var _ = require('underscore');

For additional information about the Underscore.js Cloud Module, take a look at their API reference