Mobile Web

Messaging: Managing and Receiving SMS, MMS, and Email Messages

This tutorial demonstrates how you can create, send, and read messages as well as manage messages in the message storage.

This feature is supported in mobile applications only.

Warm-up

Become familiar with the Messaging API basics by learning about:

Task

In the Chatter task, we will walk through how to send, receive, and manage messages in your application.

Creating and Sending Messages

To create engaging applications with various messaging features, you must learn to create and send messages:

  1. Retrieve the messaging service using the getMessageServices() method. The first parameter specifies the type of the messaging service to retrieve. There are 3 possible types: "messaging.sms", "messaging.mms" and "messaging.email". In the following example, the SMS service is retrieved.

    function errorCallback(error) 
{
   console.log(error.name + ": " + error.message);
}

tizen.messaging.getMessageServices("messaging.sms", serviceListCB, errorCallback);

  2. In the success callback of the getMessageServices() method, use the Message interface to define the content and attributes of the message, and then send the message using the sendMessage() method of the MessageService interface.

    If the message is not ready to be sent yet, save the message draft using the addDraftMessage() method of the MessageStorage interface.

    function onAddSuccess()
{
   console.log("Successfully added");
}

function serviceListCB(services)
{ 
   /* Define SMS message */
   var msg = new tizen.Message("messaging.sms",
   {
      plainBody: "I will arrive in 10 minutes.",
      to: ["+34666666666", "+34888888888"]
   });

   var msgReady = true;

   if (msgReady)
   {
      /* Send SMS message */
      services[0].sendMessage(msg, messageSent, errorCallback);
   }
   else
   {
      /* Save a draft */
      services[0].messageStorage.addDraftMessage(msg, onAddSuccess, errorCallback); 
   }
}

    In case you are sending MMS or email messages with attachments, add the attachments as an array of MessageAttachment objects:

    var msg = new tizen.Message("messaging.email");
msg.attachments = [new tizen.MessageAttachment("images/myimage.png", "image/png"), 
                   new tizen.MessageAttachment("docs/mydoc.pdf","text/pdf")];

  3. Define the message sending success callback that is called if the message is sent successfully. (For email, that means that the message is sent to the email delivery system, not to the final recipient of the message.)

    For messaging technologies, such as SMS, where the message is sent individually to every message recipient, the success callback must be invoked individually for each recipient.

    function messageSent(recipients) 
{
   for (var i = 0; i < recipients.length; i++) 
   {
      console.log("The SMS has been sent to " + recipients[i]);
   }
}

    Defining a sending error callback allows you to handle all possible errors and exceptions that can occur causing the message delivery to fail.

Selecting the SIM Card for Sending Messages

To add the dual SIM feature to your messaging application, you must learn to retrieve information on available SIM cards and select the SIM card to send SMS and MMS messages:

  1. To check how many SIM cards are available, call the getCount() method of the SystemInfo interface. 
    var count = tizen.systeminfo.getCount("SIM");
if (count > 1)
{
   console.log("Dual SIM is supported");
}
  2. To retrieve additional information on the available SIM cards, use the getPropertyValueArray() method of the SystemInfo interface: 
    function getPropertySuccess(sims)
{
   for (var i = 0; i < sims.length; i++)
   {
      console.log("SIM" + (i+1) + " - " + sims[i].msisdn + " (" + sims[i].operatorName + ") " + sims[i].state);
   }
}
tizen.systeminfo.getPropertyValueArray("SIM", getPropertySuccess);

    The information can be presented to the user to let them select the SIM card they want.

  3. To send the message using the second SIM card, call the sendMessage() method of the MessageService interface specifying the SIM index as 2: 
    function sendSuccess()
{
   console.log("Message has been sent");
}

function serviceSuccess(messageService)
{
   message = new Message(messageService.type,
                         {
                            to: ["0001"],
                            plainBody: "Surprise!"
                         });
   /* SIM is selected (first SIM - 1, second SIM - 2):  */
   messageService.sendMessage(message, sendSuccess, null, 2);
}

tizen.messaging.getMessageServices("messaging.sms", serviceSuccess);

Managing Messages

To create engaging applications with various messaging features, you must learn to work with messages in the message store:

  1. Retrieve messages whose sender is "me" from the message storage using the findMessages() method of the MessageStorage interface with a filter (for attributes supported in the filter, see Messaging Filter Attributes):

    var emailService;
function serviceListCB(services) 
{
   emailService = services[0]; 
   /* Set the attribute filter */
   var filter = new tizen.AttributeFilter("from", "CONTAINS", "me");
       
   emailService.messageStorage.findMessages(filter, messageArrayCB);
}
tizen.messaging.getMessageServices("messaging.email", serviceListCB);

    The findMessages() method returns an array of Message objects as the search result.

    The search result does not contain the actual bodies of the messages. To load a message body, call the loadMessageBody() method of the MessageService interface.

  2. To update a message in the message storage, use the updateMessages() method. The method uses an array of Message objects found previously by the findMessages() method as a parameter.

    In the following example, the isRead attribute of the first Message object in the given array is updated to true.

    function successCallback()
{
   console.log("Success");
}

function messageArrayCB(messages) 
{
   messages[0].isRead = true;
   emailService.messageStorage.updateMessages(messages, successCallback);
}

  3. To delete a message from the message storage, use the removeMessages() method:

    function messageArrayCB(messages) 
{
   emailService.messagingStorage.removeMessages(messages, successCallback);
}

Finding Folders

To create engaging applications with various messaging features, you must learn how to find message folders:

  1. To retrieve the messaging service, use the getMessageServices() method of the Messaging interface: 

    var service;

function serviceListCB(services)
{
   console.log("Found " + services.length + " email services");
   service = services[0];
}

tizen.messaging.getMessageServices("messaging.email", serviceListCB);

  2. Define a success handler implementing the MessageFolderArraySuccessCallback interface, and optionally an error handler too:

    function onFindFolders(folders)
{
   console.log(folders.length + " folder(s) found.");

   for (var i = 0; i < folders.length; i++)
   {
      console.log("Folder " + (i + 1) + ": " + folders[i].name);
   }
}

function onFindFoldersFail(error)
{
   console.log("Error occurred:  " + error.name);
}

  3. Define a filter (for attributes supported by the message folder filter, see Messaging Filter Attributes):

    var filter = new tizen.AttributeFilter("serviceId", "EXACTLY", service.id);

  4. To get all message folders, use the findFolders() method of the MessageStorage interface:

    service.messageStorage.findFolders(filter, onFindFolders, onFindFoldersFail);

Synchronizing with the Server

To create engaging applications with various messaging features, you must learn to load email messages and attachments and synchronize email:

  1. Retrieve the messaging service using the getMessageServices() method. 

    tizen.messaging.getMessageServices("messaging.email", serviceListCB, errorCallback);

  2. Search for all email messages with attachments using the findMessages() method of the MessageStorage interface: 

    service.messageStorage.findMessages(new tizen.AttributeFilter("hasAttachment", "EXACTLY", true),
                                    messageQueryCallback);

  3. To load a message body, use the loadMessageBody() method of the MessageService interface:

    /* Success callback for the search operation */
function messageQueryCallback(messages)
{
   for (var i = 0; i < messages.length; i++)
   {
      var message = messages[i];
      if (!message.body.loaded)
      {
         tizen.messaging.loadMessageBody(message, successCallback, errorCallback);

  4. To download the message attachments, use the loadMessageAttachment() method with an array of attachments (with valid file paths) as a parameter:

             tizen.messaging.loadMessageAttachment(message.attachments[0], successCallback,
                                               errorCallback);
      }
   }
}

  5. To synchronize email with an external server:

    1. To synchronize all account folders, use the sync() method:

      /* Synchronize the folders in the success event handler */
function servicesListSuccessCB(services)
{
   services[0].sync(serviceSyncedCB, null, 30);
}

/* Get the email service */
tizen.messaging.getMessageServices("messaging.email", servicesListSuccessCB);
    2. To synchronize a specific folder, use the syncFolder() method. In the following example, only folders containing "INBOX" in their name are synchronized.

      var emailService; /* Assume email service is initialized */
function serviceCallback(services)
{
   emailService = services[0];
}

/* Synchronize in the search success event handler */
function folderQueryCallback(folders)
{
   for (var i = 0; i < folders.length; i++)
   {
      if (folders[i].type === "INBOX")
      {
         emailService.syncFolder(folders[i], folderSyncedCB, null, 30);
      }
   }
};

/* Get the email service */
tizen.messaging.getMessageServices("messaging.email", serviceCallback, errorCallback);

/* Search for specific folders */
var filter = new tizen.AttributeFilter("serviceId", "EXISTS");
emailService.messageStorage.findFolders(filter, folderQueryCallback));

Receiving Notifications on Message Storage Changes

To create engaging applications with various messaging features, you must learn to receive notifications when messages and message folders are added, updated, or removed:

  1. Define the needed variable: 
    /* Watch identifier */
var watchId;

  2. Define the event handlers for different notifications by implementing the MessagesChangeCallback listener interface:

    var messageChangeCallback =
{
   /* When messages are updated */
   messagesupdated: function(messages)
   {
      console.log(messages.length + " message(s) updated");
   },

   /* When messages are added */
   messagesadded: function(messages)
   {
      console.log(messages.length + " message(s) added");
   },

   /* When messages are deleted */
   messagesremoved: function(messages)
   {
      console.log(messages.length + " message(s) removed");
   }
};
  3. Register the listener to use the defined event handlers: 
    watchId = msgService.messageStorage.addMessagesChangeListener(messageChangeCallback);

  4. To stop receiving the notifications, use the removeChangeListener() method of the MessageStorage interface:

    msgService.messageStorage.removeChangeListener(watchId);
Note
To provide notifications for changes in specific conversations or message folders, use the applicable methods and event handlers similarly as above.
Go to top