Making a call

Used to request a call either on behalf of a specific agent or agent group. Designed to support a number of potential "from" and "to" selectors for future use.

Request Scheme

HTTPS

Request Uri

POST v{v#}/{accountKey}/calls/

Request Headers

Authorization (required)

This header requires an OAuth bearer token. For information on the bearer token, see How to use your bearer access token.

Content-Type (required)

application/json

Indicates that the media type sent by the client is JavaScript Object Notation (JSON).

Accept (optional)

application/json;version=4

Indicates that the client will accept a JSON response and that version 4 of the API should be used.

Examples

Make call from agent 1234 to telephone number 02072068888

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "agentId": "1234" }, "to": { "telephoneNumber": "02072068888" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json"

Make call from agent 1234 to agent 4567

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "agentId": "1234" }, "to": { "agentId": "4567" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json"

Make call from an available agent within group 030 to telephone number 02072068888

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "groups": ["030"] }, "to": { "telephoneNumber": "02072068888" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json"

Make call from an available agent within group 030, 200 or 400 to telephone number 02072068888

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "groups": ["030", "200", "400"] }, "to": { "telephoneNumber": "02072068888" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json"

Successful calls return HTTP status code of 201, containing the following message and headers.

Example: Successful response

Returns HTTP Status Code 201.

Location: https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/94e5928c-7f7e-4645-ad72-61010f906449

{
 "id": "013d2063-84aa-fa90-9686-c307f5bf8beb",
 "links": [
  {
   "href": "https://***.newvoicemedia.com/V0/t0te2h4rrrp/Calls/94e5928c-7f7e-4645-ad72-61010f906449",
   "rel": "_self"
  }
 ],
 "from": {
   "telephoneNumber": "02072068888",
   "agentId": "1234"
 },
 "to": {
   "telephoneNumber": "02072068888",
   "agentId": "4567"
 }
}

Example: Specifying a Presented CLID

Presented CLID is supported from version 2 of the API. The 'Accept' header as detailed above is therefore required for the following example.

Make call from agent 1234 to telephone number 02072068888 with presented clid 08008888888

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "agentId": "1234", "presentedCLID": "08008888888" }, "to": { "telephoneNumber": "02072068888" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json; version=1.1"

Response

Returns HTTP Status Code 201.

Location: https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/94e5928c-7f7e-4645-ad72-61010f906449

{
 "id": "013d2063-84aa-fa90-9686-c307f5bf8beb",
 "links": [
  {
   "href": "https://***.newvoicemedia.com/V0/t0te2h4rrrp/Calls/94e5928c-7f7e-4645-ad72-61010f906449",
   "rel": "_self"
  }
 ],
 "from": {
   "presentedCLID": "08008888888",

   "agentId": "1234"
 },
 "to": {
   "telephoneNumber": "02072068888",
   "agentId": "4567"
 }
}

Example: Specifying a call reference and application

Specifying a call reference is supported from version 4 of the API.  The 'Accept' header as detailed above is therefore required for the following example.

Specifying an application is supported from version 5 of the API.

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "agentId": "1234", "presentedCLID": "08008888888" }, "to": { "telephoneNumber": "02072068888" },  "regarding": { "reference": "0012400000ATTUQ" }, "application": "appName" }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json;version=5"

Parameters

regarding (optional)

"regarding": { "reference": "0012400000ATTUQ" }

Where reference is an alphanumeric string or a valid URL with a maximum length of 2000 characters that contains an external ID of an object this call is regarding.

application (optional)

"application": "appName"

Where appName is an alphanumeric string—up to 32 characters—specifying which application is calling the API. If integrated with Salesforce, and the feature is enabled, appName appears in the Task's subject as "Outbound appName call to 02072068888".

Response

Returns HTTP Status Code 201.

Location: https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/94e5928c-7f7e-4645-ad72-61010f906449

{
 "id": "013d2063-84aa-fa90-9686-c307f5bf8beb",
 "links": [
  {
   "href": "https://***.newvoicemedia.com/V0/t0te2h4rrrp/Calls/94e5928c-7f7e-4645-ad72-61010f906449",
   "rel": "_self"
  }
 ],
 "from": {
   "presentedCLID": "08008888888",
   "agentId": "1234"
 },
 "to": {
   "telephoneNumber": "02072068888",
   "agentId": "4567"
 },
 "regarding": {
   "reference": "0012400000ATTUQ"
 },
 "application": "appName"
}

Example: Specifying Consent

Consent is supported from version 6 of the API. The 'Accept' header as detailed above is therefore required for the following example.

Consent is used to convey information about which parties on a call must provide consent in order for either one or both legs of the call to be recorded.

Providing a value for consent is optional but when provided it must be one of the strings: "Unknown", "OneParty", "TwoParty"

Consent must be used as follows:

Make call from agent 1234 to telephone number 02072068888 with consent

curl -X POST "https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/" -d '{ "from": { "agentId": "1234", "consent": "OneParty" }, "to": { "telephoneNumber": "02072068888", "consent": "OneParty" } }' -H "Authorization: Bearer <ACCESS_TOKEN>" -H "Content-Type: application/json;version=6"

Response

Returns HTTP Status Code 201.

Location: https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/94e5928c-7f7e-4645-ad72-61010f906449

{
 "id": "013d2063-84aa-fa90-9686-c307f5bf8beb",
 "links": [
  {
   "href": "https://***.newvoicemedia.com/V0/t0te2h4rrrp/Calls/94e5928c-7f7e-4645-ad72-61010f906449",
   "rel": "_self"
  }
 ],
 "from": {

   "agentId": "1234",
   "consent": "OneParty"
 },
 "to": {
   "telephoneNumber": "02072068888",
   "consent": "OneParty"
 }
}

Example: Invalid request, states and call exceptions

Returns HTTP Status Code 400.

• Ccxml not enabled - "Ccxml must be enabled for this account"
• Calling agent busy - "Unable to place call - Agent number busy"
• Destination agent busy - "Unable to place call - dialed Agent is not currently available"
• Unknown destination agent - "Unable to place call - invalid Agent Id."
• Unknown calling agent - "Unable to place call - Agent Id is unknown"
• Invalid number dialed - "Unable to place call - number is invalid"
• Call Failed - "Unable to place call to Agent. Please try again"
  
• Telephone number exceeds 30 characters
• Agent Id exceeds 11 digits
• Agent Id must contain digits only

• Telephone number not supported in this context

• Agent Id must be specified

• Either telephone number or agent id required
• Either telephone number or agent id required, not both
  
• Reference exceeded 2000 characters
• Reference contained invalid characters
• Application exceeded 32 characters
• Application contains non-alphanumeric characters

{
 "message": "Ccxml must be enabled for this account"
}

Example: Invalid content types

Returns HTTP Status Code 415.

• Unsupported content type - "The requested resource does not support content type 'multipart/form-data'."

{
 "message": "The requested resource does not support content type 'multipart/form-data'."
}