API Reference

Here you'll find detailed documentation for each method in the Vocale class.

The Vocale class is the main interface for interacting with the Vocale service.

Constructor

Create a new instance of the Vocale class.

const vocale = new Vocale({
  siteId: "your-site-id",
  apiKey: "your-api-key", // Optional
  serviceBaseUrl: "https://vocale.ai/service" // Optional
});

Site Identifier (siteId) required:
- Serves as a unique identifier for the site or application using the Vocale.js library. Developers must provide a valid site identifier to authenticate and associate requests with their specific application instance. You can get your Site ID by registering in Vocale and setting up your site.
API Key (apiKey):
- Required for authentication with the Vocale.ai service when using the library outside of the browser.
- When you are consuming Vocale from the browser we can check that the URL consuming the service is the right URL configured for your site, but if you use it from some backend without access to the browser's host variables, you will need to use this key.
- You can get it from the setup assistant under the Javascript information after you configure your site.
Service Base URL (serviceBaseUrl):
- This setting determines the base URL of the Vocale.ai service endpoint.
- Default Value: "https://vocale.ai/service"
- Developers can modify this value if they have a custom deployment of Vocale.

Methods

In the Vocale library, we have 3 simple methods to implement the full capabilities of voice completions on your app.

Sync

vocale.sync(payload: SyncEvent): Promise<SyncResponse>

Syncronizes the forms in the app with the Vocale service. Reporting any new found form or updating any changed one.

type SyncEvent

type SyncEvent = {
  pathname: string //The pathname where this form is located. 
  // In case you are working with an app that is not using pathnames you can use any naming convention or identifier. 
  // Just keep in mind that forms that share the same pathname and same schema will be considered the same.

  forms: ReportFormSchema[]
}

type ReportFormSchema

The ReportFormSchema is a representation of a form, with it's id and the parametrization of it's fields. Keep in mind that you might not have a real HTML form, you can just create a schema of any kind of data you want to transcribe and vocale will fill it. Then you can use the reply and map it to your app's use case.

type ReportFormSchema = {
  formId: string //Here you can use the id of the form or hardcode an id for it
  type: 'HTML' | 'CUSTOM', //Tagging purposes
  schema: Field[],
  innerText?: string
}

type Field = {
  id: string;
  fieldId?: string;
  label?: string;
  type: string;
  required?: boolean;
  disabled?: boolean;
  fieldType: 'text' | 'number' | 'boolean' | 'date' | 'select'

  options: { 
    value: string,
    label:string
  }[] //This is only allowed for 'select' fieldType
}

type SyncResponse

type SyncResponse = {
 enabled?: boolean; //wheter the widget is enabled at the reported pathname or not, you can configure this on the admin page, by default will be true
 tag?: TagForm[]
}

type TagForm = {
 formId: string
 schema: {
   id: string
   fieldId: string //the internal id created by vocale or hardcorded by you when reporting the field
 }[]
}

Voice

Sends an audio to Vocale with some parameters in order to determine which form is trying to fill with the audio.

vocale.voice(audioBlob: Blob, payload: VoiceEvent): Promise<VoiceReponse>

type VoiceEvent

type VoiceEvent = {
  pathname: string //The pathname where this audio was recorded. 
  // Same as for the sync method, if you are using this outside a browser, you can use any kind of tag.

  forms: FormWithValues[]

  eventId?: string //After running the first completion you will get a eventId. 
  // You can send it over here if you want to track the "retries" in the admin dashboard

  trigger: { formId?: string } //If you want to interact directly with a specific form.
  // Here you can hardcode the formId of the reported form.
}

type FormWithValues

The FormWithValues is similar to the ReportFormShema. Its used to have the necesary context when asking Vocale to fix the spelling on a field, translating a field, or doing any kind of in-context operating with information already present that the user can currently see, and otherwise Vocale wouldn't know anything about.

type FormWithValues = {
  formId: string
  schema: FieldWithValue[],
}

type FieldWithValue = {
 id: string;
 fieldId?: string;
 value: string;
}

type VoiceResponse

type SyncResponse = {
  success?: boolean;
  error?: string;
  actions: VoiceFormCompletionAction[],
  tag?: TagForm[]
}

type VoiceFormCompletionAction = {
  eventId: string
  type: 'form'
  payload: FormOnlyValues[]
}
>
type FormOnlyValues = {
  formId: string
  schema: FieldWithValue[]
}