Node SDK

Getting started

Flow is our Conversational AI API that allows you to add responsive, real-time speech-to-speech interactions to any product.

Flow is engineered to engage in natural and fluid conversations by automatically handling interruptions, responding to multiple speakers, and understanding different dialects and accents.

This page will show you how to use the Flow Conversational API for the most natural and intuitive conversational AI using an easy to use interactive code editor.

Set Up

1. Create an account on the Speechmatics On-Demand Portal here.
2. Navigate to Manage > API Keys page in the Speechmatics On-Demand Portal.
3. Enter a name for your API key and store your API key somewhere safe.

Code example

The Speechmatics Flow client can be found on GitHub along with a React client.

The Flow client can be installed using NPM:

npm i @speechmatics/flow-client

tip

This library can be used in the browser and backend runtimes like NodeJS and Bun! Check out our examples on Github.

Below is an example of how to use the Flow client SDK. For a more complete example, check out our NextJS sample app.

import { FlowClient, AgentAudioEvent } from "@speechmatics/flow-client";
const flowClient = new FlowClient('wss://flow.api.speechmatics.com', { appId: "example" });


async function fetchCredentials() {
  const resp = await fetch(
    'https://mp.speechmatics.com/v1/api_keys?type=flow',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${process.env.API_KEY}`,
      },
      body: JSON.stringify({
        ttl: 3600,
      }),
    },
  );
  if (!resp.ok) {
    throw new Error('Bad response from API', { cause: resp });
  }
  return await resp.json();
}

flowClient.addEventListener("agentAudio", (audio) => {
  // audio.data is PCM16_SLE data. How you play this depends on your environment
  myAudioPlayFunction(audio.data)
});

// Fetch a JWT for authentication, and start a conversation :

const jwt = await fetchCredentials(YOUR_API_KEY);

await flowClient.startConversation(jwt, {
  config: {
    template_id: "flow-service-assistant-amelia",
    template_variables: {},
  },
  // Optional, this is the default
  audioFormat: {
    type: 'raw',
    encoding: 'pcm_s16le',
    sample_rate: 16000,
  },
});

// PCM audio can be sent to the client (either f32 or int16 depending on the audio_format defined above)
function onPCMAudio(audio: Int16Array) {
  flowClient.sendAudio(audio);
}

function onSessionEnd() {
  // Ends conversation and closes websocket
  flowClient.endConversation();

  // Event listeners can also be removed like so
  flowClient.removeEventListener("agentAudio", onAgentAudio);
}