Versions Compared

Old Version 4

changes.mady.by.user Helen Griffith

Saved on

compared with

New Version 5

changes.mady.by.user Helen Griffith

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 The endpoint supports a number of potential "from" and "to" selectors for future use.

...

Insert excerpt
_ExcerptAPICloud
_ExcerptAPICloud
nopaneltrue

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 below provide provides all possible body parameters:

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

where

  • from.  
    • agentId. The Agents display Id as a string, in which the call wil display ID, in string format, of the agent the call will be made from. Mutually exclusive with from.Use either agentID or groups. 
    • groups. A list of Group display Id as strings, in which the call wil The display IDs of the groups that the call will be made from. Mutually exclusive with from.Use either groups or agentId. 
    • presentedCLID. The CLID to present to the party being called. This number must be confiugured configured as a callback number on in your VCC account. This The parameter is optional.
    • consent. A string indicating what the level of consent the from party requires with regards to the call being recorded. This The 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 . Both parties must consent for the call to be recorded
  • to.  
    • telephoneNumber. The telephony telephone number to call , in E164 format. Mutually exclusive with , that the call will be made to. Use either telephoneNumber or agentId. 
    • agentId. The Agents display Id as a string, in which you wish to be called. Mutually exclusive with to.telephoneNumber. display ID, in string format, of the agent the call will be made to. Use either agentId or telephoneNumber.
    • consent. A string indicating what the level of consent the from to 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 . Both parties must consent for the call to be recorded
  • regarding.  
    • reference. Where  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 application is an alphanumeric string—up string — up to 32 characters—specifying characters — specifying which application is calling the API. If integrated with Salesforce, and the feature is enabled, appName application appears in the Tasktask's subject as "Outbound appName Outbound application call to 02072068888"
Consent is used to convey information about which Consent must be supplied for both from and to or

Agent consent is implicit when they make the call, therefore consent for one party on the call is always given.  

Whether you need to provide a value for consent depends on who the call is being made from and to as described in the following table:

Tip
titleFurther details on consent
Info

How does VCC use the consent parameters?

The consent parameter provides information about how many 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:

ScenarioUsageExplanation
Agent to Telephone Number
.  Consent both to.When consent is supplied for to, it is combined with your account configuration to determine

from

to

Usage

agentId

telephoneNumber

consent must be either supplied for both or omitted from both

agentId or groups

agentId

consent must be omitted for bothWhen 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

groups

telephoneNumber

consent must be omitted for from and Your account configuration determines how to record the call.Group to Telephone NumberConsent must be omitted for from and either omitted or supplied for to.either omitted or supplied for to

The consent values provided enable call recording as described in the following table:

ScenarioOutcome

Both consent parameters are provided and are both OneParty

Two-sided call recording is enabled.

Both consent parameters are provided and one or both are TwoParty or Unknown

Agent-only call recording is enabled.

Neither of the consent parameters are provided

Your account configuration determines how to record the call.


Make call from agent 1234 to telephone number 02072068888

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "from": {
    "agentId": "1234"
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

...

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "from": {
    "agentId": "1234"
  },
  "to": {
    "agentId": "4567"
  }
}

...

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "from": {
    "groups": [
      "030"
    ]
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

...

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "from": {
    "groups": [
      "030",
      "200",
      "400"
    ]
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

...

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "from": {
    "agentId": "1234",
    "presentedCLID": "08008888888"
  },
  "to": {
    "telephoneNumber": "02072068888"
  }
}

...

Code Block
languagepowershell
themeMidnight
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

...

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

Make call from agent 1234 to telephone number 02072068888 with consent

Code Block
languagepowershell
themeMidnight
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

...

Code Block
languagejs
themeMidnight
{
  "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.

...

Code Block
languagejs
themeMidnight
{
    "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": "ExampelAppNameExampleAppName",
    "dispositionCode": null
}

...

Returns HTTP Status Code 400.

  • Ccxml not enabled - "Ccxml must be enabled for this account"Calling agent busy - ": CCXML is not enabled
  • Unable to place call - Agent number busy"Destination : Calling agent busy - "
  • Unable to place call - dialed Agent is not currently available"Unknown destination agent - ": Destination agent busy
  • Unable to place call - invalid Agent Id.": Unknown calling destination agent - "
  • Unable to place call - Agent Id is unknown"Invalid number dialed - ": Unknown calling agent
  • Unable to place call - number is invalid"Call Failed - ": 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
Code Block
languagejs
themeMidnight
{
 "message": "Ccxml must be enabled for this account"
}

...

Returns HTTP Status Code 415.

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

...