Call Ingestion API

​

Requirements

The Call Ingestion feature must be enabled for your network. Your Invoca Customer Success Manager (CSM) can enable this for you. A specific “External” campaign must be created on your network. This campaign ID is what you’ll use in the API request. Call recordings must be dual-channel/stereo recordings. They must also be in a file format that we support. Invoca cannot process single-channel/mono recordings or unsupported file types. See the Supported Recording Formats section for more details. Call recordings must be accessible by Invoca. See Supported Recording Access Options for more details.

​

Endpoint

​

Request Parameters

Required external_call_unique_id The unique ID of the call from the external system. This field is required to be unique across all calls within a network that are submitted from external sources. start_time This is the date and time when the call started on the call origination platform. Please see the Timestamp Formats section below for descriptions of supported timestamps. destination_phone_number DNIS in E.164 format +country national_number; example: ‘+18885551212’. UK and Spanish numbers are also supported. Their country codes are +44 and +34 respectively. Recommended to always be set to the business’s phone number. Please see Recommendations on Phone Number Fields section below for more details. calling_phone_number ANI in E.164 format +country national_number; example: ‘+18885551212’. Recommended to always be set to the customer’s phone number. Please see Recommendations on Phone Number Fields section below for more details. advertiser_campaign_id_from_network The ID from network field on the advertiser campaign. The submitted call will be added to this campaign. Please note that this campaign must be of type ExternalOnly See Advertiser Campaigns for more details. call_direction The direction of the call flow. Accepted values: inbound or outbound. recording_url OR recording_filename. Either the URL to the call recording, or if you are using the Direct Access to S3/Azure/SFTP feature, the filepath to the recording. Please see the Supported Recording Formats and Supported Recording Access Options sections for more details. Optional language_code The IETF language tag for the call transcription. This parameter can be processed only if multiple language processing is enabled for the network or it matches the default language code of the network. The default is given from the network attribute (“default_language_code”) if it is set, otherwise “en-US”. The following language codes are supported:

recording_auth_config_id The ID from the Auth Configuration setup step. Please see the Supported Recording Access Options section for more details.

Required name The name describing the signal event. For reporting a sale happened on a call, “Sale” is recommended. Other examples include “Free Trial”, “2yr Subscription”, “Cancellation.” This can be used elsewhere in the system and should be a small list of values meaningful to your organization. Names are matched case-insensitively. Optional value True or false as to whether the signal was met or not. Defaults to true if not passed. Can be a string ‘true’ or ‘false’, or 1 (true) or 0 (false), Yes (true), or No (false). These values are not case sensitive.

Required name The Partner (API) Name of the Custom Data Field you want to apply a value to. Visit your Custom Data Management Page to view your available Custom Data Fields. value The value you would like to apply to the associated Custom Data Field for this call.

Required oauth_token API token for authentication. Can be specified in the header or body of the request (See Manage API Credentials)

​

Examples

{
  "call": {
    "external_call_unique_id": "100002",
    "start_time": "2016-02-03 09:30:00 AM",
    "destination_phone_number": 2165388265,
    "calling_phone_number": 8779257383,
    "advertiser_campaign_id_from_network": 85,
    "call_direction": "inbound",
    "recording_url": "<CALL RECORDING URL>"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

{
  "cuid": "<NEW_CUID>"
}

{
  "call": {
    "external_call_unique_id": "123ABC",
    "start_time": "2016-08-08 11:03:31 -0700",
    "destination_phone_number": 9093900003,
    "calling_phone_number": 8779257383,
    "advertiser_campaign_id_from_network": 85,
    "call_direction": "inbound",
    "recording_url": "<CALL RECORDING URL>"
  },
  "signals": [
    {
      "name": "sale",
      "value": 1
    },
    {
      "name": "quote",
      "value": 1
    }
  ],
  "custom_data": [
    {
      "name": "channel",
      "value": "Paid Search"
    },
    {
      "name": "line_of_business",
      "value": "Social"
    }
  ],
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

{
  "cuid": "<NEW_CUID>"
}

​

Response Codes

​

Timestamp Formats

Example (10 digits): 1460404800 Example (13 digits): 1460404800000

Format: YYYYMMDDHHMMSSsss Example: 20160411130000000

Format: YYYY/MM/DDTHH:MM:SS.sss+hh:mm Example (UTC offset of +3 hours): 2016/04/11T23:00:00.000+03:00 Example (UTC offset of -7 hours): 2016/04/11T13:00:00.000-07:00 Example (UTC): 2016/04/11T20:00:00.000Z Example (no milliseconds): 2016/04/11T13:00:00-07:00

Format: YYYY/MM/DD HH:MM:SS.sss AM/PM Example: 2016/04/11 13:00:00.000 PM Example (no milliseconds): 2016/04/11 13:00:00 PM

​

Recommendations on Phone Number Fields

• If a customer calls a business (inbound), the customer’s number is the calling_phone_number and the business’s number is the destination_phone_number.
• If a business calls a customer (outbound), the customer’s number is still the calling_phone_number and the business’s number is still the destination_phone_number.

​

Example POST Request Using cURL

curl --location --request POST 'https://invoca.net/api/2022-03-01/calls.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: <token>' \
--data-raw '
{
  "call": {
    "external_call_unique_id": "10002",
    "start_time": "2022-03-25 09:31:29",
    "destination_phone_number": 9093900003,
    "calling_phone_number": 8779257384,
    "advertiser_campaign_id_from_network": 86,
    "call_direction": "inbound",
    "recording_url": "<CALL RECORDING URL>"
  }
}'

curl --location --request POST 'https://invoca.net/api/2022-03-01/calls.json' \
--header 'Content-Type: application/json' \
--header 'Authorization: <token>' \
--data-raw '
{
  "call": {
    "external_call_unique_id": "10001",
    "start_time": "2022-03-25 09:31:29",
    "destination_phone_number": 9093900003,
    "calling_phone_number": 8779257384,
    "advertiser_campaign_id_from_network": 86,
    "call_direction": "inbound",
    "recording_url": "<CALL RECORDING URL>"
  }
}'

​

Errors

{
  "errors": {
    "class": "RecordInvalid",
    "invalid_data": "Validation failed: 'call' is required"
  }
}

{
  "errors": {
    "class": "UnauthorizedOperation",
    "invalid_data": "You do not have permissions to perform the requested operation."
  }
}

{
  "errors": {
    "class": "UnauthorizedAdvertiser",
    "invalid_data": "You do not have access to this advertiser"
  }
}

• Campaigns must be setup with a campaign type of ExternalOnly.
• Campaigns need to be have either the Signal AI product feature or at least one Voice Signal enabled. This will enable transcription service on the submitted call.

{
  "errors": {
    "class": "call.advertiser_campaign_id_from_network",
    "invalid_data": "campaign must be for external calls only"
  }
}

{
  "errors": {
    "class": "call.advertiser_campaign_id_from_network",
    "invalid_data": "campaign must have transcription enabled"
  }
}

​

Supported Recording Formats

• WAV
• MP3
• MP4
  • Note: MP4s should be audio-only

inbound The audio processing system will assume that the call recording matches the Invoca default with the caller channel on channel 0 and the agent channel on channel 1. outbound The audio processing system will assume that the call recording is the opposite of the Invoca dafault. The audio procesing system will normalize the call recording by swapping the channels.

​

Supported Recording Access Options

Public URL In this approach, you can provide a recording_url for the call recording that is able to be downloaded without requirement of access credentials or API keys. Requesting this URL should directly download the recording. Presigned URL If the call recording is hosted in AWS S3 you can use presigned URLs. In this approach, you can provide a recording_url with a presigned URL that grants access for a predefined period of time. The presigned URL must be live for more than 24 hours to give Invoca enough time to process the recording. Direct Recording Access to S3/Azure/SFTP In this approach, you can provide Invoca with credentials to access recordings in Amazon S3, Microsoft Azure Blob Storage, or via SFTP. Then, you can provide a recording_filename with a path to the recording. If your recording filename exactly matches the external_call_unique_id, you can omit this field entirely. Your Invoca Customer Success Manager (CSM) can assist with setting this up. Secure Recording URL If accessing your call recordings requires an API token, you can set an Auth Configuration with Invoca support. After setup, Invoca will provide you with the corresponding Auth Configuration ID. When passed as a parameter in your API request, the recording_auth_config_id will enable the Invoca Audio Processing system to access the recording. Currently, the following authentication methods are supported:

​

Call Processing Error Notifications

​

Retrying Failed Calls