Create ConferenceInvite PhoneCalls

This method allows inviting other parties to a conference call.

Request/Response model

Overview

Use this request to call a public or local phone number and connect it to a conference call.

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 ConferenceInvite PhoneCalls, issue a HTTP POST request:

Model

HTTP-Method       = "POST"
URI-Fragment      = "/uapi/phoneCalls/" User-Id "/conferenceInvite"
Query-Parameters  = Multiple
Request-Payload   = PhoneCall
 
Return-Object     = Array<PhoneCall>

Example

POST /uapi/phoneCalls/@me/conferenceInvite?number=3&pin=2233 HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
  "extension":"211",
  "phoneCallView":[
    {
       "source":["211"],
       "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 `Conference` 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 - unique identifier for the User. Default: @me

Query Parameters

All requests to create ConferenceInvite PhoneCalls 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.
number	Number	No	Represents the number of the scheduled conference to which the destination is invited. If not supplied, the user is asked to enter it.
pin	String	No	Represents the PIN of the scheduled conference to which the destination is invited to. If not supplied, the user is asked to enter it .

Request Payload

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

Name	Type	Description
extension	UAPI-Extension-Number	Must refer to a `Conference` 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 value of the source is used.
source	Array<String>	Must equal to the value of the extension and must reference a `Conference` extension.
destination	Array<String>	Can be any extension number or a public number.
callerId	UAPI-Caller-Id	The caller name and number. It is displayed to the destination. Default: the `callerId` of the `Conference` extension.

Response

Success

If successful, the request 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 `Conference` extension that must be owned by the user. Default has the same value as the source parameter.
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 number of seconds a phone call must last.
400	pc_source_invalid	Value supplied in source parameter is missing or invalid. The parameter must be set to the number of an existing conference extension.
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>.
400	pc_pin_invalid	Value supplied in pin parameter is missing or invalid.
400	pc_number_invalid	Value supplied in number parameter is missing or invalid.

Examples

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

This example invites the public phone number 3235742879 to a scheduled conference of extension 211. It also sends the number of the scheduled conference and the pin number, so the invited peer does not need to know them.

The request is made by an App on behalf of a User.

HTTP Request

POST /uapi/phoneCalls/@me/conferenceInvite?number=3&pin=2233 HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token
{
  "extension":"211",
  "phoneCallView":[
    {
       "source":["211"],
       "destination":["3235742879"],
       "callerId":"John Doe <3235742879>"
    }
  ]
}

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

HTTP Response

HTTP/1.1 202 Accepted
...
[
{
  "id":"99735c54ff45a3a988f2"
  "extension":"211"
  "link": 
     {
	"self": "http://x.x.x.x/uapi/phoneCalls/@me/211/99735c54ff45a3a988f2"
     } 
}
]

This example invites the public phone number 3235742879 to a scheduled conference of extension 0003*211. It does not send the number of the scheduled conference and the pin number, so the invited peer has to know and enter them when requested.