# com.innovaphone.phoneinfo

This API is used for communication with phone/softphone apps and is closely related to API com.innovaphone.phone.

If an App provides this API the myApps client will start the App automatically if any call related messages are availble. The App will receive messages "CallAdded" and "CallUpdated" and "CallRemoved" and can provide call-related display information to the phone app (e.g. about remote party) by consuming the com.innovaphone.phone API.

An App Client API or App Service API must be announced by the App Service, prior it can be used in the App Client. Please refer to the AppWebsocket App Platform Library documentation or JavaScript Runtime config documentation.

## provideApi

The provideApi function is used to subscribe for API messages:

    var phoneinfoApi = start.provideApi("com.innovaphone.phoneinfo");
    phoneinfoApi.onmessage.attach(function (sender, obj) {
        switch (obj.msg.mt) {
        case "CallAdded":
            break;
        case "CallUpdated":
            break;
        case "CallRemoved":
            break;
        }
    });

## Messages

CallAdded, CallUpdated, CallRemoved

### CallAdded

Send by Phone-App to all API providers whenever a new call is born.

    {
        mt: "CallAdded",
        id: 1,
        guid: "fff79c5bd2115d0109f400903341035b"
    }

#### Parameters

string mt | message type [mandatory]
number id | unique call-id [mandatory]
string guid | globally unique call-id [optional]

### CallUpdated

Send by Phone-App to all API providers whenever call's attributes have changed.

    {
        mt: "CallUpdated",
        id: 1,
        guid: "fff79c5bd2115d0109f400903341035b",
        dir: "i",
        num: "200",
        sip: "charlie.chaplin",
        dn: "Sir Charles Spencer Chaplin",
        lastDiverting: "David Llewelyn Wark Griffith",
        originalCalled: "Mary Wayne Marsh",
        state: "Connected"
     }

#### Parameters

string mt | message type [mandatory]
number id | unique call-id [mandatory]
string guid | globally unique call-id [optional]
string dir | "i" for inbound call or "o" for outbound call [mandatory]
string num | Phonenumber (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 | Displayname [optional]
string lastDiverting | Displayname or Phonenumber of last diverting party [optional]
string originalCalled | Displayname or Phonenumber of first diverting party [optional]
string state | Setup | Dialing | Ringback | Queued | Alerting | Connected | Holding | Held | Disconnected [mandatory]

### CallRemoved

Send by Phone-App to all API providers whenever a call has died.

    {
        mt: "CallRemoved",
        id: 1,
        guid: "fff79c5bd2115d0109f400903341035b"
    }

#### Parameters

string mt | message type [mandatory]
number id | unique call-id [mandatory]
string guid | globally unique call-id [optional]

## Example

An App can provide call-related display information to the phone app (e.g. about remote party).
See API "com.innovaphone.phone" for details.

    var phoneApi = start.consumeApi("com.innovaphone.phone");
    var phoneinfoApi = start.provideApi("com.innovaphone.phoneinfo");
    phoneinfoApi.onmessage.attach(function (sender, obj) {
        switch (obj.msg.mt) {
        case "CallAdded":
            break;
        case "CallUpdated":
            if (obj.msg.state == "Connected") {
                phoneApi.send({ mt: "CallInfo", id: obj.msg.id, guid: obj.msg.guid, html: "<div>Here's my info</div>" }, obj.consumer);
            }
            break;
        case "CallRemoved":
            break;
        }
    });