Note: Talkilla has now been superseded by the Loop project

	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 Code Configuration

An SPA's code should be in one directory, under static/spa/<spa name>. The directory structure may be whatever is appropriate. Other Talkilla files may be used, but we do not currently specify an API for these.

Configuration of the SPA is by a single file, static/spa/<spa name>/config.json. The file should contain:

{
  loginURL: "/url/to/login/page.html"
}

The loginURL should point to the URL of the iframe to load for logging into the service provider. Typically this is expected to be hosted on a provider's own site.

As detailed elsewhere, the url of the worker to use for the SPA is detailed in the talkilla.spa-enable message received from the login page and all other SPA loading/controls will come from the worker.

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. See the list below for the options.

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.

Capabilities

These are the possible capabilities an SPA can advertise:

• call: The SPA can make calls
• hold: The SPA supports hold and resume for calls
• move: The SPA supports call move to other devices
• spachannel: The SPA does not support the data channel and routes text messages and file transfers via its server.
• pstn-call: The SPA supports calls to a PSTN network

Call Handling

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

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

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

Receiving a message from Talkilla (e.g. call offer), listen for message of structure:

{topic: topic, data: <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. e.g. 0123456798 or foo@example.com

• <call id> contains the integer 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>}}

User Initiates a Call Move

This API only applies when the SPA advertises "move" in its capabilities

Talkilla send the message:

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

When the SPA has accepted the move request:

{topic: "move-accept", data: {peer: <peer>, callid: <call id>}}

Call Hold

This API only applies when the SPA advertises "hold" in its capabilities

Either Talkilla or SPA can send a message:

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

Receiving Call Resume from a Peer

This API only applies when the SPA advertises "hold" in its capabilities

The SPA can send a message:

{topic: "resume", data: {peer: <peer>, callid: <call id>, media: {
  video: <boolean> }
}}

Note: The media parameter is a temporary option until Firefox supports session re-negotiation. On receiving a resume message, Talkilla will only enable the video tracks if the video parameter is true.

Text Messages

This part of the API only applies when the SPA advertises "spachannel" in its capabilities

Sending a text message

This message can be sent either way.

{topic: "message", data: {peer: <peer>, type: "chat:message", message: <string>}}

• Peer is the peer the message is being sent to
• username is the user the peer was from

Typing notifications

{topic: "message", data: {peer: <peer>, type: "chat:typing", message: {}}

• Peer is the peer the message is being sent to
• username is the user the peer was from
• message is an empty object, it is not used - this may go away in the future.

File Transfer

This part of the API only applies when the SPA advertises "spachannel" in its capabilities

Starting a new file

This message can be sent either way.

{topic: "message", data: {peer: <peer>, type: "file:new",
 message: {filename: <string>, size: <integer>, id: <integer>, type:<string>}}

• Peer is the peer the message is being sent to
• filename is the filename string
• size is the size of the file
• type is the mime type of the file (if known).
• id is the identifier for this specific file transfer (e.g. will be different for different transfers of the same filename).

Sending a file chunk

{topic: "message", data: {peer: <peer>, type: "file:chunk", message: {id: <integer>, chunk: <chunk>}}

• Peer is the peer the message is being sent to
• id is the identifier for this specific file transfer
• chunk is the binary string for the file chunk

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