Versions Compared

Old Version 2

changes.mady.by.user Helen Griffith

Saved on

compared with

New Version 3

changes.mady.by.user Helen Griffith

Saved on

Key

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

Used 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. Insert excerpt_ExcerptRequestScheme_ExcerptRequestSchemenopaneltrue

...

Panel
borderColor#eeeeee
bgColorwhite
titleColorwhite
borderWidth1
titleBGColor#232323black
borderStylesolid
titleIn this page

Table of Contents
depth2

Request Uri

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

Request Headers

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=46

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

Request Examples

The example below provide 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"
}
  • 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.

...

Examples

...

    • 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"


Tip
titleFurther 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:

ScenarioUsageExplanation
Agent to Telephone NumberConsent 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 AgentConsent must be omitted for both from and to.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.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

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

Make call from agent 1234 to agent 4567

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

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

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

Make call from an available agent within group 030, 200 or 400 to telephone number 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"

...

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

...

Body:

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

...


    "telephoneNumber": "02072068888"

...

...

Example: Specifying a Presented CLID

...

}
}

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

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=

...

Response

Returns HTTP Status Code 201.

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

...

6"

Body:

Code Block
languagejs
themeMidnight
{
  "from": {
    "agentId": "1234",
    "presentedCLID": "08008888888"

...

...

},
  "to": {

...


    "telephoneNumber": "02072068888"

...

...

}
}

...

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.

...

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"

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

...

Body:

Code Block
languagejs
themeMidnight
{
  "from": {
    "agentId": "1234",
    "presentedCLID": "08008888888"

...

...

},
  "to": {

...


    "telephoneNumber": "02072068888"

...

...

},
  "regarding": {

...


    "reference": "0012400000ATTUQ"

...


  },

...


  "application": "appName"

...


}

...

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
 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.
Example: Successful response
Returns HTTP Status Code 201.
Location: https://***.newvoicemedia.com/v0/a1b2c3d4e5/calls/94e5928c-7f7e-4645-ad72-61010f906449
...
 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": "ExampelAppName",
    "dispositionCode": null
}


Example: Invalid request, states and call exceptions
...
  • 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
 Code Block
languagejs
themeMidnight
{
...

 "message": "Ccxml must be enabled for this account"
...

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

}