Webportal v2

embedded apps

API Reference - phone.call

Edit
Required Privacy: Location
Operations:
GET
phone.call
Edit

This API allows use phone functionnility of the webportal.

phoneList is an array of phones connected to the vehicle, if is empty, no phones are connected to the vehicle. In each phone you can have a callList which is an array of calls for this phone (you can have multiple calls for one phone in case of a call being on hold), if is empty, no calls are currently in progress.

Input Parameter
No input params
Output Data
Data name Description Type Unit/Values Example
phoneList[n]
 .phoneId

Phone identifier of the device.

string

n/a

 		bt://11:22:33:44:55:66
phoneList[n]
 .callList[m]
  .callId

Identifier of the Call.

string

n/a

 		+33 (0) 6 01 02 03 04
phoneList[n]
 .callList[m]
  .callState

Current status of the call.

string

 - ringing: 'incoming call, ringtone phase'
- dialing: 'outgoing call, ringtone phase'
- active: 'phone conversation in progress'
- holding: 'call is on hold, another call is active'
- idle: 'call hung up' 		ringing
phoneList[n]
 .callList[m]
  .normalizedPhoneNumber

Real number used for dialing, may differ from callId.

string

phone number

 		+33601020304
phoneList[n]
 .callList[m]
  .name

Name of the remote caller or null if none

string

n/a

 		Alice
phoneList[n]
 .callList[m]
  .imageUrl

Image of the remote caller or null if none. Could be a Base64 encoded image or a local filesystem image

string

dataURI

 		data:image/png;base64,...
phoneList[n]
 .callList[m]
  .callDuration

Phone call current duration.

integer

second

 		106
Code Example 
1
2
3
4
5
6
7
8
9
10
11
12
13

webportal.get(
    /* api name */
    "phone.call",
    /* parameters */
     null
  )
  /* callback for `REPLY` messages */
  .then((message) => {
    if (message.status === 200) {
      /* handle `REPLY` success */
    }
    else { /* handle `REPLY` error */ }
  })

1
2
3
4
5
6

{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0", 
  "type": "GET", 
  "api": "phone.call",
  "params":  null
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// --- format of the `REPLY` message ---

{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0",
  "type": "REPLY",
  "api": "phone.call",
  "status": 200,
  "statusText": "OK", 
  "data": {
    "phoneList": [
      // First phone, 2 calls
      {
          "phoneId": "bt://11:22:33:44:55:66",
          "callList": [
            // First phone, First call
              {
                  "callId": "+33 (0) 6 01 02 03 04",
                  "callState": "active",
                  "name": "John Doe",
                  "normalizedPhoneNumber": "+33601020304",
                  "imageUrl": "data:image/png;base64,...",
                  "callDuration": 123 
              },
              // Second Phone, Second Call

              {
                  "callId": "+33 (0) 6 11 22 33 44",
                  "callState": "holding",
                  "normalizedPhoneNumber": "+33611223344",
                  "name": "Jane Smith",
                  "imageUrl": "file:///vdappdata/addressbook/avatar/194.png",
                  "callDuration": 23
              }
          ]
      },
      // Second Phone, No Call
      {
          "phoneId": "iap2://..."
          "callList": [] 
      }
    ]
  } 
}

false

SET
phone.call
Edit

This API allows use phone functionnility of the webportal.

Set Errors:
- 404 No connected phone: no phone device available.
- 409 Conflict: cannot complete call, another call is already in progress.
- 503 Service Unavailable: no phone device available.

Input Parameter
Param name Description Type Unit/Values Example Required
phoneNumber

Phone number of the device you want to trigger a call on, it can be retrieve throught Get or Subscribe API.

string

phone number

 		+33 (0)800 424 091 true
phoneLabel

Label of the device you want to trigger a call on.

string

n/a

 		Work false
displayName

Name of the device you want to trigger a call on.

string

n/a

 		Alice false
Output Data
Data name Description Type Unit/Values Example
callId

Telephone number on which the call was set, it can be retrieve throught Get or Subscribe API.

string

phone number

 		+33 (0)800 424 091
Code Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

webportal.set(
    /* api name */
    "phone.call",
    /* parameters */
     { 
      "phoneNumber": "+33 (0)800 424 091",
      "phoneLabel": "Work",
      "displayName": "Alice"
        }
  )
  /* callback for `REPLY` messages */
  .then((message) => {
    if (message.status === 200) {
      /* handle `REPLY` success */
    }
    else { /* handle `REPLY` error */ }
  })

1
2
3
4
5
6
7
8
9
10

{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0", 
  "type": "SET", 
  "api": "phone.call",
  "params":  { 
    "phoneNumber": "+33 (0)800 424 091",
    "phoneLabel": "Work",
    "displayName": "Alice"
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

// --- format of the `REPLY` message ---

{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0",
  "type": "REPLY",
  "api": "phone.call",
  "status": 200,
  "statusText": "OK", 
  "data": {
    "callId": "+33 (0)800 424 091" 
  } 
}

false

SUBSCRIBE
phone.call
Edit

This API allows use phone functionnility of the webportal.

This allows to listen to any call events, not only the ones triggered with SET. Event is triggered on callState change.

Input Parameter
No input params
Output Data
Data name Description Type Unit/Values Example
phoneId

Phone identifier of the device.

string

n/a

 		bt://11:22:33:44:55:66
callId

Identifier of the Call.

string

n/a

 		+33 (0) 6 01 02 03 04
callState

Current status of the call.

string

 - ringing: 'incoming call, ringtone phase'
- dialing: 'outgoing call, ringtone phase'
- active: 'phone conversation in progress'
- holding: 'call is on hold, another call is active'
- idle: 'call hung up' 		ringing
callDuration

Phone call current duration.

integer

second

 		106
Code Example 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

webportal.subscribe(
    /* api name */
    "phone.call",
    /* parameters */
     null,
    /* callback for `NOTIFY` messages */
    async (notifyMessage) => {
      if (notifyMessage.status === 200) {
        /* handle `NOTIFY` response */
      }
      else { /*  handle `NOTIFY` error  */ }
    }
  )
  /* callback for `REPLY` messages */
  .then((message) => {
    if (message.status === 200) {
      /* handle `REPLY` success */
    }
    else { /* handle `REPLY` error */ }
  })

1
2
3
4
5
6

{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0", 
  "type": "SUBSCRIBE", 
  "api": "phone.call",
  "params":  null
}

1
2
3
4
5
6
7
8
9
10
11

// --- format of the `REPLY` message ---
// type: acknowledge the status of the subscription
// reception: only once after the subscription request
// contains outputed data: no
{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0",
  "type": "REPLY",
  "status": 200,
  "statusText": "OK"
}


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// --- format of the `NOTIFY` message ---
// type: event message about the subscription
// reception: each time the conditions of the subscription are met
// contains outputed data: yes
{
  "id": "7372c16f-5f2f-42c9-84a7-5490e35f1be0",
  "type": "NOTIFY",
  "api": "phone.call",
  "status": 200,
  "statusText": "OK", 
  "data":  { 
    "phoneId": "bt://11:22:33:44:55:66",
    "callId": "+33 (0) 6 01 02 03 04",
    "callState": "ringing",
    "callDuration": "106"
  } 
}

Back to Ref List

Related References