# VoiceGain AI Integration via LowCodeAPI

## Overview

Speech-to-text transcription platform with real-time and batch processing capabilities

## Base Endpoint

```
https://api.lowcodeapi.com/voicegainai/
```

## Authentication

LowCodeAPI handles authentication automatically. You only need to:

1. **Sign up** at [VoiceGain AI](https://www.voicegain.ai/)
3. **Connect your account** in LowCodeAPI dashboard
4. **Use your `api_token`** in all requests

**Auth Type**: TOKEN

## API Categories

- **Recognize** - 3 endpoints
- **STT Callback** - 2 endpoints
- **Speech Analytics** - 9 endpoints
- **Tel Bot Callback** - 3 endpoints
- **Text** - 1 endpoints
- **Transcribe** - 7 endpoints

## Common Endpoints

### Category: Recognize

#### Sync Recognition

**Method**: `POST` | **LowCodeAPI Path**: `/v1/asr/recognize`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/recognize?api_token={api_token}
```

**Description**: Perform speech recognition in a single request.

**Request Body**:
```json
{
  "audio": "<object>",
  "settings": "<object>"
}
```

---

#### Async Recognition

**Method**: `GET` | **LowCodeAPI Path**: `/v1/asr/recognize/async`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/recognize/async?api_token={api_token}
```

**Description**: Start speech recognition (grammar required). Obtain results later.

---

#### Poll Recognition

**Method**: `GET` | **LowCodeAPI Path**: `/v1/asr/recognize/sessionid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/recognize/sessionid?stop={stop}&api_token={api_token}
```

**Description**: Poll speech recognition results.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`sessionId` | string | Yes | ID of the session |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`stop` | string | No | Can be used to immediately stop processing of the current session.  |

---

### Category: STT Callback

#### Recognition Callback

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customer/asr-recognize-callback`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/customer/asr-recognize-callback?api_token={api_token}
```

**Description**: Needs to be implemented by the user of the API on a URL of your choice.

**Request Body**:
```json
{
  "key": "value"
}
```

---

#### Transcription Callback

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customer/asr-transcribe-callback`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/customer/asr-transcribe-callback?api_token={api_token}
```

**Description**: Needs to be implemented by the user of the API on a URL of your choice.

**Request Body**:
```json
{
  "session": "<object>",
  "responseType": "<string>"
}
```

---

### Category: Speech Analytics

#### Query Sp. Analytics Data

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa?limit={limit}&detailed={detailed}&contextId={contextId}&fromAllContexts={fromAllContexts}&api_token={api_token}
```

**Description**: Get Speech Analytics data that matches filters.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`limit` | number | No | set the maximum number of returned results |
|`detailed` | boolean | No | If true then detailed results will be returned including per channel data. Set to false if you need the results for just the table of available results w/o detail. |
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |
|`fromAllContexts` | boolean | No | If true then results from all contexts will be retrieved |

---

#### New Speech Analytics Ses.

**Method**: `POST` | **LowCodeAPI Path**: `/v1/sa`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa?api_token={api_token}
```

**Description**: Create and launch new Speech Analytics Session. 

**Request Body**:
```json
{
  "saConfig": "<string>"
}
```

---

#### Get Sp. Analytics Data

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa/sasessionid/data`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/sasessionid/data?audio={audio}&emotion={emotion}&phrases={phrases}&summary={summary}&criteria={criteria}&decibels={decibels}&entities={entities}&keywords={keywords}&incidents={incidents}&wordCloud={wordCloud}&audioZones={audioZones}&api_token={api_token}
```

**Description**: Retrieve Speech Analytics result data.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saSessionId` | string | Yes | Session ID for Speech Analytics |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`audio` | boolean | No | If true then original or simulated (if diarization was used) multichannel (stereo) audio will be returned. |
|`emotion` | boolean | No | If true then emotion (mood and sentiment) information will be returned |
|`phrases` | boolean | No | If true then phrases spotted in the text will be returned |
|`summary` | boolean | No | If true then summary data for the transcript will be returned |
|`criteria` | boolean | No | If true then criteria satisfied in the text will be returned |
|`decibels` | number | No | If this parameter has a value then the result will contain an array of decibel values for the audio data. |
|`entities` | boolean | No | If true then named entities spotted in the text will be returned |
|`keywords` | boolean | No | If true then keywords spotted in the text will be returned |
|`incidents` | boolean | No | If true then list of incidents (silence, overtalk) identified in the call will be returned |
|`wordCloud` | boolean | No | If true then word cloud data for the transcript will be returned |
|`audioZones` | boolean | No | If true then audioZones information will be returned |

---

#### Poll Sp. Analytics Ses.

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa/sasessionid/status`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/sasessionid/status?api_token={api_token}
```

**Description**: Get status of given speech-analytics session

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saSessionId` | string | Yes | Session ID for Speech Analytics |

---

#### SA Transcript Content

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa/sasessionid/transcript`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/sasessionid/transcript?width={width}&format={format}&interval={interval}&api_token={api_token}
```

**Description**: Retrieve transcript from Speech Analytics session (after transcription is complete) in one of several possible formats.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saSessionId` | string | Yes | Session ID for Speech Analytics |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`width` | number | No | Applicable only to captions. Determines max caption width in number of characters. |
|`format` | string | No | Specifies the format of the transcript to be returned. Valid values are: |
|`interval` | number | No | Applicable only to plain text transcript. Determines interval (in seconds) between time stamps. |

---

#### Query Sp. Analytics Cfg.

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa/config`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/config?name={name}&type={type}&contextId={contextId}&inclOtherContextPublished={inclOtherContextPublished}&api_token={api_token}
```

**Description**: Create new Speech Analytics Configuration 

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`name` | string | No | Name to match. If the provided name ends with a star * then a prefix match will be performed. |
|`type` | string | No | Speech Analytics Configuration Type - user, built-in, or any (any is a union of user and built-in) |
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |
|`inclOtherContextPublished` | boolean | No | If true then will also retrieve Speech Analytics Configurations from other contexts on this account which have been published. |

---

#### Delete SA Cfg.

**Method**: `DELETE` | **LowCodeAPI Path**: `/v1/sa/config/saconfigid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/config/saconfigid?api_token={api_token}
```

**Description**: Delete Speech Analytics configuration for given id

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saConfigId` | string | Yes | Configuration ID for Speech Analytics |

---

#### Get Sp. Analytics Cfg.

**Method**: `GET` | **LowCodeAPI Path**: `/v1/sa/config/saconfigid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/config/saconfigid?api_token={api_token}
```

**Description**: Get Speech Analytics configuration for given id.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saConfigId` | string | Yes | Configuration ID for Speech Analytics |

---

#### Mod Sp. Analytics Cfg.

**Method**: `PUT` | **LowCodeAPI Path**: `/v1/sa/config/saconfigid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/sa/config/saconfigid?api_token={api_token}
```

**Description**: Modify existing Speech Analytics Configuration. 

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`saConfigId` | string | Yes | Configuration ID for Speech Analytics |

**Request Body**:
```json
{
  "key": "value"
}
```

---

### Category: Tel Bot Callback

#### New Bot Session

**Method**: `POST` | **LowCodeAPI Path**: `/v1/customer/aivr-callback`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/customer/aivr-callback?api_token={api_token}
```

**Description**: Specification of a callback method that invoked by the Voicegain Platform to indicate a start of a new Telephony Bot session to the User's dialog control logic.

**Request Body**:
```json
{
  "sid": "<string>",
  "sequence": "<number>",
  "aivrAppId": "<string>",
  "authToken": "<string>",
  "startTime": "<string>"
}
```

---

#### End Bot Session

**Method**: `DELETE` | **LowCodeAPI Path**: `/v1/customer/aivr-callback/csid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/customer/aivr-callback/csid?seq={seq}&api_token={api_token}
```

**Description**: Specification of a callback method that Voicegain Platform will use to communicate the end of a Telephony Bot Session to the User's dialog control logic.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`csid` | string | Yes | ID of the AIVR session on customer's system. |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`seq` | number | Yes | Interaction sequences of the AIVR session on Voicegain system. |

---

#### Existing Bot Session

**Method**: `PUT` | **LowCodeAPI Path**: `/v1/customer/aivr-callback/csid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/customer/aivr-callback/csid?seq={seq}&api_token={api_token}
```

**Description**: Specification of a callback method that Voicegain Platform will use to communicate events from an existing Telephony Bot session to the User's dialog control logic.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`csid` | string | Yes | ID of the AIVR session on customer's system. |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`seq` | number | Yes | Interaction sequences of the AIVR session on Voicegain system. |

**Request Body**:
```json
{
  "sid": "<string>"
}
```

---

### Category: Text

#### Redact Text

**Method**: `POST` | **LowCodeAPI Path**: `/v1/text/redact`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/text/redact?contextId={contextId}&api_token={api_token}
```

**Description**: Methods for working text text inputs.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |

**Request Body**:
```json
{
  "key": "value"
}
```

---

### Category: Transcribe

#### Poll by WS name

**Method**: `GET` | **LowCodeAPI Path**: `/v1/asr/transcribe`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe?full={full}&stop={stop}&wsName={wsName}&api_token={api_token}
```

**Description**: Poll speech transcription in async mode using the Websocket name.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`full` | boolean | No | Controls whether full or incremental results should be returned. If full=true, and the results are not final yet, no words nor transcript will be included in the result |
|`stop` | enum | No | Can be used to immediately stop processing of the current session. |
|`wsName` | string | Yes | Name of the websocket |

---

#### Sync Transcribe

**Method**: `POST` | **LowCodeAPI Path**: `/v1/asr/transcribe`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe?api_token={api_token}
```

**Description**: Synchronous Transcription API Method.

**Request Body**:
```json
{
  "audio": "<object>"
}
```

---

#### Transcribe Queue Status

**Method**: `GET` | **LowCodeAPI Path**: `/v1/asr/transcribe/status/queue`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe/status/queue?api_token={api_token}
```

**Description**: Return status of the transcription queue for this account (the account is identified by the JWT token or HMAC).

---

#### Async Transcribe

**Method**: `POST` | **LowCodeAPI Path**: `/v1/asr/transcribe/async`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe/async?contextId={contextId}&api_token={api_token}
```

**Description**: Start speech transcription in asynchronous mode. Obtain results later.

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |

**Request Body**:
```json
{
  "audio": "<object>",
  "sessions": "<array>"
}
```

---

#### Delete Transcript

**Method**: `DELETE` | **LowCodeAPI Path**: `/v1/asr/transcribe/sessionid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe/sessionid?contextId={contextId}&api_token={api_token}
```

**Description**: Delete transcript and any captured audio (if applicable).

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`sessionId` | string | Yes | ID of the session |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |

---

#### Poll Transcript

**Method**: `GET` | **LowCodeAPI Path**: `/v1/asr/transcribe/sessionid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe/sessionid?full={full}&stop={stop}&rmsInclude={rmsInclude}&api_token={api_token}
```

**Description**: Poll results of speech transcription.

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`sessionId` | string | Yes | ID of the session |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`full` | boolean | No | Controls whether full or incremental results should be returned. If full=true, and the results are not final yet, no words nor transcript will be included in the result. |
|`stop` | string | No | Can be used to immediately stop processing of the current session.  |
|`rmsInclude` | boolean | No | If true then the response will include encoded RMS data. Not returned with incremental result responses. |

---

#### Modify Transcribe Sess.

**Method**: `PUT` | **LowCodeAPI Path**: `/v1/asr/transcribe/sessionid`

**Full URL**:
```
https://api.lowcodeapi.com/voicegainai/v1/asr/transcribe/sessionid?contextId={contextId}&api_token={api_token}
```

**Description**: Modify existing Transcription session

**Path Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`sessionId` | string | Yes | ID of the session |

**Query Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
|`contextId` | string | No | Context Id. Only needed if making a request without JWT but using MAC Access Authentication instead. |

**Request Body**:
```json
{
  "metadata": "<array of objects>",
  "sessionId": "<string>"
}
```

---

## Complete Endpoint Reference

For a complete list of all 25 endpoints, refer to:
- **OpenAPI Definition**: `https://backend.lowcodeapi.com/voicegainai/definition`
- **Official Provider Documentation**: https://console.voicegain.ai/api/v1/index.html#tag/transcribe