# com.innovaphone.phone

This API is used for communication with phone/softphone apps.

## consumeApi

The provideApi function is used to subscribe for API messages:

    var phoneApi = start.consumeApi("com.innovaphone.phone");

    phoneApi.send({ mt: "StartCall", num: "123" });

    phoneApi.onupdate.attach(function (sender, type) {
        Object.keys(sender.model).forEach(function (key) {
            var provider = sender.model[key];
            if (provider.model.calls) {
                provider.model.calls.forEach(function (call) {
                    ...
                }
            }
        }
    });

## Messages

Start, StartCall, PrepareCall, ConnectCall, DisconnectCall, CallInfo

## Start

Starts the default app for Telephony.

    { mt: "Start", background: true }

#### Parameters

boolean background | Instructs the API provider to stay in background while the sender app of this message is running. [optional]

## StartCall

Starts a new call to the given phone number or SIP-URI.

    { mt: "StartCall", num: "200" }
    { mt: "StartCall", sip: "bob@example.com" }
    { mt: "StartCall", txt: "+49 (7031) 73009 - 0" }
    { mt: "StartCall", num: "07031730090", adjust: true }

#### Parameters

string num | Phone number to be dialed [optional]
string sip | SIP-URI to be dialed [optional]
string txt | Unclassified dialstring. Phoneapp will check and take it as 'num' or 'sip' [optional]
boolean adjust | Indicates that the number might not contain the external line prefix and might need to be added by the phone/softphone app before dialing [optional]

## PrepareCall

Similar to "StartCall", but does not initiate the call automatically. User can verify the call destination and intiate call by clicking button.

## ConnectCall

If there's an incoming call on the phone/softphone app in "Alerting" state it can be connected with this message.

    { mt: "ConnectCall" }

## DisconnectCall

If there's an active call on the phone/softphone app any state it can be disconnected with this message.

    { mt: "DisconnectCall" }

## CallInfo

An app can monitor call activity on phone/softphone apps and can provide context information for the call to be displayed in phone/softphone app.
An app can either provide a piece of HTML code or an URL which is loaded in an iframe. See Provider Model on how to monitor call activity on phone/softphone apps.

    { mt: "CallInfo", id: 1, html: "<div style='color: white'>Aloha from Apidemo</div>" }
    { mt: "CallInfo", id: 1, iframe: { src: "https://wikipedia.de/", height: "300px" } }

#### Parameters

number id | unique call-id [mandatory]
string html | HTML to be embedded [optional]
object iframe | [optional]
string src | URL of the HTML page to be embedded as iframe [optional]
string height | Height of the embedded iframe [optional]
number autoshow | activates the automatic display of the frame. The highest value is displayed first.[optional]

## API model

### Service info

List of apps providing this API

    "com.innovaphone.phone": {
        "dev:SwPh_5c6aa38f": {
            title: "Softphone",
            info: {
                type: "softphone"
            },
            model: {}
        },
        "dev:00903332024b": {
            title: "IP232",
            info: {
                type: "phone"
            },
            model: {
                registered: true,
                calls: []
            },
        }
    }

#### Parameters

string type | Type of providing app: phone (an app controlling a hardware phone) softphone (an app that can do phone calls by itself without using a hardware phone)

### Provider model

    {
        registered: true,
        calls: [
            {
                id: 1,
                guid: "fff79c5bd2115d0109f400903341035b",
                dir: "i",
                num: "200",
                sip: "charlie.chaplin",
                dn: "Sir Charles Spencer Chaplin",
                state: "Connected"
            }
        ]
    }

#### Parameters

number id | uniqe call-id [mandatory]
string guid | globally uniqe call-id [optional]
string dir | "i" for inbound call or "o" for outbound call [mandatory]
string num | Phone number (e.g. 202 or +49 7031 73009 0) [optional]
string sip | SIP-URI (e.g. charlie.chaplin or charlie.chaplin@unitedartists.com) [optional]
string dn | Display name [optional]
string state | Setup | Dialing | Ringback | Queued | Alerting | Connected | Holding | Held | Disconnected [mandatory]