Page tree
Skip to end of metadata
Go to start of metadata
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.

NameTypeRequiredDescription

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.

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.

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.

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

sourceArray<String>Must equal to the value of the extension and must reference a Conference extension.
destinationArray<String>Can be any extension number or a public number.
callerIdUAPI-Caller-IdThe 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 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 Conference 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 number of seconds a phone call must last.
400pc_source_invalidValue supplied in source parameter is missing or invalid. The parameter must be set to the number of an existing conference extension.
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_pin_invalidValue supplied in pin parameter is missing or invalid.
400pc_number_invalidValue 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.

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

HTTP Request
GET /uapi/phoneCalls/12/0003*210/b817d2618fe6f1804db1 HTTP/1.1
HOST uapi.voipnow.com
Content Type: application/json
Authorization: Bearer token

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

HTTP Response
HTTP/1.1 200 OK
...
 
{"entry":
[{"id":"b817d2618fe6f1804db1",
  "extension":"0003*210",
  "ownerId":"3",
  "ownerName":"Default Organization", 
  "answered":"2012-06-27T16:08:55+03:00",
  "published":"2012-06-27T16:08:50+02:00",
  "phoneCallView":[
    {
       "id":"00",
       "extension":"0003*210",
       "answered":"2012-06-27T16:08:55+03:00",
       "status":"5", 
       "callerId":"John Doe <3235742879>",
       "source":["0003*210"],
       "destination":["3235742879"]
     }
	"links":{...}
]
}],
"startIndex":0,
"totalResults":1,
"itemsPerPage":20,
"filtered":false,
"sorted":false
"paging":{...}
}
  • No labels

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