Page tree

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 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.

NameTypeRequiredDescription

userId

User-IdYes

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.

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: the deployment global duration.

Request Payload

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

NameTypeDescription
extensionUAPI-Extension-NumberMust 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.
sourceArray<String>A public phone number.
destinationArray<String>A public phone number.
callerIdUAPI-Caller-Id

The caller name and number.
It is displayed to the source.
Default: the caller Id of the Callback 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 a User or an Organization.

Response

Success

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

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 Callback extension that must be owned by the user.
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>.

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.

#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.