System

System 인터페이스는 KVS 시스템 환경 변수 제어와 관련된 Message를 제공합니다.

Event

Event Message의 호출 방식은 다음과 같습니다.

SynchronizeState

System.SynchronizeState는 새 연결이 설정될 때 모든 제품 구성 요소의 상태를 KVS를 업데이트하기 위해 Service Agent가 KVS에 전송하는 Event입니다. Service Agent는 1시간마다 KVS로 System.SynchronizeState를 전송해야 합니다.

System.SynchronizeState가 발생하는 경우는 다음과 같습니다.

• Servie Agent가 KVS와 새롭게 연결되었을 때
• 주기적으로 System.RequestSynchronizeState Instruction을 수신했을 때

Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.RequestSynchronizeState",
      "messageId": "{STRING}"
    },
    "body": {
      "settings": [
        {
          "key": "{STRING}",
          "value": "{STRING}"
        }
      ]
    }
  }
}

Request Header

Request Body

BootUp

System.BootUp는 애플리케이션이 재시작되어 네트워크가 연결될 때, Service Agent가 KVS로 전송하는 Event입니다.

Request Syntax

{
        "instruction": {
                "header": {
                        "type": "System.Bootup",
                        "messageId": "{STRING}"
                },
                "body": {
                        "uptime": {LONG},
                        "log": "{STRING}"
                }
        }
}

Request Header

Request Body

Exception

System.Exception는 Service Agent가 KVS가 전송한 Instruction을 실행할 수 없을 때, Service Agent가 KVS로 전송하는 Event입니다. Event 전송 시, Service Agent는 State를 포함한 모든 Service Agent의 구성 요소 상태를 전달해야 합니다.
State에 대한 자세한 설명은 State를 참고하시기 바랍니다.

Request Syntax

{
  "event": {
    "header": {
      "type": "System.Exception",
      "messageId": "{STRING}"
    },
    "body": {
      "instruction": "{STRING}",
      "error": {
        "type": "{STRING}",
        "token": "{STRING}",
        "message": "{STRING}"
      }
    }
  }
}

Request Header

Request Body

Idle

System.Idle는 SubscribeNextIdle Instruction에서 주어진 interval 동안 Service Agent의 유휴 상태가 지속될 경우, Service Agent가 KVS로 전송하는 Event입니다. 유휴 상태란 Recognizer.Text Event가 진행 중이지 않으면서 발화 또는 재생 콘텐츠가 없는 경우를 의미합니다.

안내
System.Idle 인터페이스는 1.1 버전부터 지원합니다.

Request Syntax

{
  "event": {
    "header": {
      "type": "System.Idle",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {
      "token": "{STRING}"
    }
  }
}

Request Header

Request Body

안내
대표 명령어 기능을 지원하기 위해서는 반드시 System.Idle 인터페이스를 구현해야 합니다.
대표 명령어 시나리오는 [카카오 i 기술문서] 대표 명령어를 참고하시기 바랍니다.

RequestCanceled

System.RequestCanceled는 Service Agent가 발화 인식 요청을 받고 KVS에 첨부 데이터를 전송하는 중, 해당 요청을 취소 할 때 다음 파트에 전송하는 Event입니다.

Request Syntax

코드예제System.RequestCanceled Request Syntax

{
  "event": {
    "header": {
      "type": "System.RequestCanceled",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {
      "cause": "{STRING}"
    }
  }
}

Request Header

Request Body

RequestCompleted

System.RequestCompleted는 Service Agent가 Multipart Message로 첨부 데이터를 전달할 때, 첨부 데이터 전송이 정상적으로 완료되었음을 Multipart 중 마지막 파트에 전달하는 Event입니다. 카카오 i 서버에서 전송된 첨부 데이터를 실시간 처리 중 Service Agent에서 취소를 한 경우에는 첨부 데이터 전송을 중단하고, 마지막 파트에 System.RequestCanceled Event를 전송하여 현재까지 전송된 첨부 데이터의 처리 결과를 무시하도록 합니다.

안내
첨부 데이터 전송 후 마지막 파트에 System.RequestCanceled 또는 System.RequestCompleted가 전달되지 않으면, System.RequestCompleted가 전송된 것과 동일하게 첨부 데이터 전송이 정상적으로 완료된 것으로 간주합니다.

• 예를 들어, Service Agent에서 카카오 i 서버로 음성 인식을 요청할 때 Multipart Message의 <The First Part>에는 Recognizer.Speech Event의 JSON 데이터, <The Second Part>에는 오디오 바이너리, <The Third Part>에는 System.RequestCompleted Event의 JSON 데이터를 전달합니다.

Request Syntax

코드예제System.RequestCompleted Request Syntax

{
  "event": {
    "header": {
      "type": "System.RequestCompleted",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {}
  }
}

Request Header

Request Body

Request Body는 없습니다.

Instruction

Event Message의 응답으로 Instruction Message를 수신할 수도 있습니다. Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

RequestSynchronizeState

System.RequestSynchronizeState는 KVS가 Service Agent로 State를 동기화하고 서버에서 변경된 세팅 값을 Service Agent에 반영하도록 지시하는 Instruction입니다. 이에 대한 응답으로 Service Agent는 주어진 내용을 반영 후 System.SynchronizeState Event를 전송해야 합니다.

Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.RequestSynchronizeState",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {
      "settings": [
        {
          "key": "{STRING}",
          "value": "{STRING}"
        }
      ]
    }
  }
}

Request Header

Request Body

ClearCache

System.ClearCache는 KVS가 Service Agent 자체적으로 사용하고 있는 캐시를 모두 제거하도록 지시하는 Instruction입니다.

Request Syntax

{
  "instruction": {
    "header": {
      "type": "ClearCache",
      "messageId": "test",
      "dialogRequestId": "test"
    },
    "body": {}
  }
}

Request Header

Close

System.Close는 KVS가 Service Agent에 서버와의 HTTP/2 연결을 종료하도록 지시하는 Instruction입니다.

Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.Close",
      "messageId": "{STRING}"
    },
    "body": {
      "type": "{STRING}",
      "token": "{STRING}",
      "message": "{STRING}"
    }
  }
}

Request Header

Request Body

Heartbeat

System.Heartbeat는 주기적으로 KVS와 연결된 Down Channel로 Keepalive 연결을 목적으로 하는 Instruction입니다. Service Agent는 주기적으로 해당 Instruction의 수신 여부를 확인하여 Down Channel이 유효한지 검사하며, Service Agent가 수행해야 할 별도의 처리는 없습니다.

Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.Heartbeat",
      "messageId": "{STRING}"
    },
    "body": {
      "time": "{STRING}"
    }
  }
}

Request Header

Request Body

SubscribeNextIdle

System.SubscribeNextIdle은 Service Agent의 유휴 상태가 일정 시간 이상 지속될 경우 KVS가 Service Agent에 System.Idle Event를 전달하도록 지시하는 Instruction입니다. 유휴 상태란 Recognizer.Text Event가 진행 중이지 않으면서 발화 또는 재생 콘텐츠가 없는 경우를 의미합니다.

주의
SubscribeNextIdle 인터페이스는 1.1 버전부터 지원하고 있습니다.

• 지원하는 버전에 대한 자세한 설명은 Capability를 참고하시기 바랍니다.

Request Syntax

{
        "instruction": {
                "header": {
                        "type": "System.SubscribeNextIdle",
                        "messageId": "{STRING}",
                        "dialogRequestId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "idleType": "{STRING}",
                        "interval": {LONG},
                        "ttl": {LONG},
                        "suspendPlayMs": {LONG}
                }
        }
}

Request Header

Request Body

안내
대표 명령어 기능을 지원하기 위해서는 반드시 System.SubscribeNextIdle 인터페이스를 구현해야 합니다.
자세한 설명은 [카카오 i 기술문서] 대표 명령어를 참고하시기 바랍니다.

UnsubscribeIdle

System.UnsubscribeIdle은 KVS가 Service Agent에 구독 요청한 Idle의 구독 취소를 요청할 경우, 이전에 구독 요청한 token을 포함하여 지시하는 Instruction입니다.

주의
SubscribeNextIdle 인터페이스는 1.2 버전부터 지원하고 있습니다.

• 지원하는 버전에 대한 자세한 설명은 Capability를 참고하시기 바랍니다.

Request Syntax

코드예제System.UnsubscribeIdle Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.UnsubscribeIdle",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {
      "token": "{STRING}"
    }
  }
}

Request Header

Request Body

HoldDownchannel

System.HoldDownchannel은 다운채널로 전송되는 Instruction 메시지 전송을 대기하기 위해 다운채널 커넥션을 유지(생성) 하라는 명령입니다. 지정된 ttl 시간만큼 유지한 이후에는 연결을 종료해도 됩니다.

Request Syntax

코드예제System.HoldDownchannel Request Syntax

{
  "instruction": {
    "header": {
      "type": "System.HoldDownchannel",
      "messageId": "{{STRING}}"
    },
    "body": {
      "ttl": "{{LONG}}"
    }
  }
}

Request Header

Request Body

State

State Message는 모든 Event Message를 전송하는 요청(Request)에 항상 포함되어야 합니다.

SystemState

디버깅이 필요한 경우에 Service Agent의 시스템 상태 정보를 Key와 Value로 표시하여 전달합니다. 해당 State는 선택적으로 전송됩니다.

Request Syntax

코드예제System.SystemState Request Syntax

{
  "header": {
    "type": "System.SystemState"
  },
  "body": {
    "properties": [
      {
        "key": "{STRING}",
        "value": "{STRING}"
      }
    ]
  }
}

Request Header

Request Body