API callback service
Agora provides a Notifications service (NCS) that sends notifications about Agora Real-Time STT events. You can set up an HTTP/HTTPS server to receive such notifications. When an event occurs, the Real-Time STT service notifies the Notifications service, and then the Notifications service notifies your server of the event through an HTTP/HTTPS request.
Agora does not recommended that core applications rely heavily on Notifications. If your application currently depends heavily on NCS, contact support@agora.io to enable the redundant message notification function. This feature doubles the number of received notifications, thereby reducing the probability of message loss. However, after enabling this function, you must check the message SID to manage duplicate messages. Please note that message notifications still cannot guarantee a 100% arrival rate.
Callback information
After you enable Notifications, when a specified event occurs, the Notifications server sends an HTTP/HTTPS request as a callback. The request body provides the main information of the callback in a JSON object. The JSON object contains different fields for different events.
- The following Payload fields are common for all Real-Time STT events.
- The values of
eventType,serviceType, anddetailsdepend on the event. For details, seeEventType.
Payload fields
The payload JSON object, which is the main body of a notification, includes the following fields in each type of event notification:
cname: String. The name of the channel to be transcribed.subBotUid: String. The UID of the bot subscribing to the audio.pubBotUid: String. The UID of the bot publishing the text to the channel.taskId: String. The ID of the Real-Time STT task.sequence: Number. The serial number of the notification, starting from0. You can use this parameter to identify notifications that are random, lost, or re-sent.serviceScene: String, the current service scene.1: Real-Time STT service.
sendts: Number. The time (UTC) when the event happens. Unix timestamp in ms.serviceType: Number. The type of Agora service.0: The Real-Time STT service.1: The STT module.2: The uploader module.
details: JSON. The details of the callback events provided in the tables below. The Notifications service may add new fields in the future. To ensure backward compatibility, the service will not change the data format of the existing fields.
Callback events
| eventType | serviceType | Event description |
|---|---|---|
4 | 0 (Real-Time STT service) | The M3U8 playlist file is generated for .vtt files. |
30 | 2 (uploader module) | The upload service starts. |
31 | 2 (uploader module) | All the .vtt files are uploaded to the specified third-party cloud storage. |
32 | 2 (uploader module) | All the .vtt files are uploaded, but at least one file is uploaded to Agora Cloud Backup. |
33 | 2 (uploader module) | The progress of uploading the .vtt files to the cloud storage. |
4 cloud_recording_file_infos
eventType 4 indicates that an M3U8 playlist file was generated and uploaded. During a recording, the recording service repeatedly uploads and overwrites the M3U8 file, but this event is triggered the first time the M3U8 file is generated and uploaded.
details includes the following fields:
msgName: String. The message name,cloud_recording_file_infos.fileList: String. The name of the M3U8 file.
Example
30 uploader_started
eventType 30 indicates that the upload service has started. details includes the following fields:
msgName: String. The message name, uploader_started.status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.
Example
31 uploaded
eventType 31 indicates that all the recorded files are uploaded to the specified third-party cloud storage. details includes the following fields:
msgName: String. The message name, uploaded.status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.fileList: JSONArray. An array that contains detailed information of each recorded file.fileName: String. The name of the M3U8 file or MP4 file.trackType: String. The type of the recorded file."audio": Audio file."video": Video file (no audio)."text": Caption/transcription file.
mode: Number.1: Service for channel,2: Service for a specific UID.
sliceStartTime: Number. The Unix time (ms) when the recording starts.
Example
32 backuped
eventType 32 indicates that all the .vtt files are uploaded, but at least one of them is uploaded to Agora Cloud Backup. Agora Cloud Backup automatically uploads the files to the specified third-party cloud storage. details includes the following fields:
- `msgName: String. The message name, backuped.
- `status: Number. The event status. 0 indicates normal status; other values indicate abnormal status.
- `fileList: JSONArray. An array that contains detailed information of each recorded file.
- `fileName: String. The name of the M3U8 file or MP4 file.
- `trackType: String. The type of the recorded file.
"audio": Audio file."video": Video file (no audio)."text": Caption/Transcription file.
- `mode: Number.
1: Service for channel,2: Service for specific uid.
- `sliceStartTime: Number. The Unix time (ms) when the recording starts.
Example
33 uploading_progress
eventType 33 indicates the current upload progress. It notifies you of the .vtt files upload progress once every minute after the Real-Time STT service starts. details includes the following fields:
msgName: String. The message name,uploading_progress.progress: Number. An ever-increasing number between 0 and 10,000, equal to the ratio of the number of the uploaded files to the number of the recorded files multiplied by 10,000. After the recording service exits and when the number reaches 10,000, the upload completes.
Example
Reference
This section contains content that completes the information on this page, or points you to documentation that explains other aspects to this product.
What are the differences between the Notifications service and the query method?
You can monitor the status of the Real-Time STT service either through the query method or by the Notifications service, to take action when required. Both options have pros and cons.
The query method
You can periodically call the query method to monitor the status of Real-Time STT.
- Pros: Reliable, as the status is queried proactively.
- Cons:
- Provides limited status information.
- Requires an active query. You cannot query too often because of the Queries Per Second (QPS) limit, and thus it is not as real-time as the Notifications service.
If the status reliability of Real-Time STT is a high priority, Agora strongly recommends using the query method.
Notifications service
You can use the Notifications service as a complementary option to monitor the service status. You need to configure an HTTP/HTTPS server to receive event notifications.
- Pros: Real-time
- Cons:
- The server passively receives messages, and the messages may get lost.
- The confirmation message of the message delivery may get lost, causing the message to be re-sent. In such a case, you need to deduplicate the notifications.
- The messages may not arrive in the correct order.