4
edits
Talkilla/SPA API: Difference between revisions
Update the event format: {topic: "foo", details: "bar"} becomes {topic: "foo", data: {details: "bar}}
(Created page with "=SPA API Documentation= This documentation is currently a draft. The SPA (service provider Adaptor) is a JavaScript file. Its purpose is to adapt a service provider's REST AP...") |
(Update the event format: {topic: "foo", details: "bar"} becomes {topic: "foo", data: {details: "bar}}) |
||
| Line 7: | Line 7: | ||
Example: | Example: | ||
// sending a message from the SPA worker to Talkilla: | // sending a message from the SPA worker to Talkilla: | ||
postMessage({topic: "hello", details: "hello world!"}); | postMessage({topic: "hello", data: {details: "hello world!"}}); | ||
// receiving a message from Talkilla: | // receiving a message from Talkilla: | ||
function onmessage(event) { | function onmessage(event) { | ||
// event.data.topic contains the topic of the event. | // event.data.topic contains the topic of the event. | ||
// The event.data object can contain additional data associated with the message. | // The event.data.data object can contain additional data associated with the message. | ||
} | } | ||
| Line 29: | Line 29: | ||
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: | 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", capabilities: ["call"]}); | 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. | The capabilities array lists all the features supported by the SPA. "call" means the SPA is able to place calls and receive incoming calls. | ||
| Line 36: | Line 36: | ||
Talkilla will reply with a message containing the credentials: | Talkilla will reply with a message containing the credentials: | ||
event.data will be: | event.data will be: | ||
{topic: "credentials", token: auth_string} | {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. | 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. | ||
| Line 42: | Line 42: | ||
If the SPA connected successfully and is ready to receive calls, it will send to Talkilla a 'logged-in' message: | If the SPA connected successfully and is ready to receive calls, it will send to Talkilla a 'logged-in' message: | ||
postMessage({topic: "logged-in", | 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 (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. | ||
| Line 55: | Line 59: | ||
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. | 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", loginURL: "https://operator.com/login", details: "Session has expired."}); | 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. | After receiving this message, Talkilla will display an error icon in an appropriate position. | ||
| Line 64: | Line 68: | ||
==Receiving a call== | ==Receiving a call== | ||
postMessage({topic: "offer", from: "+16501231234", | postMessage({topic: "offer", data: {from: "+16501231234", offer: <offer>}}); | ||
Talkilla will either reply with an 'answer' message: | Talkilla will either reply with an 'answer' message: | ||
event.data contains | event.data contains | ||
{topic: "answer", to: "+16501231234", | {topic: "answer", data: {to: "+16501231234", answer: <answer>}} | ||
or reject the call: | or reject the call: | ||
event.data contains | event.data contains | ||
{topic: "reject", to: "+16501231234"} | {topic: "reject", data: {to: "+16501231234"}} | ||
==Placing a call== | ==Placing a call== | ||
event.data contains | event.data contains | ||
{topic: "offer", to: "+33615827492", | {topic: "offer", data: {to: "+33615827492", offer: <offer>}} | ||
The SPA can reply with an "answer" or "reject" message. | The SPA can reply with an "answer" or "reject" message. | ||
| Line 81: | Line 85: | ||
Either the SPA or Talkilla can send a 'hangup' message: | Either the SPA or Talkilla can send a 'hangup' message: | ||
From the SPA: | From the SPA: | ||
postMessage({topic: "hangup", from: "+16501231234"}); | postMessage({topic: "hangup", data: {from: "+16501231234"}}); | ||
From Talkilla: event.data contains | From Talkilla: event.data contains | ||
{topic: "hangup", to: "+16501231234"} | {topic: "hangup", data: {to: "+16501231234"}} | ||
=Data Channel API Documentation= | =Data Channel API Documentation= | ||
This is still being defined | This is still being defined | ||