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 has finished loading (including all its dependencies; if any), it sends to Talkilla a message announcing it is ready to receive the user's credentials:

postMessage({topic: "ready", data: {capabilities: ["call"]}});

The capabilities array lists all the features supported by the SPA. "call" means the SPA is able to place calls and receive incoming calls. Other capabilities (still work in progress) include: "presence", "addressbook", ...

Talkilla will reply with a message containing the credentials: event.data will be:

{topic: "credentials", data: {token: auth_string}}

where auth_string is the string added to the callback URL by the service provider's website when redirecting the user to the Talkilla website after successfully authenticating the user.

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 'logged-in' message:

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

The (optional) capabilities array here is a subset of the capabilities announced with the 'ready' message. This is useful is the features supported depend on the plan the user has subscribed with the service provider.

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.

Receiving a call

postMessage({topic: "offer", data: {peer: "+16501231234", offer: {type:"offer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}});

Talkilla will either reply with an 'answer' message: event.data contains

{topic: "answer", data: {peer: "+16501231234", answer: {type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}}

or reject the call: (not implemented yet) event.data contains

{topic: "reject", data: {peer: "+16501231234"}}

Placing a call

event.data contains

{topic: "offer", data: {peer:"+33615827492", offer:{type:"offer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}}

The SPA can reply with an "answer" or "reject" message.

postMessage({topic: "answer", data: {peer:"webrtc@mailinator.com", answer:{type:"answer", sdp:"v=0\r\no=Mozilla-SIPUA..."}}});

"reject" is not implemented yet.

Ending a call

Either the SPA or Talkilla can send a 'hangup' message: From the SPA:

postMessage({topic: "hangup", data: {peer: "+16501231234"}});

From Talkilla: event.data contains

{topic: "hangup", data: {peer: "+16501231234"}}

Data Channel API Documentation

This is still being defined