본문 바로가기 메뉴 바로가기

Kakao i Connect Live::Kakao i Connect Live 2.0::API 레퍼런스::Admin API

페이지 이동경로

Admin API

커넥트 라이브는 라이브 스트리밍 서비스를 개발하는데 필요한 클라이언트 개발 환경을 제공하며, 대부분의 기능을 SDK로 수행할 수 있습니다. 하지만 Room에 대한 정보 조회 및 처리, Room에 대한 메시징 처리와 같이 일부 서비스의 서버에서 커넥트 라이브 서버에 접속하여 정보를 확인하거나 명령을 내려야 하는 경우가 존재합니다.
본 문서는 고객사의 관리자가 이런 작업을 처리할 수 있도록 도와주는 Admin API의 사용 방법을 설명합니다. Admin API는 Provision API, Room API, Webhook API로 구분됩니다.

표Admin API
구분 항목 설명
Provision API Provision Admin API를 사용하기 위한 Admin Token 발급 API
Room API Room.DestroyRoom Room 삭제
Room.ListParticipants 참여자 목록 조회
Room.KickParticipant 특정 참여자 강제 퇴장
Room.InactivateStream 특정 참여자의 스트림 송출 중단
Room.ListRooms 특정 서비스 ID의 Room 목록을 조회
Room.StartSTT STT 시작
Room.StopSTT STT 종료
Webhook Room events - Room.OnRoomOpened Room 생성 알림
Room events - Room.OnRoomClosed Room 종료 알림
Room events - Room.OnParticipantEvent 참여자 입장/퇴장 알림
STT STT 기능 진행 상태에 대한 이벤트 전달

Provision

Provision API는 Admin API를 사용하기 위한 Admin Token을 발급하고 연동할 서버의 URL을 조회하는 API입니다.
API 요청과 응답은 JSON-RPC 2.0을 사용하고 콘솔에서 설정한 서비스 인증 방식에 따라 기본 인증 방식: 커넥트 라이브 내부 인증과 고급 인증 방식: 서비스 자체 인증으로 구분됩니다. 자세한 설명은 커넥트 라이브 인증 프로세스에서 확인할 수 있습니다.

기본 인증 방식: 커넥트 라이브 내부 인증

서비스 인증 방식 설정이 기본 인증 방식(커넥트 라이즈 내부 인증)인 경우, Admin API 호출을 위한 Provision API도 기본 인증 방식으로 동작합니다. 기본 인증 방식은 총 2단계(Step 1과 Step 2)로 이루어져 있으며, 2차에 걸친 API Transaction은 5초 안에 이루어져야 합니다.
Admin Token 발급을 위해서는 일반 Service Secret이 아닌 Admin Secret을 사용합니다. Admin Secret은 카카오 i 커넥트 라이브 콘솔에서 확인할 수 있습니다.

Step 1

Provision API의 1단계 요청과 응답은 다음과 같습니다.

Request Syntax

코드예제CURL 요청 Syntax(Step 1) 

curl -X POST https://icl2-provisioning-ap2.k9ertc.io/api/rpc \
-H 'Content-Type: application/json' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Provision",
            "params": {
                    "version": "2.0",
                    "serviceId": "{YOUR_SERVICE_ID}",
                    "scheme": "internal"
            }
    }'

API 호출 방식
표API 호출 방식
메서드 요청 URL
POST https://icl2-provisioning-ap2.k9ertc.io/api/rpc
Request Header
표Provision Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Request Body
표Provision Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Provision으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Provisioning API 버전
- 기본값: 2.0
serviceId String 필수 서비스를 사용하기 위한 서비스 ID
- 카카오 i 커넥트 라이브 콘솔에서 발급
scheme String 필수 해당 서비스 ID의 인증 방식
- internal: 콘솔을 통해 발급한 어드민 시크릿(Admin Secret)을 사용하는 커넥트 라이브 내부 인증
Response

Provisioning은 HMAC(Hash-based Message Authentication Code) 인증을 사용하는데, 이때 보안성을 높이기 위해 nonce 등을 포함하는 절차가 필요합니다. 이런 이유로 총 두 번에 걸쳐서 요청을 수행합니다. 첫 번째 요청에서 nonce를 가져오기 위해 일부러 실패를 반환해야 하며, 이때 받은 nonce를 사용하여 HMAC을 계산해서 다시 두 번째 요청할 때만 인증이 성공되게 됩니다.
Provision API의 1단계 응답은 다음과 같습니다.

Sample Code

코드예제응답 성공 Sample Code(Step 1) 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": -11002,
                "message": "Unauthorized",
                "data": {
                        "nonce": "{NONCE}"
                }
        }
}

코드예제응답 실패 Sample Code(Step 1) 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements
표Provision Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 필수 에러 여부 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
Object 선택 응답 성공 시에만 반환
nonce String 선택 2단계 호출 시, 인증을 위해 value를 계산할 때 사용되는 값

Step 2

Provision API의 2단계 요청과 응답은 다음과 같습니다.

Request Syntax

코드예제CURL 요청 Syntax(Step 2) 

curl -X POST https://icl2-provisioning-ap2.k9ertc.io/api/rpc \
-H 'Content-Type: application/json' \
-d '{
            "jsonrpc": "2.0",
            "id": "2",
            "method": "Provision",
            "params": {
                    "version": "2.0",
                    "serviceId": "{YOUR_SERVICE_ID}",
                    "scheme": "internal",
                    "auth": {
                            "nonce": "{NONCE_FROM_INITIAL_TRANSACTION}",
                            "key": "{YOUR_SERVICE_ID}",
                            "value": "{CALCULATED_VALUE}"
                    }
            }
    }'

Request Header
표Provision Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Request Body
표Provision Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Provision으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Provisioning API 버전
- 기본값: 2.0
serviceId String 필수 서비스를 사용하기 위한 서비스 ID
scheme String 필수 해당 서비스 ID의 인증 방식
- internal: 콘솔을 통해 발급한 어드민 시크릿(Admin Secret)을 사용하는 커넥트 라이브 내부 인증
Object 필수 인증 관련 요청
nonce String 필수 1단계 호출 시, 응답에서 발급받은 값
key String 필수 서비스 ID
- 카카오 i 커넥트 라이브 콘솔에서 발급
value String 필수 계산을 통하여 생성된 값
- 그림. Value 생성 방법 참고
Value 생성 방법

Value 생성 방법 그림Value 생성 방법

Value 생성 예제

코드예제Value 생성 Syntax 

import hashlib

def main():
    serviceId = "YOUR_SERVICE_ID".        # 사용 중인 서비스 아이디
    adminSecret = "YOUR_ADMIN_SECRET"     # 사용 중인 어드민 시크릿
    nonce = "NONCE_VALUE_FROM_PROVISION"  # Provision에서 전달받은 nonce

    value = createValue(serviceId, adminSecret, nonce)
    print("Calculated value is : {}".format(value))

def createValue(serviceId, adminSecret, nonce):
    string1 = serviceId + ":" + adminSecret  # serviceId, adminSecret의 조합으로 string 생성
    hash1 = hashlib.sha256(bytes(string1, 'utf-8'))
    ha = hash1.hexdigest()

    string2 = ha + ":" + nonce  # 생성된 HA와 nonce의 조합으로 string 생성
    hash2 = hashlib.sha256(bytes(string2, 'utf-8'))
    value = hash2.hexdigest()

    return value

if __name__ == '__main__':
    main()

const {createHash} = require('node:crypto');

const serviceId = "YOUR_SERVICE_ID"         // 사용 중인 서비스 아이디
const adminSecret = "YOUR_ADMIN_SECRET"     // 사용 중인 어드민 시크릿
const nonce = "NONCE_VALUE_FROM_PROVISION"  // Provision에서 전달받은 nonce

function createValue(serviceId, adminSecret, nonce) {
  const hash1 = createHash('sha256');
  const dataForHa = `${serviceId}:${adminSecret}`
  hash1.update(dataForHa);
  const ha = hash1.copy().digest('hex')

  const hash2 = createHash('sha256');
  const dataForValue = `${ha}:${nonce}`
  hash2.update(dataForValue);
  const value = hash2.copy().digest('hex')
  return value
}

const value = createValue(serviceId, adminSecret, nonce)
console.log(`Calculated value is : ${value}`)

// this is value calculation code snippet for iCL 2.0 provision (Golang)
// you can run this code at (https://go.dev/play/p/fq15PI6U6Mp)
package main

import (
	"crypto/sha256"
	"encoding/hex"
	"fmt"
)

func main() {
	const serviceId = "YOUR_SERVICE_ID"         // 사용 중인 서비스 아이디
	const adminSecret = "YOUR_ADMIN_SECRET"     // 사용 중인 어드민 시크릿
	const nonce = "NONCE_VALUE_FROM_PROVISION"  // Provision에서 전달받은 nonce

	value := createValue(serviceId, adminSecret, nonce) // value 생성
	fmt.Printf("Calculated value is : %s", value)                     // value 출력
}

func createValue(serviceId, adminSecret, nonce string) string {
	string1 := serviceId + ":" + adminSecret // serviceId, adminSecret의 조합으로 string 생성
	hash1 := sha256.Sum256([]byte(string1))
	ha := hex.EncodeToString(hash1[:])

	string2 := ha + ":" + nonce // 생성된 HA와 nonce의 조합으로 string 생성
	hash2 := sha256.Sum256([]byte(string2))
	value := hex.EncodeToString(hash2[:])

	return value
}

public class Hash {
    public String createValue(String serviceId, String adminSecret, String nonce) throws NoSuchAlgorithmException {
        String string1 = serviceId + ":" + adminSecret;
        String ha = encrypt(string1);
        System.out.println(ha);
        String string2 = ha + ":" + nonce;
        String value = encrypt(string2);

        return value;
    }

    public String encrypt(String text) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        md.update(text.getBytes());

        return bytesToHex(md.digest());
    }

    private String bytesToHex(byte[] bytes) {
        StringBuilder builder = new StringBuilder();
        for (byte b : bytes) {
            builder.append(String.format("%02x", b));
        }
        return builder.toString();
    }
}

/////////////////////////////
import java.security.NoSuchAlgorithmException;

public class Main {
    private static String serviceId = "YOUR_SERVICE_ID";         // 사용 중인 서비스 아이디
    private static String adminSecret = "YOUR_ADMIN_SECRET";     // 사용 중인 어드민 시크릿
    private static String nonce = "NONCE_VALUE_FROM_PROVISION";  // Provision에서 전달받은 nonce

    public static void main(String[] args) throws NoSuchAlgorithmException {
        Hash hash = new Hash();
        String value = hash.createValue(serviceId, adminSecret, nonce);
        System.out.println(value);
    }
}

Response

Provision API의 2단계 응답은 다음과 같습니다.

Sample Code

코드예제응답 성공 Sample Code(Step 2) 

{
        "jsonrpc": "2.0",
        "id": "2",
        "result": {
                "uuid": "{UUID}",
                "token": "{TOKEN}",
                "ttl": {TTL},
                "api": "{API_URL}"
        }
}

코드예제응답 실패 Sample Code(Step 2) 

{
        "jsonrpc": "2.0",
        "id": "2",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}",
                "data": {
                        "nonce": "{REGENERATED_NONCE}"
                }
        }
}

Response Elements
표Provision Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
uuid String 필수 사용자를 식별하기 위한 ID
token String 필수 Admin Token으로 Admin API 호출 시 사용
ttl Integer 필수 토큰의 유효기간
api String 필수 Admin API를 사용하기 위한 API Endpoint URL
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
Object 필수 응답 실패 시에만 반환
nonce String 필수 임의의 숫자

고급 인증 방식: 서비스 자체 인증

고급 인증 방식에서 커넥트 라이브는 사용자 확인 및 권한 부여를 고객이 지정한 토큰 확인 서버에 일임합니다. Admin API 호출을 위한 Admin Token을 발급할 때도 이 절차는 그대로 유지됩니다. 커넥트 라이브는 토큰 확인 서버의 응답에 따라 Admin API 호출 권한이 있는지를 판단합니다.

Request

Response

Room

Room과 관련된 API는 다음과 같습니다.

Room.DestroyRoom

Room을 삭제하는 API입니다. Room 삭제 시 참여자들은 RoomDestroyed 타입의 Callback 이벤트를 수신합니다.
API 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Room.DestroyRoom",
            "params": {
                    "version": "2.0",
                    "roomId": "{ROOM_ID}"
            }
    }'

API 호출 방식

표API 호출 방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.DestroyRoom Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.DestroyRoom Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Room.DestroyRoom으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 미 입력 시 기본값(2.0)을 전달
roomId String 필수 삭제할 Room의 ID

Response

Sample Code

코드예제응답 성공 Sample Code 

 {
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
            "version": "2.0"
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.DestroyRoom Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
version String 필수 Room API 버전
- 2.0으로 고정
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.ListParticipants

Room의 참여자 목록을 조회하는 API입니다. API 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Room.ListParticipants",
            "params": {
                    "version": "2.0",
                    "roomId": "{ROOM_ID}"
            }
    }'

API 호출 방식

표API 호출 방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.ListParticipants Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.ListParticipants Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Room.ListParticipants으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 미입력 시 기본값(2.0)을 전달
roomId String 필수 참여자 목록을 조회할 Room의 ID

Response

Sample Code

코드예제응답 성공 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
                "participants": [
                        {
                                "participantId": "{PARTICIPANT_ID_1}"
                        },
                        {
                                "participantId": "{PARTICIPANT_ID_2}"
                        }
                ]
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.ListParticipants Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
String 선택 응답 성공 시 반환
Object[] 필수 해당 Room의 참여자 목록
participantId String 필수 해당 Room의 참여자 ID
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.KickParticipant

참여자를 강제로 퇴장시키는 API입니다. 강제로 퇴장된 참여자는 Kicked 타입의 이벤트를 수신합니다.
본 API를 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Room.KickParticipant",
            "params": {
                    "version": "2.0",
                    "roomId": "{ROOM_ID}",
                    "targets": [
                            {
                                    "participantId": "{PARTICIPANT_ID}"
                            }
                    ]
            }
    }'

API 호출 방식

표API 호출 방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.KickParticipant Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.KickParticipant Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Room.KickParticipant으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 미입력 시 기본값(2.0)을 전달
roomId String 필수 참여자를 강제 퇴장시킬 Room의 ID
Object[] 필수 강제 퇴장 대상 참여자 목록
participantId String 필수 강제 퇴장 대상 Participant ID

Response

Sample Code

코드예제응답 성공 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
            "version": "2.0"
        }
}

코드예제실패 응답 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.KickParticipant Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
version String 필수 Room API 버전
- 2.0으로 고정
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.InactivateStream

특정 참여자의 스트림 송출을 중단하는 API입니다. 송출이 중단된 참여자는 InactivatedStream 타입의 이벤트를 수신합니다.
메서드 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Room.InactivateStream",
            "params": {
                    "version": "2.0",
                    "roomId": "{ROOM_ID}",
                    "targets": [
                            {
                                    "participantId": "{PARTICIPANT_ID}",
                                    "streamId": {STREAM_ID}
                            }
                    ]
            }
    }'

API 호출 방식

표API 호출 방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.InactivateStream Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.InactivateStream Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Room.InactivateStream으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 미입력 시 기본값(2.0)을 전달
roomId String 필수 송출 중단 대상이 참여한 Room의 ID
Object[] 필수 송출 중단 대상 참여자 목록
participantId String 필수 송출 중단 대상 참여자 Participant ID
streamId Integer 필수 송출 중단 대상 Stream ID

Response

Sample Code

코드예제응답 성공 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
            "version": "2.0"
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.InactivateStream Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
version String 필수 Room API 버전
- 2.0으로 고정
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.ListRooms

해당 서비스의 Room 목록 조회 API입니다. 메서드 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
            "jsonrpc": "2.0",
            "id": "1",
            "method": "Room.ListRooms",
            "params": {
                    "version": "2.0"
            }
    }'

API 호출 방식

표API 호출 방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.ListRooms Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSON-RPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.ListRooms Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 메서드명
- Room.ListRooms으로 고정
Object 필수 JSON-RPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 미입력 시 기본값(2.0)을 전달

Response

Sample Code

코드예제응답 성공 Sample Code 

  {
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
                "rooms": [
                        {
                                "roomId": "{ROOM_ID_1}"
                        },
                        {
                                "roomId": "{ROOM_ID_2}"
                        }
                ]
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.ListRooms Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
Objects[] 필수 전체 Room 목록
roomId String 필수 조회할 Room의 ID
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.StartSTT

Room의 대화 내용에 대한 실시간 STT 기능을 시작합니다. 메서드 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "Room.StartSTT",
        "params": {
            "version": "2.0",
            "roomId": "{ROOM_ID}"
        }
    }'

API 호출방식

표API 호출방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.StartSTT Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSONRPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.StartSTT Request Body
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 매서드명
- Room.StartSTT로 고정
Object 필수 JSONRPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 기본값: 2.0
roomId String 필수 STT를 시작할 Room의 ID

Response

Sample Code

코드예제응답 성공 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
                "version": "2.0"
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.StartSTT Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
version String 필수 Room API 버전
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Room.StopSTT

실시간 STT 기능을 종료합니다. 메서드 호출 시, Provision API를 사용하여 발급받은 Admin Token 및 API Endpoint URL 정보가 필요합니다.

Request

Request Syntax

코드예제CURL 요청 Syntax 

curl -X POST {API_ENDPOINT_FROM_PROVISION} \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {YOUR_TOKEN}' \
-d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "Room.StopSTT",
        "params": {
            "version": "2.0",
            "roomId": "{ROOM_ID}"
        }
    }'

API 호출방식

표API 호출방식
메서드 요청 URL
POST {API_ENDPOINT_FROM_PROVISION}

Request Header

표Room.StopSTT Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 JSONRPC 2.0을 사용하기 위한 헤더
- application/json으로 고정
Authorization String 필수 Bearer {YOUR_TOKEN}: Provision API를 통해 발급받은 Admin Token

Request Body

표Room.StopSTT Request Body
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 임의의 문자열
method String 필수 JSON-RPC 2.0의 매서드명
- Room.StopSTT로 고정
Object 필수 JSONRPC 2.0의 파라미터
version String 선택 사용하고자 하는 Room API 버전
- 기본값: 2.0
roomId String 필수 STT를 종료할 Room의 ID

Response

Sample Code

코드예제응답 성공 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "result": {
                "version": "2.0"
        }
}

코드예제응답 실패 Sample Code 

{
        "jsonrpc": "2.0",
        "id": "1",
        "error": {
                "code": {ERROR_CODE},
                "message": "{ERROR_MESSAGE}"
        }
}

Response Elements

표Room.StopSTT Response Elements
필드 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
id String 필수 JSON-RPC 2.0의 Transaction ID
- 호출 시 지정한 문자열
Object 선택 응답 성공 시 반환
version String 필수 Room API 버전
Object 선택 응답 실패 시 반환
code Integer 필수 에러 코드
message String 필수 에러 메시지
data Object 선택 에러 관련 데이터

Webhook

콘솔에서 Webhook 정책과 수신 URL을 설정하면, 발생한 이벤트들을 HTTP POST request로 받을 수 있습니다.
Webhook을 받는 서버에서는 json payload가 포함된 HTTP POST를 처리할 수 있어야 하며, HTTP/1.1 keep-alive를 지원해야 합니다.

Room.OnRoomOpened

Room이 생성되었을 때 Room 생성 이벤트를 받을 수 있습니다.

Request

Request Syntax

코드예제Room.OnRoomOpened Request Syntax 

{
        "jsonrpc": "2.0",
        "method": "Room.OnRoomOpened",
        "params": {
                "version": "2.0",
                "serviceId": "{SERVICE_ID}",
                "roomId": "{ROOM_ID}",
                "ts": {UNIX_MILLISECONDS},
                "initiator": {
                        "uuid": "{INITIATOR_UUID}",
                        "participantId": "{INITIATOR_PARTICIPANT_ID}"
                },
                "seqNo": {SEQUENCE_NUMBER}
        }
}

Request Body

표Room.OnRoomOpened Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
method String 필수 JSON-RPC 2.0의 매서드명
- Room.OnRoomOpened로 고정
Object 필수 jsonRPC의 파라미터
version String 필수 Webhook 버전
- 2.0
serviceId String 필수 서비스를 사용하기 위한 서비스 아이디
- 콘솔에서 발급
roomId String 필수 Room의 ID
ts Integer 필수 이벤트 발생 시간
- unix milliseconds
Object 필수 Room을 생성한 참여자 정보
participantId String 필수 참여자 Participant ID
uuid Integer 필수 참여자 UUID
seqNo Integer 필수 메시지 전송 순번

Response

JSON-RPC notification이므로, body 없는 HTTP 200 OK로 응답해야 합니다.

Room.OnRoomClosed

Room이 종료되었을 때 Room 종료 이벤트를 받을 수 있습니다.

Request

Request Syntax

코드예제Room.OnRoomClosed Request Syntax 

{
        "jsonrpc": "2.0",
        "method": "Room.OnRoomClosed",
        "params": {
                "version": "2.0",
                "serviceId": "{SERVICE_ID}",
                "roomId": "{ROOM_ID}",
                "ts": {UNIX_MILLISECONDS},
                "seqNo": {SEQUENCE_NUMBER}
        }
}

Request Body

표Room.OnRoomClosed Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
method String 필수 JSON-RPC 2.0의 매서드명
- Room.OnRoomClosed로 고정
Object 필수 jsonRPC의 파라미터
version String 필수 Webhook 버전
- 2.0으로 고정
serviceId String 필수 서비스를 사용하기 위한 서비스 아이디
- 콘솔에서 발급
roomId String 필수 Room의 ID
ts Integer 필수 이벤트 발생 시간
- unix milliseconds
seqNo Integer 필수 메시지 전송 순번

Response

JSON-RPC notification이므로, body 없는 HTTP 200 OK로 응답해야 합니다.

Room.OnParticipantEvent

참여자가 Room에 입장 또는 퇴장했을 때 참여자 변경 이벤트를 받을 수 있습니다.

Request

Sample Code

코드예제Room.OnParticipantEvent Request Syntax 

{
        "jsonrpc": "2.0",
        "method": "Room.OnParticipantEvent",
        "params": {
                "version": "2.0",
                "serviceId": "{SERVICE_ID}",
                "roomId": "{ROOM_ID}",
                "openedAt": {UNIX_MILLISECONDS},
                "initiator": {
                        "uuid": "{INITIATOR_UUID}",
                        "participantId": "{INITIATOR_PARTICIPANT_ID}"
                },
                "seqNo": {SEQUENCE_NUMBER},
                "events": [
                        {
                                "event": "{EVENT_TYPE}",
                                "ts": {UNIX_MILLISECONDS},
                                "participant": {
                                        "uuid": "{PARTICIPANT_UUID}",
                                        "participantId": "{PARTICIPANT_ID}"
                                }
                        }
                ]
        }
}

표Room.OnParticipantEvent Request Body
파라미터 타입 필수 여부 설명
jsonrpc String 필수 JSON-RPC 2.0 버전
- 2.0으로 고정
method String 필수 JSON-RPC 2.0의 매서드명
- Room.OnParticipantEvent로 고정
Object 필수 jsonRPC의 파라미터
version String 필수 Webhook 버전
- 2.0으로 고정
serviceId String 필수 서비스를 사용하기 위한 서비스 아이디
- 콘솔에서 발급
roomId String 필수 Room의 ID
openedAt Integer 필수 Room 생성 시간
- unix milliseconds
Object 필수 Room을 생성한 Participant 정보
uuid String 필수 Room 생성자 UUID
participantId String 필수 Room 생성자 Participant ID
seqNo Integer 필수 메시지 전송 순번
Object[] 필수 Participant 이벤트 목록
event String 필수 이벤트 종류
joined: 참여자 입장
left: 참여자 퇴장
ts Integer 필수 이벤트 발생 시간
- unix milliseconds
Object 필수 Room에 입장한 참여자 정보
uuid String 필수 참여자 UUID
participantId Integer 필수 참여자 Participant ID

Response

JSON-RPC notification이므로, body 없는 HTTP 200 OK로 응답해야 합니다.

STT Webhook

STT 기능의 진행 단계(준비/시작/종료) 별로 미리 설정된 고객사 webhook 서버로 이벤트를 전달합니다.

Request

Webhook 호출 Syntax

고객사의 Webhook 서버로 다음과 같은 HTTP POST 요청이 전송됩니다.

코드예제CURL 요청 syntax 

curl -X POST https://{설정된 고객사의 webhook_url} \
-H "Content-Type: application/json" \
-d '{
        "name": "stt",
        "event": {이벤트 종류},
        "serviceId": {service ID},
        "roomId": {room ID},
        "error": {오류 메시지},
        "data": {
        }
    }'

API 호출방식

표API 호출방식
메서드 요청 URL
POST https://{설정된 고객사의 webhook_url}

Request Header

표STT Webhook Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 application/json으로 고정

Request Body

표STT Webhook Request Body
필드 타입 필수 여부 설명
name String 필수 webhook의 종류를 구분하는 명칭
- stt로 고정
serviceId String 필수 STT를 진행하는 서비스 ID
roomId String 필수 STT를 진행하는 Room의 ID
event String 필수 Event 종류(prepare, start, finish) 중 1 선택
- 이벤트 유형에 따른 코드 예제는 Sample Code (Event 유형) 참고
prepare: Admin API에서 Room.StartSTT 호출 시 발생
start: STT 기능이 정상적으로 시작되었을 때 발생
finish: STT 기능이 종료되었을 때 발생
- STT 중지 또는 오류로 인해 start event가 발생하지 않은 경우에도 finish event는 발생
error String 선택 오류 메시지로 정상적이지 않은 STT 중단 시 포함
data Object 필수 추가적으로 전달이 필요한 확장성 데이터

Response

STT로부터 전달받은 Request를 성공적으로 처리한 경우, webhook 서버는 HTTP Status 200 성공 응답을 반환해야 합니다.

Sample code (Event 유형)

Event 유형에 따른 API 요청 코드 예제는 다음과 같습니다.

코드예제prepare(Admin API의 Room.StartSTT 호출 시) Sample Code 

{
        "name": "stt",
        "serviceId": "sampleSvcId",
        "roomId": "test-room",
        "event": "prepare",
        "data": {
        }
}

코드예제start(STT가 정상적으로 시작된 시점에서 발생) Sample Code 

{
    "name": "stt",
    "serviceId": "sampleSvcId",
    "roomId": "test-room",
    "event": "start",
    "data": {
    }
}

코드예제finish(STT가 정상 종료된 시점에서 발생) Sample Code 

{
    "name": "stt",
    "serviceId": "sampleSvcId",
    "roomId": "test-room",
    "event": "finish",
    "data": {
    }
}

코드예제finish(STT가 비정상 종료된 시점에서 발생) Sample Code 

{
    "name": "stt",
    "serviceId": "sampleSvcId",
    "roomId": "test-room",
    "event": "finish",
    "error": "internal error",
    "data": {
    }
}

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.