Full-text search in REST API

You can use a full-text search to find dialogs containing a specified word or phrase. The query returns IDs of matching dialogs. For details on how to get information about a dialog by its ID, see this guide.

To refine your search results, you can use filtering by parameters along with full-text search. In this case, the response will return only query IDs that satisfy both the full-text search criteria and additional filters.

Getting startedGetting started

To search data via the Yandex Cloud REST API:

1. In the management console, create a service account.

2. Add the service account to the namespace with the Data viewer role. This will allow your service account to work with data in SpeechSense.

3. To authenticate to the Yandex Cloud API, create an API key or IAM token for the service account.

4. Upload voice call recordings or chat transcripts to SpeechSense.

Full-text searchFull-text search

1. Create a file named search.json and specify in it the required IDs and parameters for full-text search:

   {
     "organizationId": "<organization_ID>",
     "spaceId": "<space_ID>",
     "connectionId": "<connection_ID>",
     "projectId": "<project_ID>",
     "query": {
       "text": "<search_query>",
       "channelNumber": "<channel_number>"
     },
     "sort_data": {
       "fields": [{
         "field": "<dialog_feature_you_are_searching_by>",
         "order": "<sort_order:_ascending_or_descending>",
         "position": "<sort_field_priority>"
       }]
     },
     "pageSize": "<number_of_documents_per_page>",
     "pageToken": "<next_page_token_with_search_results>"
   }
   

   Where:

   • organizationId: ID of the organization the request takes place in. To get the ID, go to Cloud Center and click under the name of the organization in the section.
   • spaceId: ID of the space the request takes place in. To get the ID, go to SpeechSense, open the page of the space you need and click ID.
   • connectionId: ID of the connection the request takes place in. To get the ID, go to SpeechSense, open the page of the space you need. On the Connection tab, open the page of the connection and click ID.
   • projectId: ID of the project the request takes place in. To get an ID, go to SpeechSense, open the page of the space you need. On the Projects tab, open the page of the project and click ID.

   • query: Full-text search request body. Supports the following parameters:

     • text: Search query text. You can specify a word or phrase. SpeechSense will search for the specified string in the audio text transcript or chat text.

     • channelNumber: Channel number. If you specify this parameter, the search is performed only in the audio text transcript or chat text for the specified channel.

       Channel numbering in chat connections:

       • 0: Agent channel.
       • 1: Customer channel.
       • 2: Bot channel.

       Channel numbering for audio is preset at the connection level and is different from channel numbering for chats.

   • sort_data: Data sorting parameters in response to the request.

     • fields: List of dialog features you are sorting by. Supports the following parameters:
       • field: Dialog feature you are sorting by.
       • order: Sort order: ascending or descending.
       • position: Sorting field priority (when sorting by several dialog features at the same time).

   • pageSize: Number of documents per page.

   • pageToken: Token of the next page with search query results. 
     If the query results are split into multiple pages, each page has a token of its own. The response to each search query contains the next_page_token (if there is a next page). Paste it into the pageToken parameter of your search query to get the next page of search results.

   For more information about search query parameters, see the API reference.

2. Specify the service account's API key:

   export API_KEY=<service_account_API_key>
   

   If using an IAM token, provide it instead of the API key:

   export IAM_TOKEN=<service_account_IAM_token>
   

3. Send a search query to the SpeechSense API using cURL:

   curl -X POST https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/search \
      -H "Content-Type: application/json" \
      -H "authorization: Api-Key ${API_KEY}" \
      -d @search.json
   

   Where Api-Key is the API key for authentication. If using an IAM token, specify Bearer ${IAM_TOKEN} instead of Api-Key ${API_KEY}.

   Dialog IDs that meet the search criteria will be output to the terminal in JSON format.

Request examplesRequest examples

Request body example for full-text searchRequest body example for full-text search

For example, you need to find all the dialogs with the provider's technical support where the agent proposed filing a ticket for a technician's visit. Your JSON file with the request parameters will look as follows:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "query": {
    "text": "technician's visit",
    "channel_number": "0"
  },
}

Query results:

{
  "talk_ids": [
    "aud95sn63lra********"
  ],
  "talks_count":" 1",
  "next_page_token": ""
}

Where:

• talk_ids: IDs of dialogs that meet the search criteria.
• talks_count: Number of dialogs that meet the search criteria.
• next_page_token: Token of the next page with search results. If the search results are split into multiple pages, this token is used in the next query to get the next page. If this field is returned empty, the search results end on the current page.

Request body example for full-text search with filtering by parametersRequest body example for full-text search with filtering by parameters

For example, you need to find all the dialogs with the provider's technical support between 11:00 and 12:00 on September 24, 2024 in which the agent proposed filing a ticket for a technician's visit. Your JSON file with the request parameters will look as follows:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "query": {
    "text": "technician's visit",
    "channel_number": "0"
  },
  "filters": [
    {
      "key": "userMeta.date",
      "date_range": {
        "from_value": "2024-09-24T11:00:00Z",
        "to_value": "2024-09-24T12:00:00Z"
      }
    }
  ],  
}

Query results:

{
  "talk_ids": [
    "aud95sn63lra********"
  ],
  "talks_count":" 1",
  "next_page_token": ""
}

Where:

• talk_ids: IDs of dialogs that meet the search criteria.
• talks_count: Number of dialogs that meet the search criteria.
• next_page_token: Token of the next page with search results. If the search results are split into multiple pages, this token is used in the next query to get the next page. If this field is returned empty, the search results end on the current page.