> ## Documentation Index > Fetch the complete documentation index at: https://docs.voicebase.com/llms.txt > Use this file to discover all available pages before exploring further. # Callbacks # Callbacks VoiceBase can optionally make a callback request to a specific url when media upload processing is complete. ## Uploading Media with Callbacks Enabled To request a processing-completed callback from VoiceBase, include a JSON configuration attachment with your media POST. The configuration attachment should contain the publish key, for example as below: *Notes:* * Each callback in the set below will result in a unique call to the specified server upon media completion. * If "type" is not specified: "analytics" is assumed and all sections will be included (transcript, knowledge, metadata, prediction, streams, spotting) [block:code] { "codes": [ { "code": "{\n \"publish\": {\n \"callbacks\": [\n {\n \"url\" : \"https://example.org/callback\"\n },\n {\n \"url\" : \"https://example.org/callback\",\n \"method\" : \"POST\",\n \"include\" : [ \"knowledge\", \"metadata\", \"prediction\", \"spotting\", \"streams\", \"transcript\", \"metrics\", \"speakerSentiments\", \"conversation\", \"categories\", \"messages\" ]\n },\n {\n \"url\" : \"https://example.org/callback/vtt\",\n \"method\" : \"PUT\",\n \"type\" : \"transcript\",\n \"format\" : \"webvtt\"\n },\n {\n \"url\" : \"https://example.org/callback/srt\",\n \"method\" : \"PUT\",\n \"type\" : \"transcript\",\n \"format\" : \"srt\"\n },\n {\n \"url\" : \"https://example.org/callback/media\",\n \"method\" : \"PUT\",\n \"type\" : \"media\",\n \"stream\": \"original\"\n }\n ]\n }\n }", "language": "json", "name": "Callback Configuration Sample" } ] } [/block] ## Configuration Description * `publish` : object for publish-specific configuration * `callbacks` : array of callbacks, with one object per callback desired * `[n]` : callback array element * `url` : the https url for delivering a callback notification * `method` : the HTTPS method for callback delivery, with the following supported values: * `POST`: deliver callbacks as an HTTP POST (default) * `PUT`: deliver callbacks as an HTTP PUT * `type` : Type of results to callback * `analytics`: the result analytics in json format (default) * `transcript`: the transcript in specific format, see `format` attribute * `media`: the media, see `stream` attribute * `format` : the format of the callback of type 'transcript' * `json`: transcript in json format (application/json) * `text`: transcript in text format (text/plain) * `webvtt`: transcript in webvvt format (text/vtt) * `srt`: transcript in srt format (text/srt) * `dfxp`: transcript in dfxp format (application/ttaf+xml) * `include` : array of data to include with the callback of type 'analytics', with the following supported values. If "include" is omitted the callback will return all sections: * `metadata` : include supplied metadata, often useful for correlated to records in a different system * `transcript`: include transcripts for the media on all formats. * `knowledge` : include topics and keywords for the media * `prediction` : include prediction information for the media based on supplied predictors * `spotting` : include spotted groups information for the media based on supplied keyword groups * `streams` : include links for the media * `stream` : the media stream of type 'media' * `original`: the original media * `redacted-audio`: the redacted media The following table shows the Content-Type of the requests when we call you back with the results. This header is important if you are providing pre-signed URLs generated for a service like Amazon AWS S3 [block:parameters] { "data": { "h-0": "Type", "h-1": "Format", "h-2": "Content-Type header", "0-0": "analytics", "1-0": "transcript", "2-0": "transcript", "3-0": "transcript", "4-0": "transcript", "5-0": "transcript", "6-0": "media", "0-2": "application/json", "1-2": "text/plain", "2-2": "application/json", "3-2": "text/srt", "4-2": "application/ttaf+xml", "5-2": "text/vtt", "6-2": "application/octet-stream", "0-1": "-", "1-1": "text", "2-1": "json", "3-1": "srt", "4-1": "dfxp", "5-1": "webvtt", "6-1": "-" }, "cols": 3, "rows": 7 } [/block] If the media fails to be processed, you will only receive the callbacks of type "analytics" describing the error that prevented the media from being processed. Callbacks of type "transcript" and "media" will be ignored. ## Example cURL Request with Callback For example, to upload media from a local file called recording.mp3 and receive a callback at , make the following POST request using curl, or an equivalent request using a tool of your choice: [block:code] { "codes": [ { "code": " curl https://apis.voicebase.com/v3/media \\\n --header \"Authorization: Bearer $TOKEN\" \\\n --form media=@recording.mp3 \\\n --form configuration='{\n \"publish\": {\n \"callbacks\": [\n {\n \"url\" : \"https://example.org/callback\",\n \"method\" : \"POST\",\n \"include\" : [ \"transcript\", \"knowledge\", \"metadata\", \"prediction\", \"streams\" ]\n }\n ]\n }\n }'", "language": "curl", "name": "POST Recording with Callback Config" } ] } [/block] When using callbacks, you can still query the status of the media processing using a GET request to /v3/media/{mediaId}. ## Callback Retry Logic If a success response is not achieved on the first attempt, VoiceBase will retry the callback URL provided according to the following schedule until a success response or the schedule ends. Each of these 7 scheduled attempts will include 3 attempts one immediately after each other for a maximum 21 attempts to the endpoint over 8 hours. [block:parameters] { "data": { "h-0": "Retry number", "h-1": "Time since last retry", "h-2": "Time since initial try", "0-0": "1", "1-0": "2", "2-0": "3", "3-0": "4", "4-0": "5", "5-0": "6", "6-0": "7", "0-1": "Immediate", "1-1": "15 min", "2-1": "30 min", "0-2": "0", "1-2": "15 min", "2-2": "45 min", "3-1": "1 hour", "3-2": "1 hour 45 min (105 min)", "4-1": "2 hours", "4-2": "3 hours 45 min (223 min)", "5-1": "4 hours", "5-2": "7 hours 45 min (465 min)", "6-1": "8 hours", "6-2": "15 hours 45 min (945 min)" }, "cols": 3, "rows": 7 } [/block] ## IP Whitelist All egress traffic flows from VoiceBase servers through the following (currently) NAT gateways: | IPs | VoiceBase US Instance | VoiceBase EU Instance | | --- | --------------------- | --------------------- | | 1 | 52.6.244.43 | 34.248.80.158 | | 2 | 52.6.208.178 | 52.210.18.246 | | 3 | 52.2.171.140 | 54.72.141.175 | # Callback Data When media processing is complete, VoiceBase will call back your specified endpoint by making an HTTPS POST request. The body is a JSON object with the following data: [block:code] { "codes": [ { "code": "{\n \"_links\": {},\n \"formatVersion\": \"3.0.7\",\n \"mediaId\": \"efbb8c49-87f0-4f6c-9ce9-781599918f8c\",\n \"accountId\": \"710d1652-63a4-4355-8e9a-523ddacd3066\",\n \"accountName\": \"ACME Inc\",\n \"status\": \"finished\",\n \"dateCreated\": \"2017-04-28T21:12:55.563Z\",\n \"dateFinished\": \"2018-07-19T11:34:45.134Z\",\n \"timeToLiveInSeconds\": 1200,\n \"expiresOn\": \"2018-10-04T00:41:06.145Z\",\n \"metadata\": {\n \"title\": \"Inbound call 2018-07-01 from 15081231234\",\n \"description\": \"Inbound call to 1-800-599-1234, ACME Support Center\",\n \"externalId\": \"inbound-dd9e7002-4a5a-43b3-bd46-73a66362db29\",\n \"extended\": {\n \"anything\": \"goes here\",\n \"nested\": {\n \"is\": 0,\n \"also\": 0,\n \"accepted\": 0\n }\n }\n },\n \"mediaContentType\": \"audio/mpeg\",\n \"length\": 66900, // Duration in ms of the audio\n \"knowledge\": {\n \"keywords\": [\n {\n \"keyword\": \"Microsoft\",\n \"relevance\": 0.433,\n \"mentions\": [\n {\n \"speakerName\": \"Speaker 1\",\n \"occurrences\": [\n {\n \"s\": 34234,\n \"e\": 34234,\n \"exact\": \"Microsoft\"\n }\n ]\n }\n ]\n }\n ],\n \"topics\": [\n {\n \"topicName\": \"Algorithms\",\n \"relevance\": 0.4353,\n \"subtopics\": [],\n \"keywords\": []\n }\n ]\n },\n \"spotting\": {\n \"groups\": [\n {\n \"groupName\": \"Competitors\",\n \"spotted\": false,\n \"score\": \"0.4439\",\n \"spottedKeywords\": [\n {\n \"keyword\": \"Microsoft\",\n \"relevance\": 1,\n \"mentions\": [\n {\n \"speakerName\": \"Speaker 1\",\n \"occurrences\": [\n {\n \"s\": 34234,\n \"e\": 34234,\n \"exact\": \"Microsoft\"\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n },\n \"prediction\": {\n \"classifiers\": [\n {\n \"classifierId\": \"3e8dee45-ae2a-432f-b5ff-aa2513986f23\",\n \"classifierName\": \"SaleCompleted\",\n \"classifierVersion\": \"1.0\",\n \"classifierDisplayName\": \"Sales Completed\",\n \"classifierType\": \"binary\",\n \"predictedClassLabel\": \"completed\",\n \"predictionScore\": 0.929,\n \"predictedClass\": 1\n }\n ],\n \"detectors\": [\n {\n \"detectorId\": \"99179da8-2ef4-4478-92d0-f296399a90b7\",\n \"detectorName\": \"PCI\",\n \"detectorVersion\": \"1.0\",\n \"detectorDisplayName\": \"Detects credit card data\",\n \"detectorType\": \"binary\",\n \"detections\": [\n {\n \"detectorClass\": 1,\n \"detectorClassLabel\": \"pci\",\n \"detectedSegments\": [\n {\n \"speakerName\": \"Speaker 1\",\n \"occurrences\": [\n {\n \"s\": 34322,\n \"e\": 458375\n }\n ]\n }\n ]\n }\n ]\n }\n ]\n },\n \"metrics\": [\n {\n \"metricGroupName\": \"groupX\",\n \"metricValues\": [\n {\n \"metricName\": \"xyz\",\n \"metricValue\": 200\n }\n ]\n }\n ],\n \"categories\": [\n {\n \"categoryName\": \"abc\",\n \"categoryValue\": 0\n }, {\n \"categoryName\": \"def\",\n \"categoryValue\": 1,\n \"categoryMatches\": [\n {\n \"speakerName\": \"caller\",\n \"occurrences\": [\n {\n \"s\": 24251,\n \"e\": 24981,\n \"exact\": \"hello\"\n }, {\n \"s\": 26491,\n \"e\": 30571,\n \"exact\": \"hi\"\n }\n ]\n }, {\n \"speakerName\": \"agent\",\n \"occurrences\": [\n {\n \"s\": 24251,\n \"e\": 24981,\n \"exact\": \"greetings\"\n }, {\n \"s\": 26491,\n \"e\": 30571,\n \"exact\": \"how are you\"\n }\n ]\n }\n ]\n }\n ],\n \"conversation\": {\n \"speakerVerbNounPairs\": [\n {\n \"speakerName\": \"Agent\",\n \"verbNounPairs\": [\n {\n \"s\": 6679,\n \"e\": 7260,\n \"verb\": \"call\",\n \"noun\": \"team\"\n }, {\n \"s\": 44279,\n \"e\": 45099,\n \"verb\": \"have\",\n \"verbNeg\": \"not\",\n \"noun\": \"question\"\n }, {\n \"s\": 807908,\n \"e\": 808918,\n \"verb\": \"like\",\n \"noun\": \"service\",\n \"question\": true\n }\n ]\n }, {\n \"speakerName\": \"Caller\",\n \"verbNounPairs\": [\n {\n \"s\": 16250,\n \"e\": 17340,\n \"verb\": \"need\",\n \"noun\": \"help\"\n }, {\n \"s\": 901234,\n \"e\": 902786,\n \"verb\": \"provide\",\n \"noun\": \"justification\",\n \"nounNeg\": \"no\"\n }, {\n \"s\": 1002560,\n \"e\": 1003010,\n \"verb\": \"work\",\n \"verbNeg\": \"not\",\n \"noun\": \"internet\"\n }\n ]\n }\n ]\n },\n \"speakerSentiments\": [\n {\n \"speakerName\": \"Caller\",\n \"sentimentValues\": [\n {\n \"s\": 4558,\n \"e\": 7064,\n \"v\": -0.5434\n }, {\n \"s\": 9373,\n \"e\": 10345,\n \"v\": 0.7039\n }\n ]\n }, {\n \"speakerName\": \"Agent\",\n \"sentimentValues\": [\n {\n \"s\": 7464,\n \"e\": 9373,\n \"v\": 0.4328\n }, {\n \"s\": 12937,\n \"e\": 14627,\n \"v\": -0.3294\n }\n ]\n }\n ],\n \"transcript\": {\n \"confidence\": 1.0,\n \"words\": [\n {\n \"p\": 3,\n \"c\": 0.845,\n \"s\": 13466,\n \"e\": 15648,\n \"m\": \"turn|punc\",\n \"v\": 34,\n \"w\": \"supercalifragilisticexpialidocious\",\n \"frq\": [\n {\n \"e\": 1.344,\n \"f\": 234.0\n }, {\n \"e\": 2.344,\n \"f\": 340.0\n }\n ]\n }\n ],\n \"voiceActivity\": [\n {\n \"speakerName\": \"Speaker 1\",\n \"occurrences\": [\n {\n \"s\": 13000,\n \"e\": 150547\n }, {\n \"s\": 163746,\n \"e\": 258726\n }\n ]\n }\n ],\n \"alternateFormats\": [\n {\n \"format\": \"srt\",\n \"contentType\": \"text/srt\",\n \"contentEncoding\": \"base64\",\n \"charset\": \"utf-8\",\n \"data\": \"A Base64 encoded transcript\"\n }\n ]\n },\n \"streams\": [\n {\n \"status\": \"HTTP Status of the stream. Are we using this?\",\n \"streamName\": \"original\",\n \"streamLocation\": \"https://somewhere.voicebase.com/xyzt&expires=12344\",\n }\n ],\n \"encryption\": {\n \"publishKeyId\": \"11e13265-e688-428b-b7bb-708c12a30a41\",\n \"publicKeyHash\": \"A SHA256\"\n }\n }", "language": "json", "name": "Callback JSON Sample" } ] } [/block] ## Data Description * `_links` : HAL metadata with a URL for the corresponding media item * `self` : section for the media item * `href` : URL for the media item * `media` : the requested data for the media item * `mediaId` : the unique VoiceBase id for the media item * `status` : the status of processing for the media item * `mediaContentType` : the media item content type * `length` : the media item length * `metadata` : the metadata for the media item, typically for correlation to external systems (present if requested when media is uploaded) * `transcript` : the transcript(s) for the media (present if requested when media is uploaded) * `knowledge` : the topics and keywords for the media (present if requested when media is uploaded) * `predictions` : the predictions results for the media * `streams` : links for the results of the media