API Reference

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

Synchronization

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

Global Module

Omnitalk SDK 객체를 생성합니다. Omnitalk SDK는 싱글톤 패턴으로 제공됩니다. 초기화된 객체는 이후 모든 메서드 호출에 사용됩니다. Service Id와 Service Key는 console 페이지에서 발급 가능하며 노출되지 않도록 주의하여야 합니다.

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

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

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

Parameter	Mandatory	Type	Description
service_id	M	String	발급받은 Service ID
service_key	O	String	APP 서비스인 경우 KEY 필수

Audio/Video Tag Rule

음성을 입출력하기 위한 Audio 태그는 옴니톡 SDK에서 자동으로 생성하며, Video 입출력을 위한 Tag ID는 아래의 규칙이 적용됩니다.

DOM	ID	Attribute	Use For	Creator
audio	Omnitalk-Audio-0	autoplay	-	SDK
video	Omnitalk-LocalVideo-0	autoplay, playinline	publish( ), offerCall(), answerCall()	Customer
video	Omnitalk-RemoteVideo-0 ... Omnitalk-RemoteVideo-31	autoplay, playinline	subscribe( ), offerCall(), answerCall()	Customer
video	Omnitalk-LocalScreen-0	autoplay, playinline	screenShare(), subscribe()	Customer

EVENT_MESSAGE

전체 이벤트 메시지 내용은 여기를 참고하시면 됩니다. 이벤트 메시지를 수신하기 위해서는 이벤트 리스너를 이용하시면 됩니다.

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

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

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

createSession

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

await sdk.createSession(user_id);

Parameter	Mandatory/Optional	Type	Description
user_id	O	String	* max 64

• 리턴 객체 | CreateSessionResult

{
  "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD", 
  "user_id":"omnitalk",
}

sessionList(deprecated)

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

await sdk.sessionList();

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

• 리턴 객체 | SessionListResult

{
  "page": 1,
  "count": 1,
  "list": [
    {
      "user_id": "omnitalk",
      "call_type": "videocall",
      "state": "busy",
    }
  ]
}

createRoom

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

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 객체

• 리턴 객체 | CreateRoomResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4NjcxMD",
  "room_id": "8a1086680e47261208eeff87000b"
}

roomList

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

await sdk.roomList(room_type);

Parameter	Mandatory/Optional	Type	Description
room_type	O	String	"all"(default)
page	O	Number	default = 1, per page = 10

• 리턴 객체 | RoomListResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4NjcxMD",
  "count": 1,
  "page": 1,
  "room_type": "all",
  "list": [
    {
      "room_id": "8a1086680e47261208eeff87000b",
      "room_type": "videoroom",
      "count": 0, // 해당 룸의 참여자 수
      "secret": true,
      "sip_support": true,
      "start_date": 1686816051,
      "end_date": 1686819651,
      "reg_date": 1686816051,
      "subject": "fish"
    }
  ]
}

joinRoom

영상 회의에서 방송을 시작하거나 다른 방송을 시청하기 위해서는 반드시 룸 참여 과정이 필요합니다. 회의실에 참여하게 되면 별도의 작업 없이 참여자들과 음성 회의를 할 수 있게 되며 회의실에 관련된 이벤트 메세지를 수신할 수 있습니다. 이벤트에 대한 자세한 내용은 Event Message 를 참조 바랍니다.

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

• 리턴 객체 | JoinRoomResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",
  "room_id": "8a1086680e47261208eeff87000b",
  "room_type": "videoroom",
  "screen": false // 참여한 룸의 화면 공유 여부
}

partiList

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

await sdk.partiList(room_id);

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

• 리턴 객체 | PartiListResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",
  "room_id": "8a1086680e47261208eeff87000b",
  "page": 1,
  "count": 1,
  "list": [
    {
      "session": "YzMyYWE1YTA3MmJhMTY4",
      "user_id": "[email protected]",
      "user_name": "jason",
      "audio_mute": false,
      "audio_mute": false
    }
  ]
}

publish

사용자의 영상을 송출합니다. 송출되는 영상을 재생하기 위해서는 video 태그가 필요합니다. Omnitalk SDK는 video 태그의 id를 기반으로 영상을 재생합니다. 파라미터로 사용자 지정 tag id를 전달할 수 있습니다. 사용자 지정 tag id를 전달하지 않으면 옴니톡 SDK에서 발급한 Tag Rule에 따라서 video 태그를 생성하시면 됩니다.

같은 룸의 다른 사용자가 publish를 하게 되면 BROADCASTING_EVENT 를 받게 됩니다. publish한 방송의 영상을 보고 싶은 사용자는 구독 subscribe API를 이용하면 됩니다.

await sdk.publish(tag_id);

Parameter	Mandatory/Optional	Type	Description
tag_id	O	String	Video 입출력을 위한 사용자 지정 Tag ID

• 리턴 객체 | PublishResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx"
}

publishList

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

await sdk.publishList();

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

• 리턴 객체 | PublishListResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Njcx",
  "room_id": "9389314d3cb1b92eeaa81b618e0f",
  "page": 1,
  "count": 1,
  "list": [
    {
      "session": "YzMyYWE1YTA3MmJhMTY4",
      "user_id": "sADKOqOGBA",
      "user_name": "kAIaDnhpPH",
      "call_type": "videocall"
    }
  ]
}

subscribe

구독할 방송의 session을 전달하면 해당 방송을 구독할 수 있습니다. 송출되는 영상을 재생하기 위해서는 video 태그가 필요합니다. Omnitalk SDK는 video 태그의 id를 기반으로 영상을 재생합니다. 파라미터로 사용자 지정 tag id를 전달할 수 있습니다. 사용자 지정 tag id를 전달하지 않으면 옴니톡 SDK에서 발급한 Tag Rule에 따라서 video 태그를 생성하시면 됩니다.

await sdk.subscribe(publisher_session);

Parameter	Mandatory/Optional	Type	Description
publisher_session	M	String
tag_id	O	String

• 리턴 객체 | SubscribeResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Nj", // 자신의 session
  "publisher_session": "YzMyYWE1YTA3MmJhMTY4Njg", // 송출자의 session
  "screen": false // 화면 공유 여부에 대한 boolean 값
}

unsubscribe

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

await sdk.unSubscribe(publisher_session);

Parameter	Mandatory/Optional	Type	Description
publisher_session	M	String

• 리턴 객체 | UnsubscribeResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Nj",
  "publisher_session": "YzMyYWE1YTA3MmJhMTY4Njg"
}

screenShare

화면 공유 기능을 수행하기 위한 API입니다. 화면 공유는 룸당 하나의 영상만 송출 가능합니다. 송출되는 영상을 재생하기 위해서는 video 태그가 필요합니다. Omnitalk SDK는 video 태그의 id를 기반으로 영상을 재생합니다. 파라미터로 사용자 지정 tag id를 전달할 수 있습니다. 사용자 지정 tag id를 전달하지 않으면 옴니톡 SDK에서 발급한 Tag Rule에 따라서 video 태그를 생성하시면 됩니다.

screenShare 호출 성공시 동일 방의 다른 사용자들에게 SCREEEN_SHARE_EVENT가 전달됩니다. 공유 화면을 보고 싶은 사용자는 이벤트 메시지에서 전달하는 session을 구독하면 됩니다. (참고: EVENT_MESSAGE )

await sdk.screenShare(tag_id);

Parameter	Mandatory/Optional	Type	Description
tag_id	O	String	Video 입출력을 위한 사용자 지정 Tag ID

• 리턴 객체 | ScreenShareResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Nj"
}

screenUnshare

자신의 화면 공유를 취소합니다. 동일 방의 다른 사용자들에게 SCREEEN_UNSHARE_EVENT가 전달됩니다. (참고: EVENT_MESSAGE )

await sdk.screenUnshare();

• 리턴 객체 | ScreenUnshareResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4Nj"
}

screenList

룸에서 화면을 공유하고 있는 방송이 있다면 그 방송에 대한 정보를 조회하는 API입니다. 별도의 room_id를 전달하지 않으면 자신이 참여하고 있는 룸의 화면 공유 정보를 조회하게 됩니다.

await sdk.screenList();

Parameter	Mandatory/Optional	Type	Description
room_id	O	String

• 리턴 객체 | ScreenListResult

{
  "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에 따라서 video 태그를 생성하시면 됩니다. 자신의 영상은 Omnitalk-LocalVideo-0 상대방 영상은 Omnitalk-RemoteVideo-0 입니다.

offerCall 호출이 성공하면 callee에게는 RINGING_EVENT가 전달됩니다. offerCall을 호출한 측은 RINGBACK_EVENT를 받게 됩니다. (참고: EVENT_MESSAGE )

⚠️ 2.1.x 이후 버전부터 record 파라메터가 삭제되었습니다. 녹음은 recordingStart 함수를 사용합니다.

await sdk.offerCall(call_type, callee);

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

answerCall

음성 또는 영상 통화를 위한 착신 기능을 수행합니다. answerCall 호출이 성공하면 caller, callee 양측 모두 CONNECTED_EVENT를 받습니다. (참고: EVENT_MESSAGE )

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

애플리케이션에서 일반 전화와 통화할 수 있는 번호를 발급 받습니다. 파라미터에 call_number를 전달하지 않으면 서버에서 임의의 6자리 번호를 발급합니다.

애플리케이션에서 call_number 발급 이후에 일반 전화로 옴니톡 070 번호로 전화를 걸고, 발급받은 6자리 call_number를 입력하면 일반 전화에서 애플리케이션으로 통화 요청이 이루어 집니다. 이 때, 애플리케이션에서는 RINGING_EVENT를 받게 됩니다. (참고: EVENT_MESSAGE ) 전화 수신을 위해서는 answerCall()를 호출하시면 됩니다.

await sdk.makeSipNumber();

Parameter	Mandatory/Optional	Type	Description
call_number	O	String
room_id	O	String

• 리턴 객체 | MakeSipNumberResult

{
  "call_number": "123456"
}

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	String	"audio", "video"

getDeviceList

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

await sdk.getDeviceList();

• 리턴 객체 | DeviceList

{
  "videoinput": [
    {
      "kind": "videoinput",
      "label": "Logitech BRIO (046d:085e)",
      "deviceId": "33fb0bfdda06b8815f94baa46d3965211b5476825021ac91578280a5d7c05b94",
      "groupId": "cbc0be3ca9648a43fa29e144e1460bb6df916243eea817625a4700b2cf910654"
    },
    {
      "kind": "videoinput",
      "label": "FaceTime HD 카메라 (3A71:F4B5)",
      "deviceId": "9e82b7ecc5f2844f1109f31ac47bb1c5fc1d9d13d7f627e4f1db3fd0132bf9be",
      "groupId": "5ccd5bf9211dfd080cfcc6f8187f486c9a102e579a4d9e3f4e22cdfecb732cf7"
    }
  ],
  "audioinput": [
    {
      "kind": "audioinput",
      "label": "Logitech BRIO (046d:085e)",
      "deviceId": "5f9715786e17b339dfdfabfd65fc0a5b5850ec11fc6509085c4a13b5fa760bef",
      "groupId": "2479fd4c965cadd52de1d9dd54debbcdb0caf370a2c0b916f13554d9eaec782d"
    },
    {
      "kind": "audioinput",
      "label": "MacBook Pro 마이크 (Built-in)",
      "deviceId": "1a825a6af6bb985db3dbcdedf67cfad0d2b850f892a4dbd049fa01f140c2a972",
      "groupId": "dbec76dc0e283229718a34a2a07de4e98bb5987fb5db535affb6428c6b0f1339"
    }
  ]
}

setAudioDevice

사용하고 싶은 마이크 장치의 device id를 인수로 전달하면 됩니다. device id는 getDeviceList() 에서 참조 바랍니다. 이미 통화 또는 회의에 참여 중일 때 호출할 경우, 송출되는 장치가 변경되어 송출 됩니다.

await sdk.setAudioDevice(device_id);

Parameter	Mandatory/Optional	Type	Description
device_id	M	String

setVideoDevice

사용하고 싶은 카메라 장치의 device id를 인수로 전달하면 됩니다. device id는 getDeviceList() 에서 참조 바랍니다. 이미 통화 또는 회의에 참여 중일 때 호출할 경우, 송출되는 장치가 변경되어 송출 됩니다.

await sdk.setVideoDevice(device_id);

Parameter	Mandatory/Optional	Type	Description
device_id	M	String

destroyRoom

룸 삭제 기능을 수행하는 API 입니다. 룸에 어떤 참여자도 없으면 Omnitalk SDK에서 일정 시간 이후 자동으로 룸을 제거합니다. 만약 명시적으로 룸을 삭제하거나 추가 사용자의 룸 참여를 막고 싶다면 room_id를 전달하여 기능을 수행할 수 있습니다.

자신이 참여하고 있는 룸을 삭제할 수는 없습니다. 방송 중인 참여자가 있는 룸을 삭제하게 되면 방송 중인 참여자들은 계속 방송할 수 있지만 추가적인 룸 참여는 불가능한 상태가 됩니다.

await sdk.destroyRoom(room_id);

Parameter	Mandatory/Optional	Type	Description
room_id	M	String

• 리턴 객체 | DestroyRoomResult

1
  "session":"YjQ1ZGUzYzA3MmJhMTY4NjcxMD",
  "room_id":"8a1086680e47261208eeff87000b"
}

leave

방송을 종료하는 API입니다. 통화 또는 회의에 참여한 상태일 경우, session을 전달하지 않으면 자신의 방송을 종료하고 퇴장(통화 종료)하게 됩니다. 퇴장시, 다른 참가자들은 LEAVE_EVENT 를 수신 합니다. (참고: EVENT_MESSAGE )

파라미터에 session를 전달하면 해당 session을 가진 사용자가 퇴장(통화 종료) 하게 됩니다. 해당 상황은 수신 거절이나 강제 퇴장 등의 기능으로 활용할 수 있습니다.

⚠️ 2.1.x 이후 버전에서 leave는 본인의 퇴장만 가능합니다. 상대방의 강제 종료는 kickout을 사용해 주세요.

await sdk.leave();

Parameter	Mandatory/Optional	Type	Description
session_id	O	String	2.1.x 버전부터 삭제

sendMessage

채팅 기능을 사용할 수 있는 API 입니다. 같은방에 참여한 사용자들에게는 MESSAGE_EVENT 이벤트가 발생합니다. (참고: EVENT_MESSAGE )

await sdk.sendMessage(message);

Parameter	Mandatory/Optional	Type	Description
message	M	String	max length 2048

sendWhisper

귓속말 기능을 사용할 수 있는 API 입니다. target에 다른 참여자 session을 전달 해야하며, 해당 session을 가진 참여자 에게만 MESSAGE_EVENT 이벤트가 발생합니다. (참고: EVENT_MESSAGE )

await sdk.sendWhisper(message, target);

Parameter	Mandatory/Optional	Type	Description
message	M	String
target	M	String	귓속말을 보낼 상대의 session

messageList

입장한 방의 채팅 참여자 목록을 조회하고 MessageListResult 객체를 리턴합니다.

await sdk.messageList();

• 리턴 객체 | MessageListResult

{
  "session": "YjQ1ZGUzYzA3MmJhMTY4NjcxMD",
  "count": 1,
  "page": 1,
  "list": [
    {
      "call_type": "audiocall",
      "session": "Z1RWVnJRZGp1YTE2ODk3MzU1NzMtMTE3",
      "user_id": "gKodyLVKll",
      "user_name": "pVtOlFfxfO"
    }
  ]
}

---

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

kickOut

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

await sdk.kickOut(target)

Parameter	Mandatory/Optional	Type	Description
target	M	string	강제 종료할 상대의 session

recordingStart

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

await sdk.recordingStart();

recordingStop

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

await sdk.recordingStop();