MeetKai provides two types of APIs, our conversational API “Oscar” and our search API “Grouch”
Oscar is the backend to support conversational experiences. It is stateful, allowing for our multi turn functionality. Every session with Oscar begins with initializing a dialogue, each “user” can have only a single ongoing dialogue at a time. The firstsent to Oscar is what triggers the creation of a new stateful dialogue
Ashould be sent as a result of the user submitting either text or speech. Messages take in a set of speech recognition results, each with a possible transcription and the associated confidence. If the input is based on a keyword input, it should be marked as a single recognition result with confidence of 1.0.
Oscar responds with a stream of messages, please refer to the OpenAPI documentation for the specifics of each response type, however there are a few key concepts to keep in mind.
Responses from Oscar are intended to be displayed to the user as they are received in a streaming fashion.
Audio messages are meant to be buffered and played one after the other, this allows for two separate audio responses to be sent and played without requiring loading all at once
The connection will be closed when Oscar is finished with sending responses
There are 3 different ways that one can send messages to Oscar.
A web socket connection can be opened for each “turn”, the user should start by sending a single . Oscar will emit Responses and close the web socket when no more responses are expected (the turn is complete).
Not all client libraries support headers with web sockets, for this reason it is not recommended to be used unless there are special considerations for why a websocket is preferable for the application runtime.
Compression is manually carried out, please see Postman for the headers that should be specified to select between gzip and zlib.
This is the preferred method of interaction with Oscar. You begin by sending a POST message to the endpoint as prescribed in the API. In response you will get new line delimited messages. The connection will close when there are no more messages to send back
For clients that cannot support Websocket or Streaming HTTP, we also provide a batched endpoint. A single message is sent as a POST request and the response will come back as a JSON body with as an array of responses. Please refer to the batch API for details.
Grouch is the backend service that supports conversational search, instead of providing a conversational experience it is much more akin to a conventional search engine. Grouch itself is used to power all of the MeetKai Quick Apps and card abilities. There are comprehensive examples and documentation on how to use grouch, but for now this section will provide a few key points to consider.
Grouch itself can handle searching across a single or multiple domains. In the single domain scenario, the client must specify the domain to search for and results will be guaranteed to come from that domain.
In the multi domain scenario, all of the grouch supported domains are queried to surface results. Results are grouped together by domain and an associated ranking is supplied on a domain-by-domain level. External API usage currently does not support mixed ranking, it is up to the client to either co-mingle or display separately results for each domain.
Grouch supports the full conversational NLU that can be handled by Oscar in a conversational context, some example queries that grouch can handle:
Tom cruise movies no action
Shirt without stripes
Black shirt not for men
Pagination in grouch is possible but does not use a conventional offset method. Instead you perform a new query but pass in as part of the request body the IDs to exclude from the previous result. Due to potential race conditions, clients are still advised to filter out duplicate item ids before displaying the next page of results.
Personalization for all experiences happens through Grouch. Currently external API users may provide 4 types of interactions. The API documentation contains full information on this.
Like: A like interaction is an explicit positive interaction, example frontend usages of this would be a thumbs up button or a positive rating
Dislike: A dislike interaction is an explicit negative interaction, it is the opposite of a Like
Seen: A seen interaction is intended to provide an implicit interaction that a user has viewed a result. It is primarily used to enhance novelty and subtle personalization.
Click: A click interaction is a catch all for a positive interaction that implies a conversion, this might be clicking the watch now button in streaming or the order delivery button in restaurants. It is the most positive interaction a user can have with an item
Headers and Authorization
All requests to the MK API are expected to contain certain headers. There are two types of headers. Required headers, when missing, will cause the request to fail. Optional headers, when missing, will still allow a result to be returned but may be substantially degraded. In general the more headers provided the better the result quality. Please refer to the API documentation for full information.