Call Service

Call phone number

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/

Call an user’s phone number.

Authorization rights: minimum EndUser.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "phoneNumber": "+3212345678"
}
Request JSON Object:

  • phoneNumber (string) – (Required) the called phone number (see Phone Number) or the extension (see Extension).

Example response:

HTTP/1.1 201 CREATED
Content-Type: "application/json"

{
   "callId": "callhalf-1595867:0",
   "externalTrackingId": "6d435f94-9ef8-4949-b9c3-1bccd5df1c1f"
}
Response JSON Object:

  • callId (string) – (Always returned) the call identifier.

  • externalTrackingId (string) – (Always returned) The external tracking identifier of the call.

Status Codes:

Retrieve Call List

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/

Retrieve the list of the ongoing calls.

It is also possible to retrieve the call in list with details by using the includeDetails parameter.

Authorization rights: minimum EndUser.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "calls": [
      {
         "callId": "callhalf-1595867:0",
         "inConference": false,
      }
   ]
}
Response JSON Object:

Example request with includeDetails:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "includeDetails": true
}
Request JSON Object:

  • includeDetails (boolean) –

    1. to include details of the calls.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "calls": [
      {
         "callId": "callhalf-1595867:0",
         "inConference": false,
         "externalTrackingId": "6d435f94-9ef8-4949-b9c3-1bccd5df1c1f",
         "personality": "Originator",
         "state": "Active",
         "remoteParty": {
            "address": "+3212345678",
            "callType": "Group"
         },
         "endpoint": {
            "addressOfRecord": "LP_foouser@sip.netaxis.be"
         },
         "appearance": 1,
         "startTime": "2021-10-29T11:45:14.535000",
         "answerTime": "2021-10-29T11:45:16.722000"
      }
   ]
}
Response JSON Object:

  • calls (array) – (Always returned) the list of calls. See Call Attributes.

Status Codes:

Retrieve Call Details

GET /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/(string: instance_name)/

This command is used to retrieve the details of a call.

Authorization rights: minimum EndUser.

Example request:

GET /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}
Request JSON Object:

  • action (string) – (Required) the action to be done on the call. See Phone Number.

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{
   "callId": "callhalf-1595867:0",
   "externalTrackingId": "6d435f94-9ef8-4949-b9c3-1bccd5df1c1f",
   "personality": "Originator",
   "state": "Active",
   "remoteParty": {
      "address": "+3212345678",
      "callType": "Group"
   },
   "endpoint": {
      "addressOfRecord": "LP_foouser@sip.netaxis.be"
   },
   "appearance": 1,
   "startTime": "2021-10-29T11:45:14.535000",
   "answerTime": "2021-10-29T11:45:16.722000",
   "recorded": true,
   "recordingState": "Started",
   "allowedRecordingControls": "record",
}
Response JSON Object:

  • callId (string) – (Always returned) the call identifier.

  • externalTrackingId (string) – (Always returned) The external tracking identifier of the call.

  • personality (string) – (Always returned) The personality of the call. See Call personality.

  • state (string) – (Always returned) The state of the call. See Call State.

  • remoteParty (string) – (Always returned) The remote party the call. See Remote Party.

  • endpoint (string) – (Always returned) The endpoint of the call. See Endpoint.

  • appearance (string) – (Always returned) The appearance of the call.

  • startTime (string) – (Always returned) The start time of the call.

  • answerTime (string) –

    1. The answer time of the call. Returned when a call has been correctly established.

  • recorded (boolean) –

    1. If true, the call is on recording.

  • recordingState (string) –

    1. The state of the recording. A value from list:

    • ”Pending”, Call recording has been requested but has not yet been started. This can happen when the recording request is received while a call is held.

    • ”Started”, The call is being recorded.

    • ”Paused”, Call recording was started, and is now paused.

    • ”Failed”, Call recording was started, but has failed. In this state, a new call recording cannot be started.

  • allowedRecordingControls (string) –

    1. The list of the currently allowed recording controls. A value from list:

    • ”none”

    • ”record”

    • ”pause”

    • ”pause-stop”

    • ”resume”

    • ”resume-stop”

    • ”stop”

Status Codes:

Call State Modify

PUT /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/(string: instance_name)/

This command is used to modify the state of an ongoing call of the user.

Authorization rights: minimum EndUser.

Example request: hold:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "hold"
}
Request JSON Object:

Example request: reconnect:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "reconnect"
}
Request JSON Object:

Example request: blind transfer:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "blindTransfer",
   "phoneNumber": "+3212345765"
}
Request JSON Object:

  • action (string) – (Required) the action to be done on the call. See User Call Modify Actions.

  • phoneNumber (string) – (Required) the phone number to use for the call redirection. See Phone Number.

Example request: consultative transfer:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "consultativeTransfer",
   "transferCallId": "callhalf-1595875:0"
}
Request JSON Object:

  • action (string) – (Required) the action to be done on the call. See User Call Modify Actions.

  • transferCallId (string) – (Required) the call identifier of the consulted party.

Example request: start recording:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "startRecording"
}
Request JSON Object:

Example request: pause recording:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "pauseRecording"
}
Request JSON Object:

Example request: resume recording:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "resumeRecording"
}
Request JSON Object:

Example request: stop recording:

PUT /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "action": "stopRecording"
}
Request JSON Object:

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

  • 200 OK – ok

  • 400 Bad Request –

    error with possible sub-error codes:

    • 59: INVALID_CALL_OPERATION, “The endpoint state of the call is not valid.”

    • 59: INVALID_CALL_OPERATION, “The state of the call is not valid.”

    • 59: INVALID_CALL_OPERATION, “The call is in the detached state.”

    • 59: INVALID_CALL_OPERATION, “Transfer has failed.”

    • 59: INVALID_CALL_OPERATION, “Consultative transfer already in progress,”

    • 59: INVALID_CALL_OPERATION, “User has no charge address. The User must have at least the phone number or the extension.”

    • 59: INVALID_CALL_OPERATION, “Recording is disabled for this call.”

    • 59: INVALID_CALL_OPERATION, “Recording has failed for this call.”

    • 59: INVALID_CALL_OPERATION, “User recording mode does not support stop.”

    • 59: INVALID_CALL_OPERATION, “Recording is not active.”

  • 403 Forbidden – error invalid calling user

  • 404 Not Found – error call not found

Release Call

DELETE /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/(string: instance_name)/

This command is used to release a call.

Authorization rights: minimum EndUser.

Example request:

DELETE /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/callhalf-1595867:0/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 200 OK
Content-Type: "application/json"

{}
Status Codes:

Call Retrieve

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/retrieve/

This command is used to invoke the Call Retrieve function for the specified user.

This service effectively pulls the specified call for the target user from its current location to a different location for the target user.

The target user must have a multiple appearance service active, such as BroadWorks Mobility, BroadWorks Anywhere, or Shared Call Appearance. A new call is originated as if the user dialed a feature access code.

Authorization rights: minimum EndUser.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/retrieve/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{}

Example response:

HTTP/1.1 201 CREATED
Content-Type: "application/json"

{
   "callId": "callhalf-1595867:0",
   "externalTrackingId": "6d435f94-9ef8-4949-b9c3-1bccd5df1c1f"
}
Response JSON Object:

  • callId (string) – (Always returned) the call identifier.

  • externalTrackingId (string) – (Always returned) The external tracking identifier of the call.

Status Codes:

IMRN Resource Create

POST /api/v1/tenants/(string: tenant_id)/groups/(string: group_id)/users/(string: user_id)/services/calls/imrn/

This api allows the user to create an IMRN resource to anchor a mobile call.

The response contains the available IMRN resource.

Authorization rights: minimum EndUser.

Example request:

POST /api/v1/tenants/foo/groups/foogroup/users/foouser/services/calls/imrn/ HTTP/1.1
Host: example.com
Content-Type: "application/json"

{
   "phoneNumber": "+3225126778",
   "callingPhoneNumber": "+3225126780"
}
Request JSON Object:

  • phoneNumber (string) – (Required) the called phone number (see Phone Number) or the called extension (see Extension).

  • callingPhoneNumber (string) – (Required) the calling phone number (see Phone Number) or the calling extension (see Extension).

Example response:

HTTP/1.1 201 CREATED
Content-Type: "application/json"

{
   "imrn": "+3236548297"
}
Response JSON Object:

  • imrn (string) – (Always returned) the IMRN resource.

Status Codes:

User Call Modify Actions

The available call modify actions:

  • “hold” to hold the specified call,

  • “reconnect” to retrieve the specified held call and release all other calls,

  • “blindTransfer” to transfer the specified call to the specified phone number,

  • “consultativeTransfer” to transfer the specified calls after consulting with the receiving party.

  • “startRecording” to start the call recording.

  • “pauseRecording” to pause the call recording.

  • “resumeRecording” to resume the call recording.

  • “stopRecording” to stop the call recording.

Call Attributes

Name

Type

Method

Description

GET

callId

String

A

The identifier of the call.

externalTrackingId

String

A

The external tracking identifier of the call.

personality

String

A

The personality of the call. See Call personality.

state

String

A

The state of the call. See Call State.

remoteParty

Object

A

The remote party the call. See Remote Party.

endpoint

Object

A

The endpoint of the call. See Endpoint.

appearance

Integer

A

The appearance of the call.

startTime

String

A

The start time of the call.

answerTime

String

C

The answer time of the call.

uri

String

A

Only for GET list. The URI of the call.

recorded

Boolean

A

If true, then the call is on recording.

recordingState

String

C

The state of the recording. See Call Recording State.

allowedRecordingControls

String

C

The list of the currently allowed recording controls. See Call Recording Control.

Call List Attributes

Name

Type

Method

Description

GET

callId

String

A

The identifier of the call.

inConference

String

A

The in conference status of the call.

externalTrackingId

String

C

Only list with details. The external tracking identifier of the call.

personality

String

C

Only list with details. The personality of the call. See Call personality.

state

String

C

Only list with details. The state of the call. See Call State.

remoteParty

Object

C

Only list with details. The remote party the call. See Remote Party.

endpoint

Object

C

Only list with details. The endpoint of the call. See Endpoint.

appearance

Integer

C

Only list with details. The appearance of the call.

startTime

String

C

Only list with details. The start time of the call.

answerTime

String

C

Only list with details. The answer time of the call.

Call personality

Possible values:

  • Click-to-Dial

  • Originator

Call State

Possible values:

  • Alerting/Ringing

  • Active

  • Answered

  • Released

  • Detached

  • Held

  • Remote Held

Call Recording State

Possible values:

  • Pending: Call recording has been requested but has not yet been started. This can happen when the recording request is received while a call is held.

  • Started: The call is being recorded.

  • Pause:, Call recording was started, and is now paused.

  • Failed: Call recording was started, but has failed. In this state, a new call recording cannot be started.

Call Recording Control

Possible values:

  • none

  • record

  • pause

  • pause-stop

  • resume

  • resume-stop

  • stop

Remote Party

Name

Type

Method

Description

GET

address

String

A

The address of the call.

callType

String

A

The type of the call. Group, Unknown

Endpoint

Name

Type

Method

Description

GET

addressOfRecord

String

A

The external tracking identifier of the call.