# Asynchronous API (Webhook Notification)

This section describes the Asynchronous HTTP API for Gowajee's speech-to-text (STT) service using webhook notifications. With this API, clients send a request with a `webhookId` to the server and receive an immediate response indicating the job status. Once the STT processing is complete, the server sends the result to the specified webhook endpoint via an HTTP POST request.

### **Register Webhook Endpoint**

Before using Asynchronous API you need to register the webhook endpoint on [Gowajee Console.](https://console.gowajee.ai/dashboard/webhooks)

This ensures that Gowajee can send the transcription results to the endpoint you provide via the **HTTP POST method**.

### Workflow

1. **Send Request**: The client sends an HTTP request to the Gowajee API endpoint with the `webhookId` and `audioData`.
2. **Immediate Response**: The server responds immediately with the job status and IDs.
3. **Processing**: The server processes the audio data using the specified STT model.
4. **Webhook Notification**: Upon completion, the server sends the result to the webhook endpoint that has been sent as a `webhookId` in the request.

***

## Request

* Method: `POST`
* Endpoint: `https://api.gowajee.ai/v1/speech-to-text/${MODEL}/transcribe/async?webhookId=${YOUR_WEBHOOK_ID}`

### Supported Models

| Model  | Value  |
| ------ | ------ |
| Pulse  | pulse  |
| Cosmos | cosmos |
| Astro  | astro  |

### Headers

<table><thead><tr><th width="141">Name</th><th width="96">Type</th><th width="121">Required</th><th>Description</th></tr></thead><tbody><tr><td>x-api-key</td><td>string</td><td>Yes</td><td>An API key to access the service</td></tr></tbody></table>

### Query String <a href="#firstheading" id="firstheading"></a>

<table><thead><tr><th width="141">Name</th><th width="96">Type</th><th width="121">Required</th><th>Description</th></tr></thead><tbody><tr><td>webhookId</td><td>string</td><td>Yes</td><td>The ID of the webhook registered on the <a href="https://console.gowajee.ai/dashboard/webhooks">Gowajee Console</a></td></tr></tbody></table>

### Body Parameters

<table><thead><tr><th width="218">Name</th><th width="142">Type</th><th width="130">Required</th><th>Description</th></tr></thead><tbody><tr><td>audioData</td><td>string</td><td>Yes</td><td>Content of Audio data in base64 encoded string format or <code>multipart/form-data</code></td></tr><tr><td>getSpeakingRate</td><td>boolean</td><td>No</td><td>Get speaking rate (syllables per second)</td></tr><tr><td>getWordTimestamps</td><td>boolean</td><td>No</td><td>Get timestamps for all the words in the transcription.<br><br>Available only for the <a href="/pages/IUfJ0JS7YFdCq0GT98aw">Pulse</a> model.</td></tr><tr><td>boostWordList</td><td>string[]</td><td>No</td><td>Add specific words to increase the chance of these words appearing in results.<br><br>Available only for the <a href="/pages/IUfJ0JS7YFdCq0GT98aw">Pulse</a> and <a href="/pages/IUfJ0JS7YFdCq0GT98aw#mapping-model-with-api">Cosmos</a> models.<br><br>Read more <a href="/pages/NtrKnqwKRLjg1keTYkjE">details</a>.</td></tr><tr><td>boostScore</td><td>integer</td><td>No</td><td>The number between 1 to 20 to increase the chance of <code>boostWordList</code> appearing in results.<br><br>Available only for the <a href="/pages/IUfJ0JS7YFdCq0GT98aw">Pulse</a> and <a href="/pages/IUfJ0JS7YFdCq0GT98aw#mapping-model-with-api">Cosmos</a> models.<br><br>Read more <a href="/pages/NtrKnqwKRLjg1keTYkjE">details</a>.</td></tr><tr><td>multichannels</td><td>boolean</td><td>No</td><td>Set <code>multichannels=true</code> if your <code>audioData</code> is multichannel audio. This is useful for audio with multiple speakers with multiple channels.<br><br>Read more <a href="/pages/KuCIXAKK8i6jrLagwCmL">details</a>.</td></tr><tr><td>diarization</td><td>boolean</td><td>No</td><td>Set <code>diarization=true</code> if you want to perform speaker separation with diarization feature.<br><br>Read more <a href="/pages/zWpgr5uJC9jxFQOIvmdW">details</a>.</td></tr><tr><td>numSpeakers</td><td>integer</td><td>No</td><td>Number of speakers in your <code>audioData</code><br><br>Read more <a href="/pages/zWpgr5uJC9jxFQOIvmdW">details</a>.</td></tr><tr><td>minSpeakers</td><td>integer</td><td>No</td><td><p>Minimum number of speakers in your <code>audioData</code><br></p><p>Read more <a href="/pages/zWpgr5uJC9jxFQOIvmdW">details</a>.</p></td></tr><tr><td>maxSpeakers</td><td>integer</td><td>No</td><td>Maximum number of speakers in your <code>audioData</code><br><br>Read more <a href="/pages/zWpgr5uJC9jxFQOIvmdW">details</a>.</td></tr><tr><td>refSpeakers</td><td>RefSpeaker[]</td><td>No</td><td><p>The 4-5 seconds of speaker voice for diarization.<br></p><p>Users can upload multiple audio files, and the service will assume each file corresponds to a different speaker. If the service cannot determine which speaker corresponds to a particular transcription, it will label the speaker as 'unknown’.<br><br>Read more <a href="/pages/zWpgr5uJC9jxFQOIvmdW">details</a>.</p></td></tr><tr><td>sampleRate</td><td>integer</td><td>No<br>(Required for <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>)</td><td>The sample rate represents the number of samples of audio carried per second, measured in Hertz (Hz). It defines how many data points of audio are sampled in one second.<br><br>Read more about <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>.</td></tr><tr><td>sampleWidth</td><td>integer</td><td>No<br>(Required for <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>)</td><td>The sample width, also known as bit depth, determines the number of bits used to represent each audio sample. It directly affects the dynamic range of the audio signal (1 means 8-bit, 2 means 16-bit, etc).<br><br>Read more about <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>.</td></tr><tr><td>channels</td><td>integer</td><td>No<br>(Required for <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>)</td><td>Channels refer to the number of independent audio signals or paths in an audio file. Common values are mono (1 channel) and stereo (2 channels).<br><br>Read more about <a href="/pages/Hi3EYPRxiINBsyJDJPEJ">Raw Audio Format</a>.</td></tr></tbody></table>

## **Immediate** Response

```json
{
  "status": "IN_QUEUE",
  "jobId": "baf1c6a1-a8ad-4123-91ef-2379443f42d2",
  "webhookId": "9ed5f94e-7e30-447e-bb84-5ef194222396"
}
```

## Webhook Result

Once the STT processing is complete, the server sends the result to the webhook endpoint via an HTTP POST request.

### **Success Response**:

```json
{
  "type": "ASR_PULSE",
  "amount": 4.517,
  "output": {
    "results": [
      {
        "transcript": "มีคำถามเพิ่มเติมเกี่ยวกับความเสี่ยงในการลงทุนในกองทุนรวมนี้หรือไม่คะ",
        "startTime": 0,
        "endTime": 4.517
      }
    ],
    "duration": 4.517,
    "version": "2.2.0"
  },
  "webhookId": "9ed5f94e-7e30-447e-bb84-5ef194222396",
  "jobId": "baf1c6a1-a8ad-4123-91ef-2379443f42d2"
}

```

### **Failure Response**:

```json
{
  "status": "FAILED",
  "jobId": "baf1c6a1-a8ad-4123-91ef-2379443f42d2",
  "webhookId": "9ed5f94e-7e30-447e-bb84-5ef194222396",
  "message": "error message"
}
```

### Notes

* **webhookId**: The `webhookId` is the identifier of the webhook endpoint that the user needs to register on [Gowajee Console](https://console.gowajee.ai/dashboard/webhooks).
* **Immediate Response**: The immediate response indicates that the job is queued for processing.
* **Webhook Notification**: The webhook endpoint will receive either a successful response with the transcription results or a failure response if the STT processing fails.

By using the asynchronous API, you can handle longer audio files or higher volumes of transcription requests without having to wait for immediate processing.

***

### Webhook Security

To ensure that your webhook endpoint is being called by Gowajee, you can implement additional security measures. The simple method is to add a query parameter, such as a token, to your webhook URL and verify it on your server.

<figure><img src="/files/DysNBo3Aotchg5O95qxP" alt=""><figcaption></figcaption></figure>

***

### Receiving Transcription Results

Once your job has been completed, Gowajee will send the transcription results to the webhook endpoint via an **HTTP POST** request.

Ensure your server is set up to handle these requests and process the incoming data accordingly.

**Example:**

```javascript
const express = require('express');
const app = express();
const port = 3000;

app.use(express.json());

// Create a new item
app.post('/webhook/gowajee', (req, res) => {
  const query = req.query;
  const token = query.token;
  // TODO: Verify token
  const result = req.body;
  // TODO: Manage result
  res.status(200).send(true);
});

app.listen(port, () => {
  console.log(`Server is running on http://localhost:${port}`);
});

```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developers.gowajee.ai/speech-to-text/transcription/asynchronous-api-webhook-notification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.