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 ContactProperties {
               attribute DOMString[]       name;
               attribute DOMString[]       honorificPrefix;
               attribute DOMString[]       givenName;
               attribute DOMString[]       additionalName;
               attribute DOMString[]       familyName;
               attribute DOMString[]       honorificSuffix;
               attribute DOMString[]       nickname;
               attribute ContactField[]    email;
               attribute DOMString[]       photo;
               attribute ContactField[]    url;
               attribute DOMString[]       categories;
               attribute ContactAddress[]  adr;
               attribute ContactTelField[] tel;
               attribute DOMString[]       org;
               attribute DOMString[]       jobTitle;
               attribute Date              bday;
               attribute DOMString[]       note;
               attribute ContactField[]    impp;
               attribute Date              anniversary;
               attribute DOMString         sex;
               attribute DOMString         genderIdentity;
};
interface ContactField : nsISupports
{
  attribute DOMString[] type;   // "home", "work", etc.
  attribute DOMString   value;
  attribute boolean     pref; // false = no pref, true = preferred (vCard3 TYPE:PREF; vCard4 PREF:1)
};

• https://wiki.mozilla.org/ContactsAPI
• http://tools.ietf.org/html/rfc4770

Add a Friend

Most communication Apps have their own contacts. By using a common format of data and sharing through Data Store API, all contacts can be showed in one application to provide an integrated user experience. Contacts of an user may be provided by several applications redundantly. The Contacts App may group and aggregate them together to provide a better UX.

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 listed in immp field.
• 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.

var act = new Activity({name: "telephony::Skype", data: { action: "voicecall", callee: "John" }});

Send a Message

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

• the user 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.
• User input a message in Facebook App, and press the "Send" button to send it out.

var act = new Activity({name: "telephony::Facebook", data: { action: "sendmessage", receiver: "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 SIP call,
• SIP App add a new record in the Data Store for the Call History.
• Then, the user read all history with Call History App,
• and select the record to create a new contact,
• then, the Call History App ask SIP App to add that record to it's contacts.
• the Call History App receives a notification for the new contact being created.

var act = new Activity({name: "telephony::SIP", data: { action: "addcontact", callhistoryid: <object id> }});

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 object ID of Data Store.
• Then, the communication App is responsible for editing and sending a message.

var act = new Activity({ name: "telephony:Twitter", data : { action: "replymessage", message: <object ID> }});

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.