WebAPI/AppDefinedTeleophony

For B2G, communication applications likes Skype, WhatsApp, LINE, Facebook, Google plus..., etc, will define their owned communication protocols for short/instant messages, voice call, and contacts. The features of these applications are very similar to telephony, users may like to integrate all of them into one/or several place(s).

For most communication applications, they are comprised by contacts, call history, messaging, and voice/video call service. For voice/video call, it is very different from one application to another. So, every application should define their owned user interface to accept and initiate a call. But, for contact, call history, and messages, they are very similar for applications. By integrating contact, call history, and messages from all applications, the platform can provide better UX that users can browse and search all information at one place.

Following, this page is about changes of ContactsAPI, call history, and Messaging API

Contacts API

interface ContactField : nsISupports
{
  attribute DOMString handler;  // the application/or activity name that can handle voice/video call and messaging.
  attribute DOMURI status;      // an status icon as an indication of the presence (online/offline) of the user and alike.
  attribute DOMString[] type;   // for primary/favorite (use:"PREF"), "home", "work", etc.
  attribute DOMString value;
};

• |handler| and
• |status| fields

are added to ContactField interface. With them, the contact app can invoke the correct APP to initiate a voice/video call or concall.

For most IM now, |status| field can be used to show presence and status of a user. The communication Apps update this variable with URIs of icons to indicate if a user is online or offline or other cases. For handling changing of |status|, the App should listen on ContactsManager::oncontactchange event.

Add a Friend

Most communication Apps have their own contacts. The information in their contacts database are very similar. Basically, the user need only one copy of them. They don't want to maintain multiple copy of contacts. So, the user will keep all contacts in the database of Contacts API and forget contacts of communication Apps. But, communication Apps still maintain their-owned contacts for showing status of friends or for other purposes.

Make a Voice Call

When the user want to make a voice call to John; one of his friends,

• the user go to Contacts App to find out John.
• Then, the user press on John's Skype phone account.
• Contacts App ask the user what he want to do. Sending a message, making a voice call, or making a video call.
• The user ask for making a voice call.
• Contacts App make an activity for Skype to make a voice call to John.

Send a Message

When the user want to send a message to John; one of his friends,

• he go to Contacts App to find out John.
• Then, the user press on John's Facebook account.
• Contacts App ask the user what he want to do.
• The user ask for sending a message.
• Contacts App ask Facebook App to send a message to John.

Add a Number from Call History

So, the idea is to borrow the experience of mobile phone. When you ask your friend for phone number, you will call it at first to make sure the number is correct. Then, you create a new contact from call history. You select the number of your friend from call history and the phone will ask you what do you want to do. You ask the phone to add the phone number to contacts, then you pick up an existing contact or create a new one. It can also be applied to SIP phone or Skype.

• When the user make a call,
• it add a new record with Call History API.
• Then, the user read all history with Call History App,
• and select the SIP phone number/address or Skype friend account to create a new contact, or add it to an existing one.

Add a New Friend at Communication App

Another scenario is to wake up Contacts App to handle the new friend account/address/or number when adding a new friend in a communication App. That is saying,

• when the user add a friend in Skype,
• Skype will wake up Contacts App; with Web Activities, and ask it to remember the friend account.
• Then Contact App will ask the user if he want to create a new contacts or to add the account/address/or number to an existing contacts.

Add a Friend at Contacts App

The user can also initiate an action of adding a new Skype friend at Contacts App. The following description is a possible UX.

• The user press on an existing contact.
• Contact App ask the user what he want to do.
• The user ask Contact App to add a new contact address for the contact.
• Contact App ask the user what kind of address; Skype, Twitter, WhatsApp, ... etc.
• The user ask Contact App to add a Skype address.
• Contacts App wakes up Skype for adding a new friend.
• The user add a new friend of Skype, and Skype will check if the account is valid.
• If it is a valid account, and the peer, the friend, accept the request of adding as a friend. Then,
  • add the address to the contact that the user choose to initiate the action, or
  • postResult() with peer's account/address.

Import Contacts from Communication Apps

To import Contacts from a Communication App; Skype for example, it add new contacts with Contacts API.

Messaging API

interface Messaging {
   readonly    attribute SmsManager sms;
   readonly    attribute MmsManager mms;
   MessagingRequest findMessages (MessagingFilter filter, FilterOptions options);
   MessagingRequest findConversations (DOMString groupBy, MessagingFilter filter, FilterOptions options);
   MessagingRequest getMessage (DOMString id);
   MessagingRequest deleteMessage (DOMString id);
   MessagingRequest deleteConversation (DOMString id);
   MessagingRequest markMessageRead (DOMString id, boolean value);
   MessagingRequest markConversationRead (DOMString id, boolean value);
   MessagingRequest addArrivedMessage(MmsMessage msg);        // IM or Telephony Apps can add a new message as a new arrival.
};

interface Message {
   readonly    attribute DOMString id;
   readonly    attribute DOMString handler;  // the application that can handle the message for replying or sending.
   readonly    attribute DOMString receiver; // the account receiving the message.
   readonly    attribute DOMString sender;
   readonly    attribute Date      timestamp;
   readonly    attribute boolean   read;
};

• addArrivedMessage() is added to Messaging to let communication Apps add a message for a new arriving message.
• handler is added to Message to record the application can handle replying the message.
• receiver is the account receiving the message. It is used by the handler to distinguish the user of the service. The message app is not supposed for responding for editing messages. It should wake up the handler of the message for editing. (MUA is an example.)

type and serviceID can be removed and replaced by |handler| and |receiver| while |receiver| are used to distinguish different SIM.

MmsMessage are suggested for more flexible that handler can format the message in HTML to provide a rich representation.

Should we provide a way for synchronization between the database of Messaging API and App's local storage?

Reply a Message

• When the user reading a message with a Message App,
• the user press on a "Reply" button.
• The Message App send a Web Activity for the name given by Message::handler; for ex. "Twitter", and with the Message ID.
• Then, the communication App is responsible for editing and sending a message.

Message::receiver, for here, are used by the communication App to determine an account for replying the message if the App supports multiple accounts for an installation. The user may change the sender of a message instead of the value from Message::receiver. For example, some MUAs allow users to assign |From| field while composing a message.

Call History

There is no API for call history. We need a new API for that. It must have the capability of telling what the App can handle an address/number in the call history.

Communication Apps

The communication apps are invoked through Web Activities. A communication App should provide following functions.

• initiate a voice/video call to a receiver
• reply an existing message in the database of Messaging API
• send a new message to a given receiver
• show a user in contacts
• add a new friend account/address for an existing contact.

The communication apps are responsible for handling incoming calls and messages. But, they store contacts, messages, and call history in ContactsAPI, Messaging API, and call history API.

Communication Apps should be registered with their capabilities; messaging, voice call, and video call, so a contacts app can provide correct functions on UI to the user for a given address handled by a communication App. That means we should provide an API to query capabilities of and list apps.