Page tree

This method allows making new PhoneCalls in particular contexts such as User, Organization or global.

Request/Response model

Overview

Use this request to make phone calls between two parties.

If successful, the request returns the Id of the newly created PhoneCall as well as other useful properties.

The Id can be used later to query the status of the phone call, hang it up or update it using the available actions.

The request is made by an App that is registered to a User account.

To create phone calls, issue a HTTP POST request:

Model
HTTP-Method       = "POST"
URI-Fragment      = "/uapi/phoneCalls/" User-Id "/simple"
Query-Parameters  = multiple
Request-Payload   = PhoneCall

Return-Object     = Array<PhoneCall>
Example
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  "extension":"210",
  "phoneCallView":[
    {
       "source":["5354353", "5302040"],
       "destination":["5353535"],
       "callerId":"John Doe <4242425>"
    }
  ]
}

Request

This section describes how to format the request to the service.

URI fragment

The following parameters must be sent in the URI fragment:

NameTypeRequiredDescription

userId 

User-Id

Yes

Id of the User on behalf of whom the phone call is made.
It can take one of the following values:
@me - refers to the  authenticated User .
@viewer - also refers to the authenticated User .
@owner - refers to the User that owns the Extension used to make the phone call.
User-Id - refers to the unique identifier of the User.
Default: @me.

Query Parameters

All requests to make phone calls support the Standard-Request-Parameters and the custom fields parameter. All parameters are optional.

NameTypeRequiredDescription

waitForPickup

Number

No

The maximum number of seconds to wait until one of the phone numbers used picks up.
When the time value set here runs out, the call is cancelled.
Default: 25 seconds.

callDuration

Number

No

Total duration of the call, in seconds.
Default: global system value.

allowPublicTransferBooleanNo

This flag restricts or permits transfer of a phone call made to a phone number external to the system.
This flag is ignored for phone calls made to a local number.
Default: false

videoBooleanNoEnable video support in SDP.
Default: false

Request Payload

When making PhoneCalls, the following restrictions apply to the PhoneCall resource sent in the Request Payload.

NameTypeDescription
extensionUAPI-Extension-NumberMust refer to a Phone Terminal type Extension.
Must be owned by the User identified by the userId sent in the URI-Fragment.
Cannot be set to @self and if missing the first value of the source is used.
sourceArray<String>Can be set to a list of extension numbers or public numbers.
destinationArray<String>Can be any extension number or a public number.
callerIdUAPI-Caller-Id

The caller name and number.
It is displayed to the source.
Default: the Caller Id of the Phone Terminal Extension.

callerIdDestinationUAPI-Caller-IdThe caller name and number.
It is displayed to the destination.
Default: the Caller Id of the Phone Terminal Extension.
nonceStringA unique string which allows to identify the call created based on the request.

Short extension numbers can be given as source, extension, and destination, but only when the request is made using an App registered to an User or an Organization.

Response

Success

HTTP CodeDescription
200The Id of the phone call is returned.
204There is no Id to be returned.

Failure

When it fails, the request returns the following error codes:

HTTP CodeCodeDescription
400extension_invalidValue supplied in extension parameter is missing or invalid. The parameter must be set to the number of a Phone Terminal extension that must be owned by the user. Default has the same value as the source parameter.
400pc_duration_invalidValue supplied in callDuration parameter is missing or invalid. The parameter must be set to a numeric value and represents the mandatory duration of a phone call in seconds.
400pc_source_invalidValue supplied in source parameter is missing or invalid. The parameter must be set to a list of extended or short extension numbers or public phone numbers.
400pc_destination_invalidValue supplied in destination parameter is missing or invalid. The parameter must be set to a list of extended or short extension numbers or public phone numbers.
400pc_timeout_invalidValue supplied in waitForPickup parameter is missing or invalid. The parameter must be numeric and higher than 0.
400pc_callerid_invalidValue supplied in callerId parameter is missing or invalid. The parameter must be set to a value with the format: John Doe <+3334444>.
400pc_transfer_invalidValue supplied in allowPublicTransfer parameter is missing or invalid. The parameter must be set to true or false.
400pc_callerid_invalidYou are not allowed to set the callerid field.
400pc_nonce_invalidValue supplied in nonce parameter is missing or invalid.

Examples

Below you can find three examples that will help you understand the request and the response.

This example creates a PhoneCall between two public phone numbers. The request is made by an App on behalf of a User.

HTTP Request
POST /uapi/phoneCalls/@me/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  "extension":"210",
  "phoneCallView":[
    {
       "source":["5354353", "5302040"],
       "destination":["3235742879"],
       "callerId":"John Doe <4242425>"
    }
  ]
}

Assuming that the request has been successful, the Service sends the following answer:

HTTP Response
HTTP/1.1 202 Accepted
...
[
 {
   "id":"c3e92a04ff422a7a0b9f"
   "extension":"210"
   "link": 
      {
	   "self": "https://x.x.x.x/uapi/phoneCalls/@me/210/c3e92a04ff422a7a0b9f"
      } 
 }
]

Process Overview

STEP 1: The Service identifies the Extension given in the Request-Payload.

STEP 2: Then checks if the number corresponds to a Phone Terminal Extension.

STEP 3: The User of the Extension in question is charged for the PhoneCall.

STEP 4: The Service creates a PhoneCall resource also owned by this User.

STEP 5: The Service calls the source phone numbers given in the Request-Payload (e.g. 5354353 and 5302040). As soon as one picks up, the calls to the other phone numbers are dropped.

STEP 6: If a callerId is given in the Request Payload, it is displayed to the numbers used as the source, when they receive the call.
The callerId must suit the UAPI-Caller-Id data type. If not sent in the request, the Service uses the one set on the extension given in the Request-Payload.

STEP 7: Once the Service connects to the source, it calls the destination number given in the Request-Payload.

When the request is made using an App registered to the Administrator account or to an Organization, the userId cannot be set to @me and must be specified.

This example creates a PhoneCall between two phone numbers. The request is made by an App on behalf of a User.

HTTP Request
POST /uapi/phoneCalls/12/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
  "extension": "0003*210",
  "phoneCallView": [
    {
       "source":  [ "5354353", "5302040" ],
       "destination": [ "3235742879" ],
       "callerId": "John Doe <4242425>"
    }
  ]
}

Assuming the request has been successful, the Service returns the following answer:

HTTP Response
HTTP/1.1 202 Accepted
...
[
 {
   "id" : "c3e92a04ff422a7a0b9f"
   "extension": "0003*210"
   "link": 
      {
    	"self": "http://x.x.x.x/uapi/phoneCalls/@me/0003*210/c3e92a04ff422a7a0b9f"
      } 
 }
]

Process Overview

The same process as the one for the App registered to the User account occurs.

This example connects an extension to the system using the SandBox numbers. The request is made by an App on behalf of a User.

HTTP Request
POST /uapi/phoneCalls/12/simple HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
  "extension": "0003*210",
  "phoneCallView": [
    {
       "source":  [ "0003*210" ],
       "destination": [ "0003*00" ],
       "callerId": "John Doe <4242425>"
    }
  ]
}

Assuming the request has been successful, the Service returns the following answer:

HTTP Response
HTTP/1.1 202 Accepted
...
[
 {
   "id" : "c3e92a04ff422a7a0b9f"
   "extension": "0003*210"
   "link": 
      {
  	   "self": "http://x.x.x.x/uapi/phoneCalls/@me/0003*210/c3e92a04ff422a7a0b9f"
      } 
 }
]
#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 4.0 International.