BUZZ Signalling API

Introduction

There are two different channels of communication related to calls and conferences. The first is for signaling (transported over WebSocket), and the second is for the audio, video, and screenshare (transported over RTP).

This section is a reference for the signaling part including the negotiation of the session.

Point-to-Point vs. Conference

A direct call between two subscribers uses SIP (Session Initiation Protocol) for signaling. The media then usually flows over the RTP (Real-Time Protocol) channel without involving the BUZZ server.

Signalling point-to-point network diagram

Conversely, when two or more subscribers join a conference, the signaling used is a separate BUZZ-specific protocol. Once connected, the media is mixed by the BUZZ server.

Signalling conference network diagram

A conference is always attached to a room. But a direct call is not.

In the following section, you will learn about point-to-point calls. Since this is using a standard protocol, you will be referred to external resources if you need to learn more. The subsequent sections will discuss the conference signaling APIs.

Transferring Media with RTP

RTP is a standard protocol to transmit real-time data such as audio and video. It is widely used and accepts many different codecs.

As a programmer, you should not have to implement SDP or RTP as there are lots of RTP libraries (AKA RTP stacks) that will take care of that, with little effort on your part. In the next section, you will learn about libraries that provide both RTP and SIP support.

Working with RTP is fairly low level and involves receiving data from video cameras, microphones, and other devices, encoding the data, and streaming it to and endpoint. Also receiving the streamed data, decoding it, and displaying or playing the media.

RTP negotiation is done with SDP (Session Description Protocol) documents, which explain the stream connection information and codecs used for the session. The transport is done over UDP.

If you wish to learn more about their inner-workings, there are lots of online resources to learn SDP and RTP. For example:

Point-to-Point Signalling with SIP

SIP is a standard protocol for telephony. It’s a robust and extensible protocol that’s been around for a long time.

If you need to implement point-to-point signaling, you do not need to start from scratch. There are many excellent SIP libraries (AKA SIP stacks) in a number of languages that will make it easier to implement your BUZZ client. These libraries typically also provide SDP and RTP services, so if you use one of them, you may not need a separate RTP library.

It would be redundant to explain SIP in detail here since you can find countless websites that thoroughly explain all you need to know. For example:

UDP vs. WebSocket Transport

The SIP protocol can be transported over any lower-level protocol. Two choices are possible:

  • UDP
  • WebSocket

SIP Connection Information

During the login, there are many fields being returned by the /api/SubscriberSecurityLogin endpoint. Here are the ones you need in order to register to the BUZZ SIP Registrar:

{ 
   ... truncated irrelevant fields ...
   "username":"{username}",
   "sipPwd":"{password}",
   "sipdomain":"{domain}",
   "sipOutboundProxy":"{sip-proxy–and-port}",
   "webrtcSipProxy":"{websocket-proxy}"
}

where:

  • {username} and {password} are used for digest authentication. The {username} is also used as part of the SIP addresses, e.g. in the From and To fields
  • {domain} is the domain to use in the SIP addresses as well as the realm and uri fields of the Proxy-Authorization header.
  • {sip-proxy–and-port} is used for UDP transport as the proxy
  • {websocket-proxy} is used for the WebSocket transport as the connection URL

Conference Signaling

The rest of this document will cover conference sessions involving two or more subscribers/devices in a room.

Subscriber vs. Device

A subscriber represents a person. It is identified by an unchanging username. The BUZZ conference server acts as a virtual subscriber with the username “buzzconf“. A device represents an instance of BUZZ running on a subscriber’s device. It is represented by a device ID (UUID), generated every time you register the device. A single subscriber can own multiple devices. The BUZZ conference server also has an ID generated at registration time.

The conference signaling protocol is made up of messages sent between a pair of peers: a source and a destination. Before the connection is established, the peers are identified with:

  • {username}” for a subscriber
  • buzzconf” for the BUZZ conference server

After the connection is established, the peer is identified by a tuple:

  • {username}:{deviceID}” for a subscriber/device
  • buzzconf:{serverID}” for the BUZZ conference server

Signalling lifecycle diagramSession Lifecycle

A session is a lasting connection between a subscriber’s device and the BUZZ RTC Server, which represents an audio or video call, or a screen share, within a conference. A session has a state, which represents its current status.

Before the session even exists, the device must be registered. Then an offer must be received. For example, an incoming call. This creates a session in the “new” state.

New: This offer can then be answered (the session state is changed to “connecting”) or rejected (state becomes “completed”). Answering the offer means that the RTP media is negotiated.

Connecting: This indicates that the new connection has been accepted, but the RTP channel hasn’t yet started. After this channel is started, the session goes to the “connected” state. If the channel fails to open (canceled), the session goes to the “completed” state.

Connected: Indicates the connection is now open. The session stays in this state until the subscriber hangs up (bye) and then it changes to the “completed” state. Sometimes the connection’s RTP media needs to be re-negotiated (re-offer). When that’s the case, the session goes back to the “new” state to begin the negotiation again.

Completed: The session has ended.

Registration

Request

You should register with the BUZZ server at all times even if the end-user is not yet connected to a conference. To register, simply connect to a WebSocket using a URL as follows:

wss://{server}?token={token}&userid={username}&deviceid={deviceID}

where:

  • wss is the Secure WebSocket protocol
  • {server} is the domain and port of the BUZZ RTC server retrieved from the subscriberSecurityLogin API in the buzzRtcServer field
  • {token} is your authentication token retrieved from the subscriberSecurityLogin API in the bearerToken field
  • {username} is the subscriber’s identifier retrieved from the subscriberSecurityLogin API in the username field
  • {deviceID} is a UUID identifier for this device, generated at the time of the registration

There is no request body for this kind of connection.

Response

The successful response will come inside the WebSocket channel with the following format:

{
        dest: "{deviceID}",
        origin: "server",
        data: {
             type: "registered" 
       }
}

where:

  • {deviceID} is the device’s unique identifier that you generated in the connection URL

A failed response will not return any data. Instead, the WebSocket will be closed with error code 4003 (unauthorized), indicating that your user ID or token is not valid.

offer

An offer is a session connection proposal. It is sent from a subscriber’s device and then it is forwarded to a conference. In case the session is already connected, an offer is a change in an existing session data.

Format

The offer message has the following format:

{
    "dest": "buzzconf",
    "data": {
        "type": "offer",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "sdp": "{sdp}",
            "user": "{sender-username}",
            "displayName": "{sender-name}",
            "isPersonalConference": {personnal},
            "lobbyEnabled": {lobby},
            "mediaServerRegion": "{region}",
            "roomId": "{roomID}",
            "mediaType": "{media}",
            "audio": "{audioDirection}",
            "video": "{videoDirection}",
            "owner": {is-owner},
            "ownerId": {ownerID},
            "subId": {sender-subscriberID},
            "confId": "{conferenceID}",
            "companyId": {companyID},
            "simulcast": {simulcast},
            "userInfo": {
                "dnis": "{DNIS}",
                "ani": "{ANI}",
                "turnData": "{turnData}",
                "emailAddress": "{email}",
                "serviceIdentifier": "{service}"
            }
        }
    }
}

where:

  • {sessionID} is a generated UUID that identifies the session
  • {sdp} is the Session Description Protocol payload, describing the streaming communication media that are acceptable by the sender of this offer
  • {sender-username} is the subscriber’s username of the sender of this offer
  • {sender-name} is the name of the sender as it will appear to the receiver
  • {media} can be either audio, audiovideo, video, or screenshare
  • {audioDirection} the direction of the audio stream; see below
  • {videoDirection} the direction of the audio stream; see below
  • {personal} is true if this is a conference in the subscriber’s own personal conference room, otherwise false
  • {lobby} is true if this conference has a lobby, otherwise false
  • {region} is the region of the conference server (leave empty if unsure)
  • {roomID} is the unique identifier for this conference room
  • {is-owner} is true if the conference is owned by the message sender, otherwise false
  • {conferenceID} is the identifier of this conference, which is obtained by calling api/BuzzRoomId2ConferenceId?roomId={roomID} in the conferenceId field
  • {companyID} is the company identifier of the message sender
  • {DNIS} is the ???
  • {ANI} is the ???
  • {turnData} is the ???
  • {email} is the ???
  • {service} is the ???

There are 4 different “directions” for an audio or video stream:

  • inactive: The audio stream is stopped in both directions
  • sendonly: The audio stream goes from the source to the destination, but not the other way around. In effect, the sender of this offer cannot hear or see the receiver, but the receiver can
  • recvonly: The audio stream goes from the destination to the source, but not the other way around. In effect, the receiver of this offer cannot hear or see the sender, but the sender can. This is the normal behaviour when the sender presses the “mute” button
  • sendrecv: The audio stream goes from the source to the destination and vice versa

Responses

There are two possible responses to an offer:

  • answer
  • reject

answer

An answer is an affirmative response to an offer. This means the BUZZ server decided to accept a call. The SDP payload will contain the media that is acceptable by both the offer sender and the server.

Format

An answer has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "origin": "buzzconf:{serverID}",
    "data": {
        "type": "answer",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "sdp": "{sdp}"
        }
    }
}

where

  • {dest-username} is the subscriber’s username
  • {deviceID} is the identifier of the device
  • {serverID} is the identifier of the server (only during this session)
  • {sessionID} is a generated UUID that identifies the session
  • {sdp} is the Session Description Protocol payload, describing the streaming communication media that are acceptable by both peers of this call

Responses

There are two possible responses to an answer:

  • device-answered
  • cancel

reject

An answer is a negative response to an offer. This means the BUZZ server decided to reject a call.

Format

A reject has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "origin": "buzzconf:{serverID}",
    "data": {
        "type": "reject",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": "{message}"
    }
}

where

  • {dest-username} is the subscriber’s username
  • {deviceID} is the identifier of the device
  • {serverID} is the identifier of the server (only during this session
  • {sessionID} is a generated UUID that identifies the session
  • {message} is the human-readable reason for rejecting this call

Responses

No response is possible. The session doesn’t exist anymore.

device-answered

A device-answered is a confirmation from the device that the RTP stream is open.

Format

An answer has the following format:

{
    "dest": "buzzconf",
    "data": {
        "type": "device-answered",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "deviceId": "buzzconf:{serverID}"
        }
    }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)

Responses

After this, the session is fully started. No responses are expected. The subscriber may want to modify the session using any of the session management messages. He may also receive event messages.

cancel

This message indicates that the media streams failed to connect. At this point, the RTP streams are closed and the call ends.

Format

A cancel has the following format:

    "dest": "buzzconf",
    "data": {
        "type": "cancel",
        "sessionId": "{sessionID}",
        "category": "conf"
    }
}

where

  • {sessionID} is a generated UUID that identifies the session

Responses

No response is possible. The session doesn’t exist anymore.

bye

This message indicates that a subscriber wants to end a session or was kicked out of the conference. At this point, the RTP streams are closed and the session ends.

Format

A bye has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "data": {
        "type": "bye",
        "sessionId": "{sessionID}",
        "category": "conf"
    }
}

where

  • {dest-username} is the destination. If the subscriber is kicked out of a conference, this is buzzconf instead
  • {deviceID} is the identifier of the deviceIf the subscriber is kicked out of a conference, this is the server’s ID instead
  • {sessionID} is a generated UUID that identifies the session

Responses

No response is possible. The session doesn’t exist anymore.

conf-update

A conf-updated message is an indication that something has changed in a conference. For example, a subcriber has joined or left the conference, or the conference is muted.

Format

An answer has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "origin": "buzzconf:{serverID}",
    "data": {
        "type": "message",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "type": "conf-update",
            "roomId": "{roomID}",
            "members": [
              { 
                "category":"conf",
                "sessionId":"{sessionID}",
                "user":"{dest-username}",
                "displayName":"{name}",
                "mute":{audio-muted},
                "videomute":{video-muted},
                "roomId":"{roomID}",
                "mediaType":"{media}",
                "audio":"{direction}",
                "video":"{direction}",
                "joinTime":{timestamp},
                "talker":{is-talker},
                "owner":{is-owner},
                "callId":"{internal}",
                "callUrl":"{internal}",
                "confId":"{internal}",
                "subId":{internal},
                "tracks":{internal},
                "simulcast":{internal},
                "id":"{internal}",
                "pending":{internal}
              }
            ]
        }
    }
}

where

  • {dest-username} is the subscriber’s username
  • {deviceID} is the identifier of the device
  • {serverID} is the identifier of the server (only during this session)
  • {sessionID} is a generated UUID that identifies the session
  • {name} is the name of the subscriber as it should be displayed on the screen
  • {roomID} is the unique identifier for this conference room
  • {audio-muted} is true if this subscriber’s audio stream is currently muted, otherwise false
  • {video-muted} is true if this subscriber’s video stream is currently muted, otherwise false
  • {media} can be either audio, audiovideo, video, or screenshare
  • {audioDirection} the direction of the audio stream; see below
  • {videoDirection} the direction of the audio stream; see below
  • {timestamp} is the time (in Unix time milliseconds) at which this subscriber joined the conference
  • {is-talker} is true if this subscriber is currently the active speaker, otherwise false. The BUZZ client application can display the active talker. It should switch automatically to the subscriber who’s currently speaking. And it knows this information this field
  • {is-owner} is true if the conference is owned by the message sender, otherwise false
  • {internal} are for fields that are not relevant

There are 4 different “directions” for an audio or video stream:

  • inactive: The audio stream is stopped in both directions
  • sendonly: The audio stream goes from the source to the destination, but not the other way around. In effect, the sender of this offer cannot hear or see the receiver, but the receiver can
  • recvonly: The audio stream goes from the destination to the source, but not the other way around. In effect, the receiver of this offer cannot hear or see the sender, but the sender can. This is the normal behaviour when the sender presses the “mute” button
  • sendrecv: The audio stream goes from the source to the destination and vice versa

Responses

No response is expected from this.

Notes

.

Conference Session Management

The subscriber has a certain control over conferences. He can, for example, invite and kick out members, mute himself or others, and even add people that are not even subscribers (via a phone number). This section lists messages that can execute those actions.

Keepalive

During a conference, peers of the conference must send “heartbeat” messages to the server to signify that they are still connected. In return, the conference server will acknowledge that it received those messages which signifies the server is still available. This has to be done in less than 10 seconds in-between the heartbeats otherwise the peer is considered disconnected.

  • keepalive
  • keepalive-ack

Conference Control

These are general commands that let you change conference details, invite subscribers into a conference, kick and mute members.

  • conf-view
  • self-mute
  • self-videomute
  • update-party
  • conf-member-mute
  • conf-member-remove

Ad Hoc Invitation Lifecycle

An “ad hoc” invitation is an invitation to a person, either a subscriber, or someone else by specifying a phone number or email address. You can invite them to join a room (IM invitation), or you can invite them to both the room and the conference (audio invitation, or video invitation).

On top of the session lifecycle seen previously, a separate lifecycle exists for ad hoc invitations. The same states exist for these ad hoc invitations.

  • adhoc-invite
  • adhoc-accept
  • adhoc-reject
  • adhoc-device-accept
  • adhoc-device-reject

Now that you’ve seen an overview of the various messages, let’s explore each message individually.

keepalive

A keepalive message indicates that a device is still part of the conference.

Format

A keepalive has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "data": {
        "type": "keepalive",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "deviceId": "{dest-username}:{deviceID}"
        }
    }
}

where

  • {dest-username} is the username of the destination subscriber. If the destination is the BUZZ conference server, this is buzzconf instead
  • {deviceID} is the identifier of the device. If the destination is the BUZZ conference server, this is the server’s ID instead
  • {sessionID} is a generated UUID that identifies the session

Responses

  • keepalive-ack

keepalive-ack

The keepalive-ack message indicates that a keepalive message was received.

Format

A keepalive-ack has the following format:

{
    "dest": "{dest-username}:{deviceID}",
    "data": {
        "type": "keepalive-ack",
        "sessionId": "{sessionID}",
        "category": "conf",
        "data": {
            "deviceId": "{dest-username}:{deviceID}"
        }
    }
}

where

  • {dest-username} is the username of the destination subscriber. If the destination is the BUZZ conference server, this is buzzconf instead
  • {deviceID} is the identifier of the device. If the destination is the BUZZ conference server, this is the server’s ID instead
  • {origin-username} is the username of the origin subscriber. If the origin is the BUZZ conference server, this is buzzconf instead
  • {origin-deviceID} is the identifier of the device. If the origin is the BUZZ conference server, this is the server’s ID instead
  • {sessionID} is a generated UUID that identifies the session
  • {deviceID} is the identifier of the device

Responses

No responses are expected.

conf-view

The BUZZ client application can display the active talker. It should switch automatically to the subscriber who’s currently speaking. And it knows this information because of the conf-update message, under data > data > members > a single member > talker field. But sometimes the subscriber would prefer to look at a single subscriber without switching automatically to the active talker.

A conf-view message indicates that a subscriber wants to look at another subscriber in the same conference. At this point, the focus is on this subscriber, even if another subscriber is the active talker. At this point, the stream will display the correct subscriber.

Format

A conf-view has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
         "type": "conf-view",
         "sessionId": "{other-subscriber's-sessionID}"
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {other-subscriber's-sessionID} is the session identifier of the subscriber that was selected for viewing. This data is located in the list of members of the conference. E.g. in the conf-update message, under data > data > members > a single member > sessionId. To switch back to the active talker, use the ID “vas” which stands for “view active speaker”.

Responses

No response is sent after this, but the stream now shows the selected subscriber.

self-mute

A self-mute message indicates that a subscriber wants to turn off the audio media coming from his microphone.

Format

A self-mute has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
        "type": "self-mute",
        "sessionIds":[
          "{sessionID}"
        ],
        "mute":{muted}
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {muted} is true if the user is muting himself, false if he’s un-muting himself

Responses

After this, all conference members including the one who just muted himself will receive a conf-update message to indicate this change.

self-videomute

A self-videomute message indicates that a subscriber wants to turn off the video media coming from his video camera.

Format

A self-videomute has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
        "type": "self-videomute",
        "sessionIds":[
          "{sessionID}"
        ],
        "mute":{muted}
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {muted} is true if the user is muting himself, false if he’s un-muting himself
  • {internal} are for fields that are not relevant

Responses

After this, all conference members including the one who just muted himself will receive a conf-update message to indicate this change.

update-party

 

 

conf-mute-all

A conf-mute-all message is used to mute or unmute all the members of the conference. A subscriber can only send this message if they are the owner of the conference.

Format

A conf-mute-all has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
        "type": "conf-mute-all",
        "mute":{audio-muted},
        "video":{video-muted}
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {audio-muted} is true if this subscribers’ audio stream must be muted, otherwise false
  • {video-muted} is true if this subscribers’ video stream must be muted, otherwise false

Responses

After this, all conference members including the one who just muted the conference will receive a conf-update message to indicate this change.

conf-member-mute

A conf-member-mute message is used to mute or unmute a specific member of the conference. A subscriber can only send this message if they are the owner of the conference.

Format

A conf-member-mute has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
        "type": "conf-member-mute",
        "mute":{audio-muted},
        "video":{video-muted},
        "sessionId": "{other-subscriber's-sessionID}"
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {audio-muted} is true if this subscriber’s audio stream must be muted, otherwise false
  • {video-muted} is true if this subscriber’s video stream must be muted, otherwise false
  • {other-subscriber's-sessionID} is the session identifier of the subscriber to mute. This data is located in the list of members of the conference. E.g. in the conf-update message, under data > data > members > a single member > sessionId.

Responses

After this, all conference members including the one who was just muted will receive a conf-update message to indicate this change.

conf-member-remove

A conf-member-remove message is used to kick a specific member out of the conference. A subscriber can only send this message if they are the owner of the conference.

Format

A conf-member-remove has the following format:

{ 
   "dest":"buzzconf:{serverID}",
   "data":{ 
      "type":"message",
      "category":"conf",
      "sessionId":"{sessionID}",
      "data":{
        "type": "conf-member-mute",
        "sessionId": "{other-subscriber's-sessionID}"
      }
   }
}

where

  • {sessionID} is a generated UUID that identifies the session
  • {serverID} is the identifier of the server (only during this session)
  • {other-subscriber's-sessionID} is the session identifier of the subscriber to kick out. This data is located in the list of members of the conference. E.g. in the conf-update message, under data > data > members > a single member > sessionId.

Responses

After this, the conference member who was kicked out will receive a bye message. All other conference members will receive a conf-update message to indicate this change.

adhoc-invite

An adhoc-invite message will add someone to a conference. This person can be an existing subscriber (BUZZ user), or you can invite non-subscribers via email or by calling a phone number (PSTN).

Format

An adhoc-invite has the following format:

{ 
   "dest":"buzzconfpstn",
   "data":{ 
      "type":"adhoc-invite",
      "category":"adhoc",
      "data":{ 
         "from":"{sender-username}",
         "name":"{sender-name}",
         "roomId":"{roomID}",
         "type":"call",
         "adHocCallType":"audio",
         "isScheduledRoom":{is-scheduled},
         "confid":"{conferenceID}",
         "outbound":"{dest-phone-number}",
         "uid":"{inviteID}"
      }
   }
}

where

  • {sender-username} is the subscriber’s username of the sender of this invite
  • {sender-name} is the name of the sender as it will appear to the receiver
  • {roomID} is the unique identifier for this conference room
  • {conferenceID} is the identifier of this conference, which is obtained by calling api/BuzzRoomId2ConferenceId?roomId={roomID} in the conferenceId field
  • {dest-phone-number} is the phone number of the person you’re inviting
  • {is-scheduled} is true if this conference is scheduled, false otherwise
  • {inviteID} A generated invitation identifier, GUID format

Responses

  • adhoc-accept if the invited person accepted the invitation and asks to join the call
  • adhoc-reject if the invited person refused the invitation

adhoc-accept

An adhoc-accept is an affirmative response to an offer. This means the invited person accepted a call.

Format

An adhoc-accept has the following format:

{ 
   "dest": "{dest-username}:{deviceID}",
   "origin": "buzzconfpstn:{invitedID}",
   "data":{ 
      "category":"adhoc",
      "type":"adhoc-accept",
      "data":{ 
         "from":"buzzconfpstn",
         "roomId":"{roomID}",
         "to":"{sender-username}",
         "data":{ 
            "adHocCallType":"audio",
            "confid":"{conferenceID}",
            "from":"{sender-username}",
            "isScheduledRoom":{is-scheduled},
            "name":"{sender-name}",
            "outbound":"{dest-phone-number}",
            "roomId":"{roomID}",
            "type":"call",
            "uid":"{inviteID}"
         }
      }
   }
}

where

  • {dest-username} is the subscriber’s username
  • {deviceID} is the identifier of the device
  • {invitedID} is the identifier of the invited person (only during this session)
  • {sender-username} is the subscriber’s username of the sender of this invite
  • {sender-name} is the name of the sender as it will appear to the receiver
  • {is-scheduled} is true if this conference is scheduled, false otherwise
  • {roomID} is the unique identifier for this conference room
  • {conferenceID} is the identifier of this conference, which is obtained by calling api/BuzzRoomId2ConferenceId?roomId={roomID} in the conferenceId field
  • {dest-phone-number} is the phone number of the person you’re inviting
  • {inviteID} A generated invitation identifier, GUID format

Responses

There are two possible responses to an answer:

  • adhoc-device-accept if the media stream is established
  • adhoc-device-reject if the media stream failed

adhoc-reject

An adhoc-reject is a negative response to an offer. This means the invited person refused a call.

Format

An answer has the following format:

{ 
   "dest": "{dest-username}:{deviceID}",
   "origin": "buzzconfpstn:{invitedID}",
   "data":{ 
      "category":"adhoc",
      "type":"adhoc-reject",
      "data":{ 
         "from":"buzzconfpstn",
         "roomId":"{roomID}",
         "to":"{sender-username}",
         "data":{ 
            "adHocCallType":"{invitation-type}",
            "confid":"{conferenceID}",
            "from":"{sender-username}",
            "isScheduledRoom":{is-scheduled},
            "name":"{sender-name}",
            "outbound":"{dest-phone-number}",
            "roomId":"{roomID}",
            "type":"call",
            "uid":"{inviteID}"
         },
      }
   }
}

where

  • {invitation-type} is the kind of invitation, either audio, video, or IM. The latter will add the invited person to the room but not the conference
  • {dest-username} is the subscriber’s username
  • {deviceID} is the identifier of the device
  • {invitedID} is the identifier of the invited person (only during this session)
  • {roomID} is the unique identifier for this conference room
  • {sender-username} is the subscriber’s username of the sender of this invite
  • {is-scheduled} is true if this conference is scheduled, false otherwise
  • {sender-name} is the name of the sender as it will appear to the receiver
  • {conferenceID} is the identifier of this conference, which is obtained by calling api/BuzzRoomId2ConferenceId?roomId={roomID} in the conferenceId field
  • {dest-phone-number} is the phone number of the person you’re inviting
  • {inviteID} A generated invitation identifier, GUID format

Responses

After this, the session is aborted. No responses are expected.

adhoc-device-accept

An adhoc-device-accept is a confirmation that the invitation should be completed.

Format

An adhoc-device-accept has the following format:

{ 
   "dest":"buzzconfpstn",
   "data":{ 
      "type":"adhoc-device-accept",
      "category":"adhoc",
      "data":{ 
         "device": "buzzconfpstn:{invitedID}",
         "from":"buzzconfpstn",
         "roomId":"{roomID}"
      }
   }
}

where

  • {roomID} is the unique identifier for this conference room
  • {invitedID} is the identifier of the invited person (only during this session)

Responses

After this, the session is fully started. No responses are expected.

adhoc-device-reject

An adhoc-device-reject indicates that the invitation should be cancelled.

Format

An adhoc-device-reject has the following format:

{ 
   "dest":"buzzconfpstn",
   "data":{ 
      "type":"adhoc-device-reject",
      "category":"adhoc",
      "data":{ 
         "device": "buzzconfpstn:{invitedID}",
         "from":"buzzconfpstn",
         "roomId":"{roomID}"
      }
   }
}

where

  • {roomID} is the unique identifier for this conference room
  • {invitedID} is the identifier of the invited person (only during this session)

Responses

After this, the session is aborted. No responses are expected.