Making a call

The POST v0/{accountKey}/calls/ endpoint allows you 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.

In this page

Most URLs in the example code use the following values:

***. To access the API for your region, replace *** with the correct subdomain for your region:
Region URL subdomain Base URL
EMEA emea https://emea.newvoicemedia.com
USA nam https://nam.newvoicemedia.com
APAC apac https://apac.newvoicemedia.com
a1b2c3d4e5. The value represents the Vonage Contact Center account on which the API request is run. To run the API request on your account data, you must replace a1b2c3d4e5, where used, with your account's API key. For example, if your API key is mtovfiliti3, use mtovfiliti3 in place of a1b2c3d4e5.
<ACCESS_TOKEN>. The value represents a bearer access token which you must use to validate every request. Replace <ACCESS_TOKEN> where used with your bearer access token. For information about getting a bearer access token, see Getting a bearer access token.

Header Parameters

This endpoint requires the following 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`

application/json;version=6

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

Request Examples

The example below provide all possible body parameters:

{
  "from": {
    "agentId": "5464",
    "groups": [
      "030"
    ],
    "presentedCLID": "01256636451",
    "consent": "OneParty"
  },
  "to": {
    "telephoneNumber": "07970303957",
    "agentId": "4567"
  },
  "regarding": {
    "reference": "http://Test.com"
  },
  "application": "TestApp"
}

from.
- agentId. The Agents display Id as a string, in which the call wil be made from. Mutually exclusive with from.groups.
- groups. A list of Group display Id as strings, in which the call wil be made from. Mutually exclusive with from.agentId.
- presentedCLID. The CLID to present to party being called. This number must be confiugured as a callback number on your VCC account. This parameter is optional.
- consent. A string indicating what level of consent the from party requires with regards to the call being recorded. This parameter is optional. Possible values are:
  - Unknown - Consent status is unknown
  - OneParty - Only one party must consent for the call to be recorded
  - TwoParty - both partiesmust consent for the call to be recorded
to.
- telephoneNumber. The telephony number to call in E164 format. Mutually exclusive with to.agentId.
- agentId. The Agents display Id as a string, in which you wish to be called. Mutually exclusive with to.telephoneNumber.
- consent. A string indicating what level of consent the from party requires with regards to the call being recorded. This parameter is optional. Possible values are:
  - Unknown - Consent status is unknown
  - OneParty - Only one party must consent for the call to be recorded
  - TwoParty - both partiesmust consent for the call to be recorded
regarding.
- reference. 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. 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"

Further details on consent

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.

Consent must be used as follows:

Scenario	Usage	Explanation
Agent to Telephone Number	Consent must be supplied for both from and to or must be omitted for both.	When consent is supplied it is used to determine how to record the call when it is omitted your account configuration is used instead.
Agent to Agent	Consent must be omitted for both from and to.	Your account configuration determines how to record the call.
Group to Telephone Number	Consent must be omitted for from and either omitted or supplied for to.	When consent is supplied for to, it is combined with your account configuration to determine how to record the call.

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; version=6"

Body:

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

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; version=6"

Body:

{
  "from": {
    "agentId": "1234"
  },
  "to": {
    "agentId": "4567"
  }
}

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; version=6"

Body:

{
  "from": {
    "groups": [
      "030"
    ]
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

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; version=6"

Body:

{
  "from": {
    "groups": [
      "030",
      "200",
      "400"
    ]
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

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=6"

Body:

{
  "from": {
    "agentId": "1234",
    "presentedCLID": "08008888888"
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

Specifying a call reference and application

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=6"

Body:

{
  "from": {
    "agentId": "1234",
    "presentedCLID": "08008888888"
  },
  "to": {
    "telephoneNumber": "02072068888"
  },
  "regarding": {
    "reference": "0012400000ATTUQ"
  },
  "application": "appName"
}

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"

Body:

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

Response Examples

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

Example: Successful response

Returns HTTP Status Code 201.

{
    "id": "017db4a2-44b5-672e-8b9f-1a805fed07ad",
    "links": [
        {
            "href": "https://emea.newvoicemedia.com/V0/lmccg0ujju4/Calls/017db4a2-44b5-672e-8b9f-1a805fed07ad",
            "rel": "_self"
        }
    ],
    "from": {
        "presentedClid": "123456789",
        "agentId": "1234",
        "consent": "OneParty"
    },
    "to": {
        "telephoneNumber": "02072068888",
        "consent": "OneParty"
    },
    "regarding": {
        "reference": "0012400000ATTUQ"
    },
    "status": "Active",
    "recordingStatus": "Stopped",
    "application": "ExampelAppName",
    "dispositionCode": null
}

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'."
}

Region	URL subdomain	Base URL
EMEA	emea	https://emea.newvoicemedia.com
USA	nam	https://nam.newvoicemedia.com
APAC	apac	https://apac.newvoicemedia.com