View source for WebAPI/AppDefinedTelephony

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 [http://messaging.sysapps.org/ 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> }});

=== Add a Friend at Contacts App ===

== Import Contacts from Communication Apps ==
Since Communication Apps share their contacts through Data Store API, Contacts can import all Contacts.

== Format of Messages ==
All messages are shared through Data Store API.  Messages are SMS, MMS, EMail, and IM messages.

== 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 ==
T.B.D.

== Communication Apps ==
The communication apps are invoked through [[WebAPI/WebActivities|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.

[[Category:Web APIs]]