STT Callback

callback string

Pre-recorded Streaming:Nova All available languages

Deepgram’s Callback feature allows you to supply a callback URL to which transcriptions can be returned. When passed, Deepgram will immediately respond with a request_id before processing your audio asynchronously.

To enable Callback, when you call Deepgram’s API, add a callback parameter in the query string and set it to the URL to which you would like transcriptions sent:

callback=URL

To transcribe audio from a file on your computer, run the following cURL command in a terminal or your favorite API client.

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: audio/wav' \
  --data-binary @youraudio.wav \
  --url 'https://api.deepgram.com/v1/listen?callback=URL'

An example URL is https://example.com/callback.

Your callback URLs may reference the following protocols:

• For pre-recorded audio: http or https
• For streaming audio, http, https, ws, or wss:

Authentication ensures the security and integrity of callback requests. There are two main methods for authenticating callback requests: using Basic Auth and utilizing the dg-token request header.

You may embed username-password authentication credentials in the callback URL in the format https://username:[email protected]. However, it’s important to note that only ports 80, 443, 8080, and 8443 are permitted for callbacks.

Alternatively, the callback request may include a header named dg-token. When present, this header is set to the API Key Identifier associated with the API Key used to submit the original request, which lets you verify that the callback came from Deepgram.

Depending on the type of submitted audio, the response will vary.

When Deepgram has finished analyzing the audio, it will send a POST request to the provided callback URL with an appropriate HTTP status code.

If the HTTP status code of the response to the callback POST request is unsuccessful (not 200-299), Deepgram will retry the callback up to 10 times with a 30 second delay between attempts.

To enable the Callback Method, include the callback_method parameter in the query string. By default, the method supports POST, but you can specify PUT instead.

curl \
  --request POST \
  --header 'Authorization: Token YOUR_DEEPGRAM_API_KEY' \
  --header 'Content-Type: text/plain' \
  --data 'Your Text.' \
  --url 'https://api.deepgram.com/v1/listen?callback=URL&callback_method=put'

As Deepgram analyzes the audio, the way in which it sends requests back to the provided callback URL varies:

• If your callback URL begins with http:// or https://, then Deepgram will send POST requests to the callback server for each streaming response.
• If your callback URL begins with ws:// or wss://, then Deepgram will establish a WebSocket connection with the callback server and send WebSocket text messages that contain the streaming responses.