Talkilla/SPA API

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

SPA API Documentation

The SPA (service provider Adaptor) is a JavaScript file. Its purpose is to adapt a service provider's REST API to Talkilla's API. Each SPA is loaded in its own web worker (http://dev.w3.org/html5/workers/). Communication between the SPA and talkilla happen via a message port (using onmessage and postMessage, see https://developer.mozilla.org/en-US/docs/Web/Guide/Performance/Using_web_workers#Passing_data ) Note: workers have no access to the DOM (ie. no 'window' or 'document' objects).

Example:

// sending a message from the SPA worker to Talkilla:
postMessage({topic: "hello", data: {details: "hello world!"}});

// receiving a message from Talkilla:
function onmessage(event) {
  // event.data.topic contains the topic of the event.
  // The event.data.data object can contain additional data associated with the message.
}

The SPAs are hosted on Talkilla's web server. To allow REST API calls on the service provider's servers hosted on other domains, these servers will need to send the Access-Control-Allow-Origin HTTP response header. See https://developer.mozilla.org/en/docs/HTTP/Access_control_CORS for more information.

It is advisable to make the Javascript web worker as lightweight as possible, as this will be continuously running in the background of the browser.

SPA Installation

A list of supported service providers is presented on the Talkilla website. To install a new service provider in Talkilla, the user clicks on the name of the provider. This loads the provider's website, where the user needs to login (using existing credentials or creating a new account on the service provider's website). Once the user has been successfully identified by the service provider, the user is redirected to the Talkilla website.

Technically, this is similar to the oauth flow. The authentication sequence starts when the user clicks on the Talkilla website a link pointing to the service provider's website. The link includes a callback URL where the user should be redirected once the user's credentials have been verified. A token is added to the callback URL by the service provider's website. This token will be used to start the SPA.

SPA initialization

When Talkilla starts within SocialAPI, as part of its initialization, it will start a web worker (https://developer.mozilla.org/en-US/docs/Web/Guide/Performance/Using_web_workers ) for each installed SPA.

When the SPA is loaded, Talkilla will send a message containing the credentials to connect the SPA to its provider: event.data will be:

{topic: "connect", data: <credentials>}

where 'credentials' is an arbitrary object containing the user's credentials for this SPA/Provider.

At this point, the SPA can start connecting to the service provider's servers. If the SPA connected successfully and is ready to receive calls, it will send to Talkilla a 'connected' message:

postMessage({
  topic: "connected",
  data: {
    addresses: [{type: "pstn", value: "+33698234520"},
                {type: "email", value: "james@operator.com"}],
    capabilities: ["call"],
    settingURL: "https://operator.com/settings"
  }
});

The capabilities, addresses and settingURL are not implemented yes.

The (optional) capabilities array here is a set of capabilities supported by the SPA for the connected user service.

The settingURL is the address of a webpage that the user can load by clicking in the UI. Note: currently only the first address will be used. 'addresses' is an array because in the future service providers may be allowed to identify more than one address for the same user.

If the token given to the SPA by Talkilla leads to authentication failure, the SPA can notify Talkilla that showing a web page asking the user to login again will be required.

postMessage({topic: "reauth-needed", data: {loginURL: "https://operator.com/login", details: "Session has expired."}});

After receiving this message, Talkilla will display an error icon in an appropriate position. 'details' is a human readable error message explaining why the SPA couldn't connect to the service provider; it will likely be shown if the user hovers the error icon. 'loginURL' is the address of a webpage that will be loaded if the user clicks on the error icon.

Note: Needing to re-authentify the user to connect is an error. Having to login on the service provider's website shouldn't be required each time the browser is restarted.

Call Handling

Messages that handle calls, can go two ways from the Worker to the SPA and vice-versa.

To send a message to the worker (e.g. incoming call):

postMessage({topic: <topic>, data: })

Receiving a message from the worker (e.g. call outgoing), listen for message of structure:

{topic: topic, data: }

Call Handling Data Structures

These are the data structures associated with calls

• <peer> is a string which is the id of the peer that the call is with.

• <call id> contains the call id for a single call sequence.
  • This is used to ensure that messages from one call with a peer don't affect other calls/actions with the same peer.
  • Currently, sending a new call id for a call with a peer does not force a new call to be started.

• <session desc> is a serialized object equivalent of RTCSessionDescription
  • Type will be offer for an incoming call offer, and answer for a response to an offer.

{ type: "answer", sdp: "v=0\r\no=Mozilla-SIPUA..."}

• <ice candidate> is a serialized object equivalent of RTCIceCandidate e.g.

{candidate: "candidate string", sdpMid: "media stream id", sdpMLineIndex: 2}

Call Flows

Users Receives a Call

Send from the SPA to Talkilla:

{topic: "offer", data: {peer: <peer>, offer: <session desc>, callid: <call id>}}

When the user answers, Talkilla will post the following to the SPA:

{topic: "answer", data: {peer: <peer>, answer: <session desc>, callid: <call id>}

== User Places a Call

Talkilla sends to the SPA:

{topic: "offer", data: {peer: <peer>, offer: <session desc>, callid: <call id>}}

When the other end answers, the SPA will send to Talkilla:

{topic: "answer", data: {peer: <peer>, answer: <session desc>, callid: <call id>}

Talkilla will time out call offers after 30 seconds, at this time a call hangup is sent (see below).

Ending a Call

Either Talkilla or SPA can send a message:

{topic: "hangup", data: {peer: <peer>, callid: <call id>}}

Handling ICE Candidates

Firefox is capable of Trickle ICE. After an initial call offer or answer, there may be additional ICE candidates. Hence these may be sent from either side.

ICE candidates may be sent from either Talkilla to the SPA or vice-versa depending on which part of the call they are coming from:

{topic: "ice:candidate", data: {peer: <peer>, candidate: <ice candidate>}}

When the ICE candidate list is complete, a message with a null data value will be passed:

{topic: "ice:candidate", data: {peer: <peer>, candidate: null}}

Data Channel API Documentation

This is still being defined