Using Callback URLs

Callback URLs provide a convenient way to receive real-time updates on the status of your orders. Instead of polling our API to check for updates, you can register a callback URL, and we'll notify you whenever there's a change in the order's status.

Setting up Callback URLs

When placing an order for a transcript using the Order Transcript Service endpoint, include the callback parameter with a valid URL where you want to receive status updates.

Securing Callback URLs

3Play will call the exact URL you specify in your callback. To secure this, you should provide an expiring token in the URL that you can use to verify the authenticity of the request. This would look something like:

https://path.to.your.site/api/v1/3play-transcript?token=abcd-1234-efgh

The timeout for this token should be at least:

• For ASR - 1 day
• For Human Transcription - 2 weeks

You could provide a non-expiring token, which is less secure and not recommended.

Handle incoming requests

Ensure that your server is set up to handle POST requests at the specified callback URL. Our API will send status updates to this URL whenever the order changes.

Callback Payload

The payload sent to your callback URL includes (at minimum) the following info:

{
    "id": "11111111", // The transcript ID
    "media_file_id": "22222222",
    "batch_id": "33333333",
    "status": "complete",
    "cancellable": "false",
    ...and more...
}

To get a full list of the fields that come in a callback, you can hit the Send Immediate Callback endpoint. This gives you the exact payload our platform calls when there are status updates.

Retrieving Completed Transcripts

Once you receive a payload where status = complete, you can download the transcript (using the id field in the payload) by calling the Download Transcript endpoint. Check the Get Available Output Formats endpoint to see the various formats available.

By leveraging callback URLs, you can build a more efficient and responsive integration with our API, ensuring that you're always up-to-date on the status of your orders.