Wix Stores: Speechly Integration - Velo API Reference

Speechly Integration

Example Site
To see a live example, click here.

The Speechly Integration package provides your site visitors with the ability to filter store products using speech recognition.

You can add filters to a Wix Stores product page, such as a dropdown menu with categories or a slider to indicate maximum price. When a site visitor holds down the push-to-talk button, Speechly starts listening for voice input, and returns the input detected. A site visitor can filter store products by saying any term in the UI filters, for example, 'Find me a product under €10,' 'Yellow,' or 'Fendi'. If the returned voice input matches a term in the UI filters, the product page displays the filtered products set by the site visitor’s speech input. Note that currently you can’t use voice input to filter by size.

Note: To use this package, you must have a Wix Premium account with a connected domain.

To see an example site that demonstrates how to use the package, click here.

For any questions or assistance, email speechly directly at hello@speechly.com.

Setup

Before using the package, set up the following:

Speechly Platform

Create a Speechly account, or log in if you have an existing account.
In your dashboard, open the dropdown menu in the top right corner, and click Create new project. Note that you don’t have to create an application, it will be created automatically later on.
After creating a new project, open the dropdown menu again and go to the Project settings and create an API Token. Copy the API Token, you will need it for the next steps.

Wix Platform

Make sure you have a Wix Premium account with a connected domain.
Add a Wix Store to your site.
Open the Wix Secrets Manager, and store your Speechly API token as a new secret with the name velo-speechly-token.

Configurations

Do the following to create a connection from your site to Speechly:

Create a new .js file in your backend code. For example, init-speechly.js.

Add the following code to this file:

import {initSpeechly} from '@velo/wix-stores-speechly-backend';

export function init() {
  return initSpeechly();
}

js | Copy Code

To run this function from the Editor, click the green arrow next to the function declaration. A new tab will open in the code panel for running the function.
Click Run in the right column to run the function. When successful, the function creates an application in Speechly for you, and you can find your Speechly App ID in the function’s output. Set this ID as the speechlyAppId value in the package’s wix-stores-speechly-config.json file.

Components

Add the following components to your site:

Push-to-talk (PTT) button

The push-to-talk button is a button that listens for voice input while it is being pressed. To add the push-to-talk button:

Click Add on the left side of the Editor.
Go to Embed > Custom Embeds > Custom Element.
Add the custom element to your site, and select the element. Click Choose Source. Set the Server URL to https://speechly.github.io/browser-ui/v3/push-to-talk-button.js, and the Tag Name to push-to-talk-button. Click Update. Learn more about adding custom elements to your site here.
Then set the custom element’s ID to #pushtotalk in the Properties & Events panel.

Note that the Speechly source code for the push-to-talk button places the push-to-talk button towards the bottom of the screen to make it more accessible for mobile users.

Big Transcript

The big transcript is an overlay-style component that displays your speech-to-text transcripts in real-time (when there is active voice input). To add the big transcript component:

Click Add on the left side of the Editor.
Go to Embed > Custom Embeds > Custom Element.
Add the custom element to your site, and select the element. Click Choose Source. Set the Server URL to https://speechly.github.io/browser-ui/v3/transcript-drawer.js, and the Tag Name to transcript-drawer. Click Update.
Set the custom element’s ID to #bigTranscript in the Properties & Events panel.

Note that the Speechly source code for the big transcript component places the big transcript component as an overlay near the top-left corner of the screen.

Package Content

This package contains the following backend and public files. The main functionality for this package is located in the public files. Note that only exported functions that you can use in your site are listed here.

Backend Files

This package contains the following backend files:

speechly.js

The code in this file contains a function that creates an application in Speechly.

The file contains the following function:

initSpeechly()
Creates a Speechly app and returns the Speechly app ID.
Syntax:
```
export function initSpeechly():Promise<string>
```
js | Copy Code
Returns:
A promise that resolves to a string with either a Speechly app ID, or an error message.
Import the function to your backend code only, using the following syntax:
```
import { initSpeechly } from '@velo/wix-stores-speechly-backend';
```
js | Copy Code

wix-stores-speechly-config.json.js

The code in this editable file contains the configuration needed to use this package. Follow the instructions in the Setup section to set up the configurations.

Public Files

This package contains the following public files:

speech-to-text.js

The code in this file contains a function that enables speech recognition and speech-to-text on your site, and filters your store products using these functionalities.

The file includes the following function:

startVoice()
Initializes the speech recognition and speech-to-text functionalities when a site visitor holds down the push-to-talk button and starts talking. The event listener on the button will trigger and return an object containing the site visitor’s intent and entity (voice input detected). If any of the terms in the return object match one or more terms in the UI filters, the speech recognition can be used to filter store products. To learn more about Speechly, see the documentation here.
Syntax:
```
export async function startVoice(comp = {}): Promise<boolean>
```
js | Copy Code
Parameters:
- components: (optional) Array of component objects used to filter your store products. For example, a size dropdown menu, or a slider for a maximum price.
Note that if you choose to create your own component objects to filter your store products, call the function without the components parameter, and follow the steps in Option 1 of the How to Use the Package section.
Import the function to your page/public code using the following syntax:
```
import { startVoice } from '@velo/wix-stores-speechly';
```
js | Copy Code

set-filters.js (Optional)

The code in this file contains a function that sets the filters and handles the product repeater for your store products. It assumes you have a container with all your product filters (filter box) and a product repeater on your site. If you don’t, and you choose to create your own components to filter your store products, disregard this file and follow the steps in Option 1 of the How to Use the Package section.

The file includes the following function:

buildPage()
Displays the filtered products set by the site visitor’s voice input in the product repeater.
Syntax:
```
export async function buildPage(comp = {}): Promise<boolean>
```
js | Copy Code
Parameters:
- components: (optional) Array of component objects used to filter your store products. For example, a size dropdown menu, or a slider for a maximum price.
Import the function to your page/public code using the following syntax:
```
import { buildPage } from '@velo/wix-stores-speechly';
```
js | Copy Code

How to Use the Package

This section demonstrates how you can work with the package, and the different options for using the package functions.

There are 2 options for using this package:

Option 1: Use the list of components provided in the optional public file
For easy implementation, we created an example site containing UI elements (components) for filtering the products, plus corresponding code to set the filters and display the filtered products, as provided in the optional set-filters.js public file.
Option 2: Build and use your own components
Add your own components for filtering store products to your site. Use the package functions in the speech-to-text.js public file to build a custom product page with your filters. This option provides you with more flexibility.

Option 1: Use the components provided in the optional public file

See the example site that includes UI elements (components) for filtering the store products, and uses the corresponding list of components provided in the optional set-filters.js public file.
Click Edit Now to view and edit the example in the Editor.
In your page code, you can see that all the components in the optional set-filters.js public file are listed. Note that unlike the product repeater and load more button components, the filter components are optional, and the code works without them. You can remove any filters you don’t want to use from the components object.

Option 2: Build and use your own components

Build the components you want for filtering store products, and add them to your site.
Import the startVoice() function from the package.
Call the startVoice() function without parameters in the $w.onReady() function.

Add a component event listener inside the $w.onReady() function. Your code should look something like this:

import { startVoice } from '@velo/wix-stores-speechly';

$w.onReady(function () {

  startVoice();

  $w('#pushtotalk').on('speechsegment', (event) => {
    // filter products based on the speech event object
  })

}