API callback service

Agora provides a Notifications (NCS) service that can send 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 that event through an HTTP/HTTPS request.

Note

Best practice is that core apps do not rely on NCS. If your apps already rely heavily on NCS, contact support@agora.io and enable the redundant message notification function. This doubles the received notifications and reduces the probability of message loss. After enabling the message notification function, you need to deduplicate messages based on SID. Message notification still cannot guarantee a 100% arrival rate.

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 fields in the red rectangle are common for all callback events.
• The fields in the blue rectangle are common for all Real-Time STT events. For details, see Payload fields.
• The values of eventType, serviceType, and details depend on the event. For details, see EventType.

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 from 0. 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.

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.

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.

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.

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.

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.

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.

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.

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.

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.