/
Making a call

Making a call

Jul 29, 2024

The POST v0/{accountKey}/calls/ endpoint allows you to request a call either on behalf of a specific agent or agent group. The endpoint supports 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:
    RegionURL subdomainBase URL
    EMEAemeahttps://emea.cc.vonage.com
    USAnamhttps://nam.cc.vonage.com
    APACapachttps://apac.cc.vonage.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 following example provides all possible body parameters:

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

where

  • from  
    • agentId. The display ID, in string format, of the agent the call will be made from. Use either agentID or groups.
    • groups. The display IDs of the groups that the call will be made from. Use either groups or agentId.
    • presentedCLID. The CLID to present to the party being called. This number must be configured as a callback number in your VCC account. The parameter is optional.
  • to  
    • telephoneNumber. The telephone number, in E164 format, that the call will be made to. Use either telephoneNumber or agentId.
    • agentId. The display ID, in string format, of the agent the call will be made to. Use either agentId or telephoneNumber.
  • 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 application is an alphanumeric string — up to 32 characters — specifying which application is calling the API. If integrated with Salesforce, and the feature is enabled, application appears in the task's subject as "Outbound application call to 02072068888"

Make call from agent 1234 to telephone number 02072068888

curl -X POST "https://***.cc.vonage.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://***.cc.vonage.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://***.cc.vonage.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://***.cc.vonage.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://***.cc.vonage.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://***.cc.vonage.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"
}

Body

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

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.cc.vonage.com/V0/lmccg0ujju4/Calls/017db4a2-44b5-672e-8b9f-1a805fed07ad",
            "rel": "_self"
        }
    ],
    "from": {
        "presentedClid": "123456789",
        "agentId": "1234"
    },
    "to": {
        "telephoneNumber": "02072068888"
    },
    "regarding": {
        "reference": "0012400000ATTUQ"
    },
    "status": "Active",
    "recordingStatus": "Stopped",
    "application": "ExampleAppName",
    "dispositionCode": null
}

Example: Invalid request, states and call exceptions

Returns HTTP Status Code 400.

  • Ccxml must be enabled for this account: CCXML is not enabled
  • Unable to place call - Agent number busy: Calling agent busy
  • Unable to place call - dialed Agent is not currently available: Destination agent busy
  • Unable to place call - invalid Agent Id: Unknown destination agent
  • Unable to place call - Agent Id is unknown: Unknown calling agent
  • Unable to place call - number is invalid: Invalid number dialed
  • Unable to place call to Agent. Please try again: Call Failed
  • 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.

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