# API Reference ## **Synchronization** Omnitalk SDK는 통신 서비스를 제공하기 위해 Offer-Answer 구조로 설계되어 있으며, 이를 위해 반드시 async, await 비동기 처리를 지원해야 합니다. ## **Global Module** sdk 객체를 생성합니다. 생성된 객체는 이후 모든 메서드 호출에 사용됩니다. Service Id와 Service Key는 [console 페이지](https://omnitalk.io/console/service/service-id)에서 발급 가능하며 노출되지 않도록 주의하여야 합니다. ```javascript Omnitalk.sdkInit(service_id, service_key); const sdk = Omnitalk.getInstance(); ```
cdn import 시 객체 생성 Omnitalk.Omnitalk.sdkInit(service\_id, service\_key);\ const sdk = Omnitalk.getInstance();
*\*O = Optional, M = Mandatory*
ParameterMandatoryTypeDescription
service_idMString발급받은 Service ID
service_keyOStringAPP 서비스인 경우 KEY 필수
## Audio/Video Tag Rule 음성을 입출력하기 위한 Audio 태그는 옴니톡 SDK에서 자동으로 생성하며, Video 입출력을 위한 Tag ID는 아래의 규칙이 적용됩니다.
DOMIDAttributeUse ForCreator
audioOmnitalk-Audio-0autoplay-SDK
videoOmnitalk-LocalVideo-0autoplay, playinlinepublish()Customer
videoOmnitalk-RemoteVideo-0
...
Omnitalk-RemoteVideo-31		autoplay, playinlinesubscribe()Customer
## EVENT\_MESSAGE ## on 이벤트 메시지는 [여기](https://docs.omnitalk.io/commons/event-message)를 참고하시면 됩니다. 이벤트 메시지를 수신하기 위해서는 옴니톡의 이벤트 리스너 API를 이용하시면 됩니다. ```javascript sdk.on('event', ()=>{}) ``` leave 이벤트로 서버와의 연결이 끊기거나 사용자 인터넷 환경 불안정 등으로 인터넷 연결이 끊길 때 발생하는 close 메시지입니다. ```jsx sdk.on('close', ()=>{}) ``` ## ## createSession 사용자의 세션을 생성하기 위해 서버와 연결하고 그 결과로 세션 아이디, 유저 아이디 등을 포함한 객체를 리턴합니다. ```javascript const sessionInfo = await sdk.createSession(user_id); ```
ParameterMandatoryTypeDescription
user_idOString사용자별 과금 정보, 통화 기능등에 사용되며, 미입력시 임의의 ID 정보를 자동으로 할당
리턴 객체 예시 | createSession { "result": "success", "session": "YjQ1ZGUzYzA3MmJhLTM0", "user\_id": "KclCDjtcOn" }
## ~~sessionList(deprecated)~~ 세션 생성 후 같은 Service Id 및 Key를 사용하는 모든 사용자를 조회합니다. ```javascript await sdk.sessionList(); ```
ParameterMandatory/OptionalTypeDescription
pageONumberdefault = 1, per page = 10
리턴 객체 | sessionList { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", "page": 1, "count": 1, "list": \[ { "user\_id": "omnitalk", "call\_type": "videocall", "state": "busy", } ] }
## createRoom 모든 방송은 룸에서 이루어집니다. 방송을 시작할 룸 타입을 전달해 룸을 생성합니다. 방 주제나 방의 비밀 번호를 설정할 수 있습니다. start\_date 및 end\_date는 룸 생성 및 종료 예상 시간을 설정할 때 이용합니다. ```javascript const roomInfo = await sdk.createRoom(room_type); ``` | Parameter | Mandatory/Optional | Type | Description | | ----------- | ------------------ | ------ | ----------- | | room\_type | M | String | | | subject | O | String | | | secret | O | Number | max 6 | | start\_date | O | Number | Date 객체 | | end\_date | O | Number | Date 객체 |
리턴 객체 예시 | createRoom { "room\_id": "b45de3c016739550222295", "session": "YjQ1ZGUzYzA3MmJhLTM0" }
## **roomList** 인수로 전달한 룸타입에 해당하는 모든 룸을 조회해 리스트로 반환합니다. default인 "all"은 룸타입에 관계없이 전체 룸을 조회합니다. ```javascript const roomList = await sdk.roomList(room_type); ``` | Parameter | Mandatory/Optional | Type | Description | | ---------- | ------------------ | ------ | -------------------------- | | room\_type | O | String | "all"(default) | | page | O | Number | default = 1, per page = 10 |
리턴 객체 예시 | roomList { "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD", "count": 1, "page": 1, "room\_type": "all", "list": \[ { "room\_id": "8a1086680e47261208eeff87000b", "room\_type": "videoroom", "count": 0, "secret": true, "sip\_support": true, "sip\_number": "991000" (optional) "start\_date": 1686816051, "end\_date": 1686819651, "reg\_date": 1686816051, "subject": "fish" } ] }
## joinRoom 방송을 시작하거나 다른 방송을 시청하기 위해서는 반드시 룸 참여 과정이 필요합니다. ```javascript const joinResult = await sdk.joinRoom(room_id); ``` | Parameter | Mandatory/Optional | Type | Description | | ---------- | ------------------ | ------ | ---------------- | | room\_id | M | String | | | secret | O | Number | max 6 | | user\_name | O | String | max 32, nickname |
리턴 객체 예시 | joinRoom { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", "room\_id": "8a1086680e47261208eeff87000b", "room\_type": "videoroom" }
## partiList 해당 룸에 참여한 모든 사용자(방송 개시 여부와 무관)를 조회합니다. room\_id를 전달하지 않으면 자신이 참여한 룸의 참여자 리스트를 조회합니다. ```javascript const partiListResult = await sdk.partiList(room_id); ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | -------------------------- | | room\_id | O | String | | | page | O | Number | default = 1, per page = 10 |
리턴 객체 예시 | partiList { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", "page": 1, "count": 1, "list": \[ { "session": "YzMyYWE1YTA3MmJhMTY4", "user\_id": "", "user\_name": "jason", "audio\_mute": false, "video\_mute": false } ] }
## publish 영상 방송을 개시하고 방송 세션 id가 담긴 객체를 리턴받습니다. 사용자 지정 Tag ID를 전달하지 않으면 옴니톡 SDK에서 발급한 [Tag Rule](#audio-video-tag-rule)에 따른 Tag ID를 이용하시면 됩니다. 같은 룸의 다른 사용자가 join하거나 publish를 하게 되면 `CONNECTED_EVENT`를 받게 됩니다. 이는 각 사용자(peer)의 오디오가 연결되어 방송을 구독할 수 있는 상태가 되었음을 의미합니다. publish한 방송의 영상을 보고 싶은 사용자는 구독 [subscribe API](#subscribe)를 이용하면 됩니다. ```javascript const publishResult = await sdk.publish(tag_id); ```
ParemeterMandatoryTypeDescription
tag_idOStringVideo 입출력을 위한 사용자 지정 Tag ID
리턴 객체 예시 | publish { "session": "YjQ1ZGUzYzA3MmJhLTIz", }
## subscribe 구독할 방송의 세션 번호를 전달하면 해당 방송을 구독할 수 있습니다. tag id를 별도로 전달하지 않으면 옴니톡의 [Tag Rule](#audio-video-tag-rule)에 따른 id를 이용하시면 됩니다. subscribe 호출이 성공하면 자신의 세션, 구독하는 세션, 화면 공유 여부에 대한 boolean 값을 리턴 객체로 받게 됩니다. ```javascript const subscribeResult = await sdk.subscribe(publish_idx); ```
ParemeterMandatoryTypeDescription
publisherSessionMString
tag_idOString
리턴 객체 | subscribe { "session": "YjQ1ZGUzYzA3MmJhMTY4Nj", // 자신의 세션 "subscribe": "YzMyYWE1YTA3MmJhMTY4Njg" // 구독하는 상대의 세션 "screen": false // 화면 공유 여부에 대한 boolean 값
## unsubscribe 구독 중인 방송의 구독을 취소할 수 있습니다. ```javascript await sdk.unsubscribe(publisherSession); ``` | Parameter | Mandatory/Optional | Type | Description | | ---------------- | ------------------ | ------ | ----------- | | publisherSession | M | String | |
리턴 객체 | unsubscribe { "session": "YjQ1ZGUzYzA3MmJhMTY4Nj", // 자신의 세션 "subscribe": "YzMyYWE1YTA3MmJhMTY4Njg" // 구독취소한 세션 }
## screenShare 화면 공유 기능을 수행하기 위한 API입니다. tag id를 별도로 전달하지 않으면 옴니톡의 [Tag Rule](#audio-video-tag-rule)에 따른 id를 이용하시면 됩니다. screenShare 호출 성공시 화면 공유에 대한 session id가 담긴 리턴 객체를 받게 되며 동일 방의 다른 사용자들에게 `SCREEEN_SHARE_EVENT`가 전달됩니다. 공유 화면을 보고 싶은 사용자는 이벤트 메시지에서 전달하는 세션id를 구독하면 됩니다. (참고: [EVENT\_MESSAGE ](https://docs.omnitalk.io/commons/event-message#screen_share_event)) ```javascript await sdk.screenShare(tag_id); ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | --------------------------- | | tag\_id | O | String | Video 입출력을 위한 사용자 지정 Tag ID |
리턴 객체 | screenShare { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", }
## screenUnshare 자신의 화면 공유를 취소합니다. 동일 방의 다른 사용자들에게 `SCREEEN_UNSHARE_EVENT`가 전달됩니다. (참고: [EVENT\_MESSAGE ](https://docs.omnitalk.io/commons/event-message#screen_unshare_event)) ```javascript await sdk.screenShare(); ```
리턴 객체 | screenUnshare { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", }
## screenList 룸에서 화면을 공유하고 있는 방송이 있다면 그 방송에 대한 정보를 조회하는 API입니다. 별도의 room\_id를 전달하지 않으면 자신이 참여하고 있는 룸의 화면 공유 리스트를 조회하게 됩니다. ```javascript await sdk.screenList(); ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | ----------- | | room\_id | O | String | |
리턴 객체 | screenList { "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx", "room\_id": "9389314d3cb1b92eeaa81b618e0f", "count": 1, "page": 1, "list": \[ { "session": "YzMyYWE1YTA3MmJhMTY4", "user\_id": "sADKOqOGBA", "user\_name": "kAIaDnhpPH", "call\_type": "videocall" } ] }
## offerCall 음성 또는 영상 통화를 위한 발신 기능을 수행합니다. 첫 번째 파라미터인 call\_type이 음성 통화 요청인지, 영상 통화 요청인지 결정합니다. callee는 전화를 요청할 상대방의 user\_id를 전달해 주시면 됩니다. record 파라미터를 전달하지 않으면 default=false 입니다. 영상 통화의 경우 송출되는 영상을 재생하기 위해서는 video 태그가 필요합니다. Omnitalk SDK는 video 태그의 id를 기반으로 영상을 재생합니다. 파라미터로 사용자 지정 tag id를 전달할 수 있습니다. 사용자 지정 tag id를 전달하지 않으면 옴니톡 SDK에서 발급한 [Tag Rule](#audio-video-tag-rule)에 따라서 video 태그를 생성하시면 됩니다. 자신의 영상은 `Omnitalk-LocalVideo-0` 상대방 영상은 `Omnitalk-RemoteVideo-0` 입니다. offerCall 호출이 성공하면 callee에게는 `RINGING_EVENT`가 전달됩니다. offerCall을 호출한 측은 `RINGBACK_EVENT`를 받게 됩니다. (참고: [EVENT\_MESSAGE ](https://docs.omnitalk.io/commons/event-message)) ⚠️ 2.1.x 이후 버전부터 record 파라메터가 삭제되었습니다. 녹음은 [recordingStart](#recordingstart) 함수를 사용합니다. ```javascript await sdk.offerCall(call_type, callee, record); ``` | Parameter | Mandatory/Optional | Type | Description | | --------------- | ------------------ | ------- | -------------------- | | call\_type | M | String | | | callee | M | String | 이메일, 전화번호, 닉네임, id 등 | | record | O | Boolean | 2.1.x 버전부터 삭제 | | local\_tag\_id | O | String | | | remote\_tag\_id | O | String | |
이벤트 메시지 예시 | RINGBACK_EVENT { "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD", "caller": "alice", "callee": "bob", "call\_type": "audiocall" }
이벤트 메시지 예시 | RINGING_EVENT { "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD", "room\_id": "9389314d3cb1b92eeaa81b618e0f", "room\_type": "audiocall", "call\_type": "audiocall", "caller": "alice", "callee": "bob", "track": "audio", }
## answerCall 음성 또는 영상 통화를 위한 착신 기능을 수행합니다. answerCall 호출이 성공하면 caller, callee 양측 모두 `CONNECTED_EVENT`를 받습니다. ```javascript await sdk.answerCall(call_type, caller); ``` | Parameter | Mandatory/Optional | Type | Description | | --------------- | ------------------ | ------ | ----------- | | call\_type | O | String | | | caller | O | String | | | local\_tag\_id | O | String | | | remote\_tag\_id | O | String | | ## makeSipNumber 개인 또는 방송 룸에 일반 전화를 수신할 수 있는 번호를 부여합니다. 만약 룸에 번호를 할당하면 룸의 참여자 모두에게 전화를 걸 수 있습니다. ```javascript await sdk.makeSipNumber(); ``` | Parameter | Mandatory/Optional | Type | Description | | ------------ | ------------------ | ------ | ----------- | | call\_number | O | String | | | room\_id | O | String | | ## mute/unmute mute할 track을 인자로 넘겨주면 음소거 및 음소거 해제 기능을 수행할 수 있습니다. 비디오 mute는 로컬의 화면 송출을 off 시키는 기능입니다. mute/unmute API를 호출하면 룸의 다른 사용자들에게 `MUTE_EVENT` 또는 `UNMUTE_EVENT`가 전달됩니다. ```javascript await sdk.setMute(track); await sdk.setUnmute(track); ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | ---------------- | | track | M | String | "audio", "video" | ## getDeviceList 해당 장치의 모든 오디오, 비디오 장치를 조회할 수 있는 API 입니다. ```javascript await sdk.getDeviceList(); ```
리턴 객체 예시 | getDeviceList { "videoinput": \[\ { "kind":"videoinput", "label":"Logitech BRIO (046d:085e)", "deviceId": "33fb0bfdda06b8815f94baa46d3965\ 211b5476825021ac91578280a5d7c05b94", "groupId":"cbc0be3ca9648a43fa29e144e1460bb6\ df916243eea817625a4700b2cf910654 ", }, \ { "kind":"videoinput", "label":"FaceTime HD 카메라 (3A71:F4B5)", "deviceId": "9e82b7ecc5f2844f1109f31ac47b\ b1c5fc1d9d13d7f627e4f1db3fd0132bf9be", "groupId":"5ccd5bf9211dfd080cfcc6f8187f486c9a1\ 02e579a4d9e3f4e22cdfecb732cf7 ", }, ], \ "audioinput": \[\ { "kind":"audioinput", "label":"Logitech BRIO (046d:085e)", "deviceId": "5f9715786e17b339dfdfabfd65fc0a5b5\ 850ec11fc6509085c4a13b5fa760bef", "groupId":"2479fd4c965cadd52de1d9dd54debbcdb0\ caf370a2c0b916f13554d9eaec782d ", }, \ { "kind":"audioinput", "label":"MacBook Pro 마이크 (Built-in)", "deviceId": "1a825a6af6bb985db3dbcdedf67cfad\ 0d2b850f892a4dbd049fa01f140c2a972", "groupId":"dbec76dc0e283229718a34a2a07de4\ e98bb5987fb5db535affb6428c6b0f1339 ", }, ], }
## setAudioDevice 제어하고 싶은 장치의 device id를 인수로 전달하면 됩니다. ```jsx await sdk.setAudioDevice(device_id); ``` | Parameter | Mandatory/Optional | Type | Description | | ---------- | ------------------ | ------ | ----------- | | device\_id | M | String | | ## setVideoDevice 제어하고 싶은 장치의 device id를 인수로 전달하면 됩니다. ```jsx await sdk.setAudioDevice(device_id); ``` | Parameter | Mandatory/Optional | Type | Description | | ---------- | ------------------ | ------ | ----------- | | device\_id | M | String | | ## setResolution 송출할 비디오 영상의 해상도를 설정하는 API입니다. ```jsx await sdk.setResolution(resolution); ``` | resolution | width \* height | | ---------- | --------------- | | QVGA | 320 \* 240 | | VGA | 640 \* 480 | | SD | 720 \* 480 | | HD | 1280 \* 720 | | FHD | 1920 \* 1080 | | 2k | 2560 \* 1440 | | 4k | 1840 \* 2160 | ## destroyRoom 룸 삭제 기능을 수행하는 API 입니다. 룸에 어떤 참여자도 없으면 Omnitalk SDK에서 일정 시간 이후 자동으로 룸을 제거합니다. 만약 명시적으로 룸을 삭제하거나 추가 사용자의 룸 참여를 막고 싶다면 해당 room\_id를 전달하여 기능을 수행할 수 있습니다. 자신이 참여하고 있는 룸을 삭제할 수는 없습니다. 방송 중인 참여자가 있는 룸을 삭제하게 되면 방송 중인 참여자들은 계속 방송할 수 있고 룸 리스트 조회도 가능하지만 추가적인 룸 참여는 불가능합니다. ```javascript await sdk.destroyRoom(room_id); ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | ----------- | | room\_id | M | String | |
리턴 객체 | destroyRoom { "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD", "room\_id":"8a1086680e47261208eeff87000b", }
## leave 방송을 종료하는 API입니다. 통화 또는 회의에 참여한 상태일 경우, session을 전달하지 않으면 자신의 방송을 종료하고 퇴장(통화 종료)하게 됩니다. 퇴장시, 다른 참가자들은 LEAVE\_EVENT 를 수신 합니다. (참고: [EVENT\_MESSAGE ](https://docs.omnitalk.io/commons/event-message)) 파라미터에 session를 전달하면 해당 session을 가진 사용자가 퇴장(통화 종료) 하게 됩니다. 해당 상황은 수신 거절이나 강제 퇴장 등의 기능으로 활용할 수 있습니다. ⚠️ 2.1.x 이후 버전에서 leave는 본인의 퇴장만 가능합니다. 상대방의 강제 종료는 [kickout](#kickout)을 사용해 주세요. ```javascript await sdk.leave(); ``` | Parameter | Mandatory/Optional | Type | Description | | ----------- | ------------------ | ------ | ------------- | | session\_id | O | String | 2.1.x 버전부터 삭제 | *** {% hint style="info" %} **sdk 2.1.x 이후 버전부터 사용 가능** {% endhint %} ## kickOut 사용자가 룸에 참여해 방송을 개시한 이후에 다른 사용자를 강제퇴장 시키는 기능입니다. 인수로 전달하는 session은 룸에서 강제 퇴장되며 세션이 끊어지게 됩니다. 룸의 다른 참여자들에게는 KICKOUT\_EVENT가 발생합니다. ```javascript await sdk.kickOut(target) ``` | Parameter | Mandatory/Optional | Type | Description | | --------- | ------------------ | ------ | ------------------ | | target | M | string | 강제 종료할 상대의 session | ## recordingStart 음성 녹음을 시작하는 API입니다. 모든 call\_type에서 호출할 수 있습니다. 단, 녹음 시작 API 호출은 call/room에 참여한 사용자별로 한 번만 호출할 수 있습니다. recordingStop()을 호출하지 않고 leave()를 호출 하거나 연결이 끊어져도 해당 시점까지 녹음은 마무리됩니다. ```javascript await sdk.recordingStart(); ``` ## recordingStop 음성 녹음을 종료하는 API입니다. 녹음 완료 시 옴니톡 콘솔에 등록한 Webhook URL로 콜백을 받을 수 있습니다. ```javascript await sdk.recordingStop(); ```