Depending on the type of Voysis AI service you are using (music, eCommerce etc.) the response to audio queries that your client makes will be slightly different. Here, we describe the common high-level elements, and have sections describing the service-specific response values.

Common Response

All responses from the different Voysis AI services have the same high-level elements:

intent

The intent element is a string indicates the type of activity that the User wants to perform. Are they searching for a product? Do they want to add the current product to their card? Are they looking for order status?
The intent element is present in all query responses, but the exact meaning of the value is service specific. See the sections below for the intent values for different services.

"intent": "newSearch"

reply

The reply element is an object that contains a text property, which is a string that represents feedback to the user. For example, if a user searched for something, the reply might contain "Here's what I found`. It can be used with text-to-speech services to provide audio feedback to the user.

"reply": {
  "text": "Here's what I found"
}

textQuery

The textQuery element is an object that contains a text property, which is a string representation of what the user actually said. For example:

"textQuery": {
  "text": "show me freshly squeezed orange juice"
}

context

The context element of a query contains information that is used by the Voysis AIs to support advanced, stateful, query processing where the results of the "current" query depend on the context established by a previous query.

The contents of context are specific to the service type of your Voysis AI. See the service-specific documentation pages for details on the precise contents your client implementation can rely on in context. The example given here simply contains a map of spoken keywords but based on the service type, this object could be much larger.

"context":{  
  "keywords":[  
    "freshly",
    "squeezed",
    "orange juice"
  ]
}

Context Handling

In order to properly support stateful queries, it is important for client implementations to properly support the context element.

In the simplest client implementation, all that needs to be done is for the client to copy the context it receives from each query and re-submit it as part of the next query sent to your Voysis AI.

More advanced implementations may modify the contents of an existing context, or create a completely new context themselves. The details of how to approach such implementations will be dependent on your specific integration with Voysis.

🚧
Failure to correctly pass the context back to the Voysis AI can result in a degraded experience for end-users.

entities

The entities element of a response contains service-specific results that can be consumed by a client implementation. See the service-specific documentation to understand what details can be present in this element.

Example Response:

{
  "id": "17cd8bcd-5d76-42ef-9451-3ff0818791d6",
  "conversationId": "e93c3a76-a8fc-4047-bb24-4eff7913c523",
  "queryType": "audio",
  "textQuery": {
    "text": "i am looking for the best red leather handbags under 200 dollars"
  },
  "audioQuery": {
    "mimeType": "audio/pcm;bits=16;rate=16000"
  },
  "context": {
    "keywords": [
      "leather",
      "handbags"
    ],
    "attributes": {
      "color": "red"
    },
    "price": {
      "type": "lessThan",
      "value": 200
    },
    "sortBy": "rating"
  },
  "intent": "newSearch",
  "reply": {
    "text": "Here's what I found"
  },
  "entities": {},
  "_links": {
    "self": {
      "href": "/queries/17cd8bcd-5d76-42ef-9451-3ff0818791d6"
    },
    "audio": {
      "href": "/queries/17cd8bcd-5d76-42ef-9451-3ff0818791d6/audio"
    }
  },
  "_embedded": {}
}