API Reference

⚠️ SDK 2.0.x 버전과 2.1.x 이후 버전간 호환 불가

Synchronization

Omnitalk SDK는 통신 서비스를 제공하기 위해 Offer-Answer 구조로 설계되어 있으며, 이를 위해 반드시 async, await 비동기 처리를 지원해야 합니다.

Global Module

Omnitalk 객체를 생성합니다. 생성된 객체는 이후 모든 메서드 호출에 사용됩니다. Service Id와 Service Key는 console 페이지에서 발급 가능하며 노출되지 않도록 주의하여야 합니다.

import { Omnitalk } from "omnitalk-rn-sdk";

const SERVICE_ID = '발급받은 service id';
const SERVICE_KEY = '발급받은 service key';  // 앱

Omnitalk.sdkInit(SERVICE_ID, SERVICE_KEY);
const sdk = Omnitalk.getInstance();

EVENT_MESSAGE

on

이벤트 메시지는 여기를 참고하시면 됩니다. 이벤트 메시지를 수신하기 위해서는 옴니톡의 이벤트 리스너 API를 이용하시면 됩니다. (React-native는 screen share/unshare 기능을 제공하지 않습니다.)

sdk.on('event', ()=>{})

leave 이벤트로 서버와의 연결이 끊기거나 사용자 인터넷 환경 불안정 등으로 인터넷 연결이 끊길 때 발생하는 close 메시지입니다.

sdk.on('close', ()=>{})

createSession

사용자의 세션을 생성하기 위해 서버와 연결하고 그 결과로 세션 id, 유저 id가 담긴 객체를 리턴합니다. user_id 생략시 Omnitalk 서버에서 임의의 id를 부여합니다.

await sdk.createSession(user_id);

Parameter	Mandatory/Optional	Type	Description
user_id	O	String	max 64

리턴 객체 | createSession

{

"session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD",

"user_id":"omnitalk",

}

아래와 같은 상황에서는 에러가 발생합니다.

• SDK가 초기화 되지 않은 경우(sdkInit 호출 전)

• SDK 초기화 할 때 인자로 전달한 service id와 service key가 유효하지 않은 경우

• 이미 세션을 생성한 경우

• user_id가 64자를 초과하는 경우

• user_id가 string type이 아닌 경우

sessionList

세션 생성 후 같은 Service Id 및 Key를 사용하는 모든 사용자를 조회합니다.

await sdk.sessionList();

Parameter	Mandatory/Optional	Type	Description
page	O	Number	default = 1, per page = 10

리턴 객체 | sessionList

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",

"page": 1,

"count": 1,

"list": [

{ "user_id": "omnitalk",

"call_type": "videocall",

"state": "busy",

}

]

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• page가 number type이 아닌 경우

createRoom

모든 방송은 룸에서 이루어집니다. 방송을 시작할 룸 타입을 전달해 룸을 생성합니다. 방 주제나 방의 비밀 번호를 설정할 수 있습니다. start_date 및 end_date는 룸 생성 및 종료 예상 시간을 설정할 때 이용합니다.

await sdk.createRoom(room_type);

Parameter	Mandatory/Optional	Type	Description
room_type	M	DEFAULT_ROOM_TYPE	sdk 제공
subject	O	String	max 128
secret	O	Number	6 digits
start_date	O	Number	Date 객체
end_date	O	Number	Date 객체

리턴 객체 | createRoom

{

"session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD",

"room_id": "8a1086680e47261208eeff87000b"

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• subject가 128자를 초과하는 경우

• secret이 6자를 초과하는 경우

roomList

인수로 전달한 룸타입에 해당하는 모든 룸을 조회해 리스트로 반환합니다. default인 "all"은 룸타입에 관계없이 전체 룸을 조회합니다.

await sdk.roomList(room_type);

Parameter	Mandatory/Optional	Type	Description
room_type	O	ROOM_TYPE	sdk 제공, default= "all"
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

방송을 시작하거나 다른 방송을 시청하기 위해서는 반드시 룸 참여 과정이 필요합니다.

await sdk.joinRoom(room_id);

Parameter	Mandatory/Optional	Type	Description
room_id	M	String
secret	O	Number	6 digits
user_name	O	String	max 64, nickname

리턴 객체 | joinRoom

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",

"room_id": "8a1086680e47261208eeff87000b",

"room_type": "videoroom"

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• room_id가 32자를 초과하는 경우

• user_name이 64자를 초과하는 경우

• secret이 6자를 초과하는 경우

partiList

해당 룸에 참여한 모든 사용자(방송 개시 여부와 무관)를 조회합니다. room_id를 전달하지 않으면 자신이 참여한 룸의 참여자 리스트를 조회합니다.

await sdk.partiList(room_id);

Parameter	Mandatory/Optional	Type	Description
room_id	O	String	max 32
page	O	Number	default = 1, per page = 10

리턴 객체 | partiList

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",

"page": 1,

"count": 1,

"list":

[

{

"session": "YzMyYWE1YTA3MmJhMTY4",

"user_id": "[e-mail]",

"user_name": "jason",

"call_type": "videocall",

}

]

}

아래와 같은 상황에서는 에러가 발생합니다.

• 룸에 참가중이 아닌 경우

• room_id가 32자를 초과하는 경우

publish

영상 방송을 개시하고 방송 세션 id가 담긴 객체를 리턴받습니다. 영상 stream url을 담을 객체를 전달해야 합니다. 같은 룸의 다른 사용자가 join하거나 publish를 하게 되면 CONNECTED_EVENT를 받게 됩니다. 이는 각 사용자(peer)의 오디오가 연결되어 방송을 구독할 수 있는 상태가 되었음을 의미합니다. publish한 방송의 영상을 보고 싶은 사용자는 구독 subscribe API를 이용하면 됩니다.

await sdk.publish(local_renderer);

Parameter	Mandatory/Optional	Type	Description
local_renderer	M	RTCView	react-native-webrtc의 RTCView 타입의 객체

리턴 객체 | publish

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",

}

아래와 같은 상황에서는 에러가 발생합니다.

• 이미 영상 방송을 개시중인 상태

• 룸에 참가중이 아닌 경우

• 참가중인 룸 타입이 영상 방송을 지원하지 않는 경우 (VIDEO_ROOM 또는 WEBINAR가 아닌 경우)

publishList

참여한 룸에서 방송 중인 사용자 리스트를 조회합니다. room_id를 전달하지 않으면 자신이 참여한 룸의 참여자 리스트를 조회합니다.

await sdk.publishList();

Parameter	Mandatory/Optional	Type	Description
room_id	O	String
page	O	Number	default = 1, per page = 10

리턴 객체 | publishList

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",

"room_id": "9389314d3cb1b92eeaa81b618e0f",

"page": 1,

"count": 1,

"list":

[

{

"session": "YzMyYWE1YTA3MmJhMTY4",

"track": "video",

"audio_mute": false,

"video_mute": false,

"user_id": "sADKOqOGBA",

"user_name": "kAIaDnhpPH"

}

],

}

아래와 같은 상황에서는 에러가 발생합니다.

• 룸에 참가중이 아닌 경우

• 참가중인 룸 타입이 다자간 영상 회의 타입이 아닌 경우 (VIDEO_ROOM 또는 WEBINAR가 아닌 경우)

• room_id가 32자를 초과하는 경우

• room_id가 string type이 아닌 경우

• page가 number type이 아닌 경우

subscribe

구독할 방송의 세션 번호와 구독 영상의 stream url을 담을 객체를 전달하면 해당 방송을 구독할 수 있습니다. subscribe 호출이 성공하면 자신의 세션, 구독하는 세션, 화면 공유 여부에 대한 boolean 값을 리턴 객체로 받게 됩니다.

await sdk.subscribe(publisher_session, remote_renderer);

Parameter	Mandatory/Optional	Type	Description
publisher_session	M	String
remote_renderer	M	RTCView	react-native-webrtc의 RTCView 타입의 객체

리턴 객체 | subscribe

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Nj", // 자신의 세션

"subscribe": "YzMyYWE1YTA3MmJhMTY4Njg" // 구독하는 상대의 세션

"screen": false // 화면 공유 여부에 대한 boolean 값

}

아래와 같은 상황에서는 에러가 발생합니다.

• 룸에 참가중이 아닌 경우

• 참가중인 룸 타입이 다자간 영상 회의 타입이 아닌 경우 (VIDEO_ROOM 또는 WEBINAR가 아닌 경우)

• publisher_session를 전달하지 않은 경우

• publisher_session이 40자를 초과하는 경우

• 너무 많은 방송을 구독한 경우

  • 장치 사양과 해상도에 따라 차이가 있으나, 많은 영상을 구독하여 한번에 시청하는 경우 영상 끊김 현상이 발생할 수 있습니다.

unsubscribe

구독 중인 방송의 구독을 취소할 수 있습니다.

await sdk.unSubscribe(publisher_session);

Parameter	Mandatory/Optional	Type	Description
publisher_session	M	String

리턴 객체 | unsubscribe

{

"session": "YjQ1ZGUzYzA3MmJhMTY4Nj", // 자신의 세션

"subscribe": "YzMyYWE1YTA3MmJhMTY4Njg" // 구독취소한 세션

}

아래와 같은 상황에서는 에러가 발생합니다.

• 룸에 참가중이 아닌 경우

• publisher_session를 전달하지 않은 경우

• publisher_session이 40자를 초과하는 경우

• publisher_session이 현재 구독중인 세션이 아닌 경우

offerCall

음성 또는 영상 통화를 위한 발신 기능을 수행합니다. 음성 통화는 call_type과, 상대방 번호인 callee를 전달하고 영상 통화의 경우 caller 와 callee의 영상 stream url을 담을 객체를 전달해야 합니다. offerCall 호출이 성공하면 callee에게는 RINGING_EVENT가 전달됩니다. offerCall을 호출한 측은 RINGBACK_EVENT를 받게 됩니다. (참고: EVENT_MESSAGE )

await sdk.offerCall(call_type, callee);

Parameter	Mandatory/Optional	Type	Description
call_type	M	CALL_TYPE	sdk제공 ("audiocall" | "videocall")
callee	M	String	착신 상대방의 user_id
record	O	Boolean	audio call만 지원
local_renderer	*O	RTCView	react-native-webrtc의 RTCView 타입의 객체
remote_renderer	*O	RTCView	react-native-webrtc의 RTCView 타입의 객체

이벤트 메시지 예시 | 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",

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• call_type 또는 callee를 전달하지 않은 경우

• call_type이 전화 타입이 아닌 경우 (VIDEO_CALL 또는 AUDIO_CALL 또는 SIPCALL이 아닌 경우)

• callee가 32자를 초과하는 경우

• call_type이 VIDEO_CALL인데 local_renderer와 remote_renderer를 전달하지 않은 경우

answerCall

음성 또는 영상 통화를 위한 착신 기능을 수행합니다. 음성 통화의 경우 인수 전달없이 API호출만으로 통화 연결 가능합니다. 영상 통화의 경우 자신과 상대의 영상 stream url을 담을 객체를 전달해야 합니다. answerCall 호출이 성공하면 caller, callee 양측 모두 CONNECTED_EVENT를 받습니다.

await sdk.answerCall(call_type, caller); 

Parameter	Mandatory/Optional	Type	Description
call_type	O	CALL_TYPE	sdk제공("audiocall" | "videocall")
caller	O	String	착신 상대방의 user_id
record	O	Boolean	audio call만 지원
localRenderer	*O	RTCView	react-native-webrtc의 RTCView 타입의 객체. 영상 통화의 경우 필수
remoteRenderer	*O	RTCView	react-native-webrtc의 RTCView 타입의 객체. 영상 통화의 경우 필수

이벤트 메시지 예시 | CONNECTED_EVENT

{

"session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD"

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

RINGING_EVENT를 수신 했다면 인수 전달없이 API 호출만 하시면 통화 연결이 됩니다. 만약 RINGING_EVENT를 수신 하지 않은 상태에서 아래와 같은 상황에서는 에러가 발생합니다.

• call_type 또는 caller를 전달하지 않은 경우

• caller가 string type이 아닌 경우

• caller가 32자를 초과하는 경우

• call_type이 전화 타입이 아닌 경우 (VIDEO_CALL 또는 AUDIO_CALL 또는 SIPCALL이 아닌 경우)

• call_type이 VIDEO_CALL인데 local_renderer와 remote_renderer를 전달하지 않은 경우

makeSipNumber

개인 또는 방송 룸에 일반 전화를 수신할 수 있는 번호를 부여합니다. 만약 룸에 번호를 할당하면 룸의 참여자 모두에게 전화를 걸 수 있습니다.

await sdk.makeSipNumber();

Parameter	Mandatory/Optional	Type	Description
call_number	O	Number	6 digits
room_id	O	String

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• call_number가 string type이 아닌 경우

• room_id가 string type이 아닌 경우

mute/unmute

mute할 track을 인자로 넘겨주면 음소거 및 음소거 해제 기능을 수행할 수 있습니다. 비디오 mute는 로컬의 화면 송출을 off 시키는 기능입니다. mute/unmute API를 호출하면 룸의 다른 사용자들에게 MUTE_EVENT 또는 UNMUTE_EVENT가 전달됩니다.

await sdk.setMute(track);
await sdk.setUnmute(track);

Parameter	Mandatory/Optional	Type	Description
track	M	TRACK	sdk제공("audio"|"video")

sendMessage

채팅 기능 구현을 위한 메시지 전송 API입니다. 어떤 룸이든 입장하게 되면 기본적으로 채팅을 주고 받을 수 있는 상태가 됩니다. sendMessage API를 이용해 메시지는 발신하고, 옴니톡에서 전달하는 MESSAGE_EVENT로 메시지를 수신할 수 있습니다. 채팅 메시지는 룸의 모든 참여자에게 전송되며 특정 사용자에게 전달할 귓속말 메시지는 whisper action타입으로 보내면 됩니다.

Parameter	Mandatory/Optional	Type	Description
action	M	MESSAGE_ACTION	sdk제공(send | whisper)
message	M	String	max 2048
target	*O	String	귓속말 상대방 session id. whisper action의 경우 필수

이벤트 메시지 예시 | MESSAGE_EVENT

{

"action": "join",

"cmd": "MESSAGE_EVENT",

"session": "U0lTUlpocVhOUTE2ODg3MDcxNjQtMzgy",

"timestamp": 1688707215,

"user_id": "woo",

"user_name": "HJAhbndrmK"

}

아래와 같은 상황에서는 에러가 발생합니다.

• 룸에 참가중이 아닌 경우

• action이 WHISPER인데 target이 없는 경우

• message가 string type이 아닌 경우

• message의 길이가 너무 긴 경우

getAvailableMessageUsers

룸에서 채팅 가능한 사용자의 목록을 조회합니다.

await sdk.getAvailableMessageUsers();

Parameter	Mandatory/Optional	Type	Description
-	-	-	-

리턴 객체 | getAvailableMessageUsers

{

"session": "Smt1U29ncVRsSDE2ODg3MDcxMDctNTA0",

"count": 3,

"page": 1,

"list":

[

{

"call_type": "audiocall",

"session": "SHdyWlFMZEJ1VjE2ODg3MDc1MTYtNTA3",

"user_id": "222",

"user_name": "TydFCkYSBL"

},

{

"call_type": "audiocall",

"session": "SWxJZ2tGcldNeDE2ODg3MDc4NTYtNTEw",

"user_id": "333",

"user_name": "ErKMqhVSzb"

},

{

"call_type": "audiocall",

"session": "U0lTUlpocVhOUTE2ODg3MDcxNjQtMzgy",

"user_id": "woo",

"user_name": "HJAhbndrmK"

}

]

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

getDeviceList

해당 장치의 모든 오디오, 비디오 장치를 조회할 수 있는 API 입니다.

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를 인수로 전달하면 됩니다.

await setAudioDevice(device_id);

Parameter	Mandatory/Optional	Type	Description
device_id	M	String

switchVideoDevice

모바일 디바이스의 전/후면 카메라 switching 기능입니다.

await sdk.switchVideoDevice();

Parameter	Mandatory/Optional	Type	Description
-	-	-	-

destroyRoom

룸 삭제 기능을 수행하는 API 입니다. 룸에 어떤 참여자도 없으면 Omnitalk SDK에서 일정 시간 이후 자동으로 룸을 제거합니다. 만약 명시적으로 룸을 삭제하거나 추가 사용자의 룸 참여를 막고 싶다면 해당 room_id를 전달하여 기능을 수행할 수 있습니다. 자신이 참여하고 있는 룸을 삭제할 수는 없습니다. 방송 중인 참여자가 있는 룸을 삭제하게 되면 방송 중인 참여자들은 계속 방송할 수 있지만 추가적인 룸 참여는 불가능하며 룸 리스트에 조회되지 않습니다.

await sdk.destroyRoom(room_id);

Parameter	Mandatory/Optional	Type	Description
room_id	M	String

리턴 객체 | destroyRoom

{

"session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD",

"room_id":"8a1086680e47261208eeff87000b",

}

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• room_id가 string type이 아닌 경우

• room_id가 32자를 초과하는 경우

leave

자신의 방송을 종료하는 API입니다.

await sdk.leave();

Parameter	Mandatory/Optional	Type	Description
-	-	-

리턴 객체 | leave

{

"session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD",

}

아래와 같은 상황에서는 에러가 발생합니다.

• 이미 연결이 끊어졌거나 leave를 호출한 경우

kickOut

사용자가 룸에 참여해 방송을 개시한 이후에 다른 사용자를 강제퇴장 시키는 기능입니다. 인수로 전달하는 session은 룸에서 강제 퇴장되며 세션이 끊어지게 됩니다. 룸의 다른 참여자들에게는 KICKOUT_EVENT가 발생합니다.

await sdk.kickOut(target);

Parameter	Mandatory/Optional	Type	Description
target	M	String	강제종료 시킬 유저의 세션

아래와 같은 상황에서는 에러가 발생합니다.

• 세션을 생성하지 않은 경우

• 룸에 참가중이 아닌 경우

---

sdk 2.1.x 이후 버전부터 사용 가능

recordingStart

음성 녹음을 시작하는 API입니다. 모든 call_type에서 호출할 수 있습니다. 단, 녹음 시작 API 호출은 call/room에 참여한 사용자별로 한 번만 호출할 수 있습니다. recordingStop()을 호출하지 않고 leave()를 호출 하거나 연결이 끊어져도 해당 시점까지 녹음은 마무리됩니다.

await sdk.recordingStart();

recordingStop

음성 녹음을 종료하는 API입니다. 녹음 완료 시 옴니톡 콘솔에 등록한 Webhook URL로 콜백을 받을 수 있습니다.

await sdk.recordingStop();