Manage hotwords

Authorization

Before you use the Hotword OpenAPI, you must have an identity account and an AccessKey pair to access the API from a client. For more information, see Create an AccessKey pair. The Alibaba Cloud account that you use to call the Hotword OpenAPI must be the same account that you use to create the multi-modal interactive application in Alibaba Cloud Model Studio.

To call the Hotword OpenAPI, a Resource Access Management (RAM) user must have permissions to access the multimodal dialog product. To grant the required permissions:

In the RAM console, go to Identity Management > Users. Find the RAM user that is associated with the AccessKey pair. In the Actions column, click Add Permissions. Select the AliyunMultimodalDialogFullAccess system policy and grant it to the RAM user. This policy grants permissions to manage Multimodal Dialog.

Sample code

To quickly integrate with the Hotword OpenAPI, you can use the Alibaba Cloud software development kit (SDK) to call the OpenAPI. You can view sample code and download the complete sample project from the OpenAPI Explorer page.

Request parameters

For a complete description of the request parameters, see the Hotword OpenAPI portal. This topic provides detailed parameter examples in JSON format for operations such as creating, deleting, updating, and querying hotword lists. For information about how to call the code, see the Sample code section.

Create a hotword list

{
  "action": "createVocabulary",
  "vocabularyName": "Hotword List",
  "vocabulary":[
          {"text": "Alice", "lang": "en", "type": "contact_name"}, 
          {"text": "Bale", "lang": "en", "type": "contact_name"}
      ]
}

{
  "code": 200,
  "message": "Success", 
  "requestId": "a2a2987e2f8a********4ed7464d9593",
  "vocabularyId": "44f683d4cfd********c367f7f156587"
}

Delete a hotword list

{
  "action": "deleteVocabulary",
  "vocabularyId": "44f683d4cfd********c367f7f156587"
}

{
  "code": 200,
  "message": "Success", 
  "requestId": "b2a2987e2f8a********4ed7464d9593"
}

Update a hotword list

{
  "action": "updateVocabulary",
  "vocabularyId": "44f683d4cfd********c367f7f156587",
  "vocabulary":[
          {"text": "Alice", "lang": "en", "type": "contact_name"},
          {"text": "Bale", "lang": "en", "type": "contact_name"}
      ]
}

{
  "code": 200,
  "message": "Success", 
  "requestId": "c2a2987e2f8a********4ed7464d9593"
}

Query hotword lists

{
  "action": "queryVocabulary",
  "vocabularyIds": [
    "44f683d4cfd********c367f7f156587",
    "44f683d4cfd********c367f7f156587"
  ]
}

{
  "code": 200,
  "message": "Success", 
  "requestId": "d2a2987e2f8a********4ed7464d9593",
  "vocabularys":[
      {
        "vocabularyId": "44f683d4cfd********c367f7f156587",
        "vocabularyName": "***",
        "vocabulary":[
            {"text": "Alice", "lang": "en", "type": "contact_name"},
            {"text": "Bale", "lang": "en", "type": "contact_name"}
        ],
        "modifiedTime": 1749565022301
      },
      {
        "vocabularyId": "44f683d4cfd********c367f7f156587",
        "vocabularyName": "***",
        "vocabulary":[
            {"text": "Alice", "lang": "en", "type": "contact_name"},
            {"text": "Bale", "lang": "en", "type": "contact_name"}
        ],
        "modifiedTime": 1749565022301
      } 
    ]
}

FAQ

1. How do I use a hotword list created with the Hotword OpenAPI in a conversation flow?

For more information, see Real-time Multimodal Interaction Protocol (WebSocket). In the Start instruction, specify the hotword list ID in the parameters.upstream.vocabulary_id parameter. This setting overwrites the hotword configuration specified in the console.