Process raw audio files

POST /v0/bulk-ingest

Trigger audio-file processing in Medallia Speech for the purpose of creating a feedback record in Experience Cloud. This endpoint is used to provide context for voice signals by sending metadata associated with the signals (audio files) in the body of the request.

Headers


Header	Description
Authorization (Required)	Requires `Bearer` and the OAuth access token (see Authentication)
Content-Type (Required)	Requires `application/json`
Accept	Requires `application/json` if used

For the request URL, always use the base URL for your Experience Cloud instance. For detailed information about identifying the host, see API hosts.

Parameters

Note: We recommend that you include the optional parameters in your API request to ensure your audio is being transcribed precisely to meet your business needs.


Parameter	Description	Data type
call_identifier (Required)	Unique identifier for the call record (must not be blank) It can be the Universal Call ID (UCID) or a similar tracked value. Example: 12345-67890-1234567890 Important: Make sure you can track this parameter, since it can later be used as an external ID for the file during import or export.	string
speech_file_name (Required)	Name of the audio file associated with the record, encoded as a JSON string S3 supports the use of forward slashes in file names to simulate folders. If your company uses this feature, you must include the full path in the Speech filename. Example: audio/2028-07-03!1000/T15996_A.wav	string
unit_identifier	ID of the agent that handled the call (typically the last agent to whom the customer was transferred, if there are multiple agents), encoded as a JSON string This must match the ID that is included in the organizational hierarchy for the agent. Note: You can supplement with additional unit fields through the transfer of custom metadata. For example, if your company is using Apps (formerly known as Best Practice Packages) that have a different unit field, you can include that field as metadata.	string
call_date_and_time (Required)	Date and time of the interaction, encoded as a JSON string containing an ISO-8601 timestamp Format — `yyyy-MM-dd HH:mm:ssZZ` (for example, `2027-01-01 11:30:00-0800`).	DateTime
engine (Required)	The speech-to-text transcription engine to use for the call, encoded as a JSON string The default value is `Engine1`. The accepted values are: Engine1 — Voci engine Engine2 — Amazon Transcribe engine	string
call_recording_url	URL of an external resource of the call interaction recording, encoded as a JSON string This is typically used to refer back to the third-party source system. Note: This URL is not used to download the call recording. It is intended as a clickable link from Medallia reporting to the source system.	string
vertical_model	Medallia Speech vertical model to use for analyzing the call contents, encoded as a JSON string The default value is `Call Center`. The accepted values are: Call Center Large Vocab	string
locale	Primary language spoken by the customer during the call, encoded as a JSON string containing ISO 639-1 values The default value is `en-US`. *The accepted ISO 639-1 values for each engine are listed below. Note: When the `engine` is `Engine1` and the `agent_locale` field has a value, then `locale` will be used for the customer channel and `agent_locale` for the agent channel. Otherwise, `locale` will be used as the media language for the entire file.	string
agent_locale	Primary language spoken by the agent during the call, encoded as a JSON string containing ISO 639-1 values The default and accepted values are the same that can be sent for `locale`. Note: This parameter is available only when the `engine` is `Engine1`.	string
lid	Restriction: This feature is inactive by default. Ask your Medallia expert to file a Feature activation request with Medallia Support. If enabled, detects the language in speech data to be transcribed The default value is `Disabled`. The accepted values are: Enabled Disabled Note: This parameter is available only when the `engine` is `Engine2`.	string
langoptions	Defines the set of languages that can be detected in speech data prior to transcription (available for Engine2 only when `lid="Enabled"`) The accepted values are the same that can be sent for `locale` when using Engine2 only. Note: This parameter is available only when the `engine` is `Engine2` and `lid` is `Enabled`.	string
apply_diarization	Determines whether diarization needs to be applied to the audio file during processing, encoded as a JSON string Diarization presumes two people are speaking and separates mono audio recordings into distinct channels by categorizing speech into two groups. This setting only applies to mono-channel recordings. The default value is `No`. The accepted values are: Yes No	string
agent_channel	Determines which of the two channels (0 or 1) is associated with the agent The other channel is associated with the customer. Note: The initiator of a call is assigned to channel 0. For inbound calls, set the agent channel to 1. For outbound calls, set the agent channel to 0. This must be mapped during Auto-Importer processing. Confirm how your telephony system records data to audio channels to properly set this value. The default value is `0`. The allowed values are: 0 1	string
substitutions	The set of transcription substitutions to make during processing, encoded as a JSON object containing key/value pairs Substitutions find and replace transcription errors with corrected values. The format is a JSON object in which the keys are the original strings to find and the values are the replacement strings. See the example below for proper formatting: `{"appeal box":"a PO box","triple A batteries":"AAA batteries"}` Important: Substitution rules are processed as part of the call made to the Speech API, and therefore cannot be applied to historical data. If you need to apply new substitution rules to data already transcribed by Speech, you must resend the associated audio file through the API.	Substitution data object
apply_redaction	Determines whether redaction is performed on the audio and its transcription, encoded as a JSON string By default, if no value is set, redaction is set to `Yes`. Restriction: Redaction is not available for the Amazon Transcribe engine. The allowed values are: Yes No Note: For security purposes, Medallia Speech automatically redacts credit card numbers, Social Security Numbers, and street addresses from the transcription and playback audio. If your company wishes to keep that information visible in Experience Cloud, set `"apply_redaction": "No"` as part of the transcription API request.	string
music	Determines whether music detection is performed on the audio and its transcription, encoded as a JSON string By default, if no value is set, music is set to `False`. The allowed values are: True False Restriction: Music detection is not available for the Amazon Transcribe engine.	boolean
first_name	First name of the customer, encoded as a JSON string Only required if a followup survey is being sent for the contact center interaction, since this would be necessary for the email invitation.	string
last_name	Last name of the customer, encoded as a JSON string Only required if a followup survey is being sent for the contact center interaction, since this would be necessary for the email invitation.	string
email	Email address of the customer, encoded as a JSON string Only required if a followup survey is being sent for the contact center interaction, since this would be necessary for the email invitation.	string
phone_number	Phone number of the customer, encoded as a JSON string This makes the customer phone number available to closed-loop feedback processes when applicable. It can be based on the detected ANI (Automatic Number Identification).	string
connection_id	Restriction: This parameter is deprecated and is no longer available. Use `connector_id` instead. Unique identifier of the connection profile This property is set automatically when you create a new connection profile.	string
connector_id	Important: When using the Speech API, if one or more Speech API type connectors are configured, this parameter is required. In this scenario, the API fails if the `connector_id` is not provided. Unique identifier of a specific Speech API connector configured in Admin Suite If set, the Medallia Speech data in the API request is routed through the connector for processing, including extra metadata available in `speech_additional_info`.	string
historical	Determines whether the speech job is run as "historical", which applies a lower priority to speech, so it is processed in between higher priority "live" jobs When `true`, Medallia Speech applies the normal configurations, such as substitutions and custom vocabulary. The allowed values are: True False	Boolean
speech_additional_info	Additional information specific to each speech vendor Use this parameter to send additional call audio metadata. See the example below for proper formatting: `{ "queue_name": "Bank", "queue_id": "12", "direction": "Inbound", "skill": "Bank", "agent_first_name": "John", "agent_last_name": "Doe" }` This option enables clients to augment the default set of call metadata. Restriction: Use of this field requires setting a `connector_id`.	Information data object

*Supported languages for locale, agent_locale, and customer_locale are listed in the following table:


Engine 1	Engine 2
en-US en-GB en-AU es-US es-ES es-MX fr-CA fr-FR de-DE it-IT pt-BR	ar-AE cs-CZ da-DK el-GR en-IN he-IL hu-HU ja-JP ko-KR nl-NL no-NO pl-PL pt-PT ro-RO sk-SK sv-SE tr-TR zh-TW zh-CN

Example requests

Request with one record

[
   {
       "call_identifier": "0696e114-b819-11ea-b3de-0242ac130004",
       "speech_file_name": "T15584.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1", 
       "call_recording_url": "https://storage.example.com/recordings/CALL-00123.mp3",
       "vertical_model": "Call Center",
       "locale": "en-US",
       "agent_locale": "en-US",
       "apply_diarization": "No",
       "agent_channel": "0",
       "substitutions": {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
       "apply_redaction": "Yes",
       "first_name": "Janelle",
       "last_name": "Perry",
       "email": "janelle.perry@mail.com",
       "phone_number": "555-555-5555",
       "connector_id": "68478g15-be61-3512-ceg2-26de2b782gg1",
       "speech_additional_info": {"queue_name":"Bank","queue_id":"12","direction":"Inbound","skill":"Bank","agent_first_name":"Gordon","agent_last_name":"Gekko"}
   }
]

Request with multiple records

[
   {
       "call_identifier": "8a98e8f7-f815-4247-90da-57ec53da6c50",
       "speech_file_name": "T15987A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1",
       "call_recording_url": "https://storage.example.com/recordings/CALL-00124.mp3",
       "apply_redaction": "Yes",
       "substitutions": {"sub1":"subA"},
       "locale": "en-US",
       "agent_locale": "en-US"
   },
   {
       "call_identifier": "0e04a5a9-bab2-4644-9aab-04e887213e50",
       "speech_file_name": "T15987C.wav",
       "unit_identifier": "svc_tech_103",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine1",
       "email": "janelle.perry@mail.com",
       "phone_number": "555-555-5555"
   },
   {
       "call_identifier": "75285c45-0675-4325-95a8-867a1575f074",
       "speech_file_name": "T15987F.wav",
       "unit_identifier": "svc_tech_103",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
       "engine": "Engine2",
       "call_recording_url": "https://storage.example.com/recordings/CALL-00125.mp3",
       "vertical_model": "Call Center",
       "apply_diarization": "No",
       "apply_redaction": "Yes",
       "email": "janelle.perry@mail.com"
   }      
]

Loaded via Auto Importer

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
   },
]

Connection ID profiles in Setup (loaded via Auto Importer)

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
     "connector_id" : "e8274f70-981c-11ed-938e-9f223223dd53",
   },
]

Payload for connectors + metadata

Metadata added to payload via speech_additional_info mapped to fields through connector data mappings:

[
   {
       "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
       "speech_file_name": "T15560A.wav",
       "unit_identifier": "wm_advisor_1",
       "call_date_and_time": "2020-06-24T13:02:00-03:00",
     "engine": "Engine2",           
     "agent_channel": "1",
    "apply_redaction": "Yes",
    "apply_diarization": "No",
    "locale": "en-US",
    "substitutions": 
     {"appeal box":"a PO box","triple A batteries":"AAA batteries"},
     "connector_id" : "e8274f70-981c-11ed-938e-9f223223dd53",
"speech_additional_info": 
{        "RECORDINGID": "62d53717-5a2e-d006-8e18-32e92cef00",
        "RECORDINGDATE": "2023-01-19T21:26:44Z",
        "LINENAME": "SMP_LEGACY_MN_1",
        "CALLID": "2003735217",
        "CALLTYPE": "External",
        "CALLDIRECTION": "Inbound",
        "STATIONID": "MN0136",
        "LOCALNAME": "Dacy Hanson",
        "ASSIGNEDWORKGROUP": 
        "STARTTIME": "2023-01-06T21:26:44Z",
        "REMOTENAME": "GEORGE TWIGG",
        "ENDTIME": "2023-01-06T21:28:59.23Z",
        "CALLDURATIONSECONDS": "180",
        "DNIS": "2172389143",
        "SKILLSET": "CS_RES_NNE_FIBER",
        "DISCOTYPE": "Remote Disconnect",
   },
]

Tip: While engine, vertical model, locales, diarization, redactions, substitutions and other values can be defined, currently, there's no merge mechanism between the Speech API payload and connector settings, so Experience Cloud will use the the values defined in the Speech API payload if present.

Status codes


Status code	Description
200 OK	Job Accepted, Partially Accepted, or All Rejected
400 Bad Request — Validation Error	Returned when a required field is missing, a restricted field is present, the feature is disabled, or a locale is not supported

Response model


Property	Description	Data type
job_id	UUID of the transcription job We recommend storing this value for troubleshooting and auditing.	string
status	The overall request status This value indicates whether or not the basic requirements were met to accept the file for processing. It does not indicate that the transcription will succeed. Note: A status of ACCEPTED or REJECTED means that all of the call entities provided in the request take on that status. A status of PARTIALLY_ACCEPTED means that there is a difference in status on particular call entities in the request, and the `details` array should be parsed for further status of each. The possible values are: ACCEPTED PARTIALLY_ACCEPTED REJECTED	string
details	An array of details related to the call entities from the request This element is only returned when a specific file or several files could not be processed (when the status is PARTIALLY_ACCEPTED). See Example responses to learn more.	File processing data object
details[].call_identifier	A unique record identifier used to associate the response in the details array with the Speech API response details	string
details[].speech_file_name	Name of the audio file on the Medallia Media File Transfer server that is associated with the record	string
details[].status	Status of the record processing (ACCEPTED or REJECTED)	string
details[].error_message	Brief description of any error that occurred	string

Example responses

200 OK — Job Accepted

{
   "job_id": "713c865e-0d1f-43a0-9998-5fada657850b",
   "status": "ACCEPTED"
}

200 OK — Partially Accepted

When one or more tasks in the batch were rejected, the details array contains per-task results.

{
   "job_id": "377533aa-d342-4a6a-8af3-724a91587bb1",
   "status": "PARTIALLY_ACCEPTED",
   "details": [
       {
           "call_identifier": "cb80e932-9a86-45c5-af83-4a0441daca3b",
           "speech_file_name": "T15560A.wav",
           "status": "ACCEPTED"
       },
       {
           "call_identifier": "1a87c03c-d148-4b70-b745-eeca94b1cc0b",
           "speech_file_name": "T15560E.wav",
           "status": "REJECTED",
           "error_message": "File T15560E.wav does not exist"
       }
   ]
}

200 OK — All Rejected

{
   "job_id": "68a49d2d-71ba-4dda-a27b-85d17039d2cc",
   "status": "REJECTED",
   "details": [
       {
           "call_identifier": "ab8c2994-9359-4269-ba4f-cd4c0d53635e",
           "speech_file_name": "T15525.wav",
           "status": "REJECTED",
           "error_message": "File T15525.wav does not exist"
       }
   ]
}

Note: The service does not validate if duplicate parameters are sent in the body of the request, or across several requests. If the same request is sent more than once, all will be accepted.

400 Bad Request — Validation Error

This specific example demonstrates a validation error due to a missing connector_id.

{
   "job_id": "7b721583-cb4f-48bb-8861-426ed0cf8719",
   "status": "REJECTED",
   "details": [
       {
           "call_identifier": ""12042024-454004002450966-record-cv20240413001",
           "speech_file_name": "Audio/454004002450966.wav",
           "status": "REJECTED",
           "error_message": "Send failed; nested exception is org.apache.kafka.common.errors.SaslAuthenticationException: {\"status\":\"invalid_token\"}"
       }
   ]
}