Create Callback PhoneCalls

This method allows making PhoneCalls using a Callback Extension.

Request/Response model

Overview

Use this request to make a public call using a Callback Extension.

If successful, the request returns the Id of the newly created PhoneCall as well as other 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 Callback PhoneCalls, issue a HTTP POST request:

Model

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

Return-Object     = Array<PhoneCall>

Example

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

 {
  "extension":"212",
  "phoneCallView":[
    {
       "source":["3334444"],
       "destination":["3235742879"],
       "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.

Name	Type	Required	Description
userId	User-Id	Yes	Id of the User which owns the `Callback` extension that is used. 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 list phone calls support the Standard-Request-Parameters and the custom fields parameter. All parameters are optional.

Name	Type	Required	Description
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: the deployment global duration.

Request Payload

When making Callback phone calls, the following restrictions apply to the PhoneCall resource sent in the Request Payload.

Name	Type	Description
extension	UAPI-Extension-Number	Must refer to a `Callback` Extension. Must be owned by the user identified by the `userId` sent in the URI-Fragment. Cannot be set to @self and must be specified.
source	Array<String>	A public phone number.
destination	Array<String>	A public phone number.
callerId	UAPI-Caller-Id	The caller name and number. It is displayed to the source. Default: the `caller Id` of the `Callback` Extension
nonce	String	A 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 a User or an Organization.

Response

Success

The Service returns the Id of the newly created PhoneCall and the following HTTP statuses:

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

Failure

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

HTTP Code	Code	Description
400	extension_invalid	Value supplied in extension parameter is missing or invalid. The parameter must be set to the number of a `Callback` extension that must be owned by the user.
400	pc_duration_invalid	Value 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.
400	pc_source_invalid	Value 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.
400	pc_destination_invalid	Value 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.
400	pc_timeout_invalid	Value supplied in `waitForPickup` parameter is missing or invalid. The parameter must be numeric and higher than 0.
400	pc_callerid_invalid	Value supplied in `callerId` parameter is missing or invalid. The parameter must be set to a value with the format: John Doe <+3334444>.

Examples

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

This example connects two public phone numbers using the Callback Extension 212. The request is made by an App on behalf of a User.

HTTP Request

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

{
  "extension":"212",
  "phoneCallView":[
    {
       "source":["3334444"],
       "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":"212"
  "link": 
     {
	"self": "http://x.x.x.x/uapi/phoneCalls/@me/212/c3e92a04ff422a7a0b9f"
     } 
}
]

Process overview

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

STEP 2: Then checks if the Extension corresponds to a Callback Extension.

STEP 3: If the Extension is valid, the User of the Extension in question is charged for the phone call.

STEP 4: The Service creates a PhoneCall resource that is owned by the same User.

STEP 5: Then the Service connects with the source numbers given in the Request-Payload.

STEP 6: If a callerId is given in the Request-Payload, it is displayed to the phone number associated with the source.
The callerId must suit the UAPI-Caller-Id data type. If not sent in the request, the Service will use the one set on the extension given in the Request-Payload.

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

This example makes a call between two phone numbers using a Callback Extension. The request is made by an App on behalf of a User.

HTTP Request

POST /uapi/phoneCall/12/callback HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

{
  "extension":"0003*212",
  "phoneCallView":[
    {
       "source":["3334444"],
       "destination":["3235742879"],
       "callerId":"John Doe <4242425>"
    }
  ]
}

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

HTTP Response

HTTP/1.1 202 Accepted
...
[
{
  "id":"c3e92a04ff422a7a0b9f"
  "extension":"0003*212"
  "link": 
     {
	"self":"https://x.x.x.x/uapi/phoneCalls/12/003*212/c3e92a04ff422a7a0b9f"
     } 
}
]

Process overview

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

Show all results

Page tree

Request/Response model

Overview

Request

URI fragment

Query Parameters

Request Payload

Response

Success

Failure

Examples

Process overview

Process overview