对话 API
可以通过对话集成从文本中识别意图并触发它们。
这里提供了一个 API 端点，用于接收输入语句并生成对话响应。通过传递由 Home Assistant 生成的对话 ID，可以在多次输入与响应之间跟踪一次“对话”。
该 API 可通过 Rest API 和 Websocket API 使用。
可以像下面这样将一句话通过 POST 发送到 /api/conversation/process：
{
"text": "turn on the lights in the living room",
"language": "en"
}
或者通过 WebSocket API 发送，如下所示：
{
"type": "conversation/process",
"text": "turn on the lights in the living room",
"language": "en"
}
可用的输入字段如下：
对话响应
/api/conversation/process 返回的 JSON 响应包含已触发意图的执行结果信息，例如：
{
"continue_conversation": true,
"response": {
"response_type": "action_done",
"language": "en",
"data": {
"targets": [
{
"type": "area",
"name": "Living Room",
"id": "living_room"
},
{
"type": "domain",
"name": "light",
"id": "light"
}
],
"success": [
{
"type": "entity",
"name": "My Light",
"id": "light.my_light"
}
],
"failed": [],
},
"speech": {
"plain": {
"speech": "Turned Living Room lights on"
}
}
},
"conversation_id": "<generated-id-from-ha>",
}
"response" 对象中可用的属性如下：
对话 ID 会与对话响应一并返回。
如果 continue_conversation 为 true，则表示对话代理预期用户继续跟进输入。
响应类型
动作已完成
该意图在 Home Assistant 中产生了一个动作，例如打开灯。响应中的 data 属性包含一个 targets 列表，其中每个 target 的形式如下：
还会包含另外两个 target 列表，其中包含执行 success 或 failed 的设备或实体：
{
"response": {
"response_type": "action_done",
"data": {
"targets": [
(area or domain)
],
"success": [
(entities/devices that succeeded)
],
"failed": [
(entities/devices that failed)
]
}
}
}
一个意图可以包含多个 target，它们会叠加应用。target 必须按从一般到具体的顺序排列：
area
domain
- Home Assistant 集成 domain，例如 "light"
device_class
- 某个 domain 的设备类别，例如 "cover" domain 下的 "garage_door"
device
entity
custom
大多数意图最终会得到 0、1 或 2 个 target。当前只有在涉及设备类别时才会出现 3 个 target。target 组合示例如下：
- "Turn off all lights"
- "Turn on the kitchen lights"
- 2 个 target：
area:kitchen、domain:light
- "Open the kitchen blinds"
- 3 个 target：
area:kitchen、domain:cover、device_class:blind
查询回答
该响应是对问题的回答，例如“what is the temperature?”。回答文本见 speech 属性。
{
"response": {
"response_type": "query_answer",
"language": "en",
"speech": {
"plain": {
"speech": "It is 65 degrees"
}
},
"data": {
"targets": [
{
"type": "domain",
"name": "climate",
"id": "climate"
}
],
"success": [
{
"type": "entity",
"name": "Ecobee",
"id": "climate.ecobee"
}
],
"failed": [],
}
},
"conversation_id": "<generated-id-from-ha>",
}
错误
在意图识别或处理期间发生了错误。具体错误类型请参见 data.code，错误消息请参见 speech 属性。
{
"response": {
"response_type": "error",
"language": "en",
"data": {
"code": "no_intent_match"
},
"speech": {
"plain": {
"speech": "Sorry, I didn't understand that"
}
}
}
}
data.code 是一个字符串，可取值如下：
no_intent_match - 输入文本未匹配到任何意图。no_valid_targets - 指定的区域、设备或实体不存在。failed_to_handle - 处理该意图时发生意外错误。unknown - 在意图处理范围之外发生了错误。
语音
对用户播报的响应通过响应中的 speech 属性提供。它可以是纯文本（默认），也可以是 SSML。
对于纯文本语音，响应如下所示：
{
"response": {
"response_type": "...",
"speech": {
"plain": {
"speech": "...",
"extra_data": null
}
}
},
"conversation_id": "<generated-id-from-ha>",
}
如果语音使用 SSML，则会是下面这样：
{
"response": {
"response_type": "...",
"speech": {
"ssml": {
"speech": "...",
"extra_data": null
}
}
},
"conversation_id": "<generated-id-from-ha>",
}
对话 ID
如果响应的对话代理支持，对话可以通过 Home Assistant 内部生成的唯一 ID 来跟踪。要继续一段对话，请从 HTTP API 响应中获取 conversation_id（与对话响应一起返回），并将其添加到下一条输入语句中：
初始输入语句：
{
"text": "Initial input sentence."
}
JSON 响应包含对话 ID：
{
"conversation_id": "<generated-id-from-ha>",
"response": {
(conversation response)
}
}
使用下一条输入语句发起 POST：
{
"text": "Related input sentence.",
"conversation_id": "<generated-id-from-ha>"
}
预加载句子
可以使用 WebSocket API 预加载某种语言的句子：
{
"type": "conversation/prepare",
"language": "en"
}
可用的输入字段如下：
