Invite Service

Invite Service allows user A to send a time-limited invite to user B. In most cases this would be an invite to join a video session or answer a phone call.

Sending an invite cannot be fully solved on the client side - what do you do when this invite is not answered? Or user A disconnects before it gets a reply. Or user B does not have the app in the foreground. Who is responsible for delivering a missed call notification? What if user B has two devices, both of them ring on incoming call, user B answers on the first device. How do you stop ringing on his second device? Invite Service solves this.

Initialization

The only argument needed to initialize the Invite Service is an instance of Signal Service.

// Init Invite Service
var inviteSvc = new bit6.Invite(signalSvc);

Send Invite

User A sends an Invite to User B. This outgoing invite has:

The actual code to send the invite is pretty straightforward. You just need to describe the push notification payloads to be delivered:

// App-specific payload we want to deliver
var info = {
    id: videoSessionId,
    media: {audio: true, video: true}
};
// Describe APNS and FCM messages you want to deliver
// on invite and on timeout
var payloadMsg = {
    signal: info,
    apns: {
        aps: {
            alert: 'Alice is calling...'
        }
        data: {
            invite: info
        }
    },
    fcm: {
        data: {
            title: 'Alice is calling...',
            invite: info
        }
    }
};
var timeoutMsg = {
    signal: {},
    aps: {
        aps: {
            alert: 'Missed call from Alice',
        }
    },
    fcm: {
        data: {
            title: 'Missed call from Alice',
        }
    }
};
// Actual Invte object to send
var data = {
    to: 'bob',
    ttl: 60,
    payload: payloadMsg,
    timeout: timeoutMsg
};

inviteSvc.send(data, function(err, invite)) {
  // listen to events on 'invite'
}

The caller (User A) will get events on this outgoing invite object:

invite.on('timeout', function()) {
  // The recipient did not answer - neither accepted or rejected
});

invite.on('accept', function()) {
  // The recipient accepted this invite
});

invite.on('reject', function()) {
  // The recipient rejected this invite
});

At any time the user who sent the outgoing invite can cancel it:

invite.cancel()

This will trigger the delivery of the timeout payload to the recipient.

Receive Invite

The code to receive incoming invites depends on on the platform push support implementation. For Invites arriving via Signal Service you can simply do:

inviteSvc.on('invite', function(invite) {
    // Got new incoming invite
});

Once the incoming invite is received the application needs to decide whether accept or reject it. For example it can display an incoming call UI and let the user answer or decline the call.

// Accept the invite
invite.accept()
// Or reject the invite
// invite.reject()

The platform will then let the sender know if the invite was accepted or rejected.

The recipient (User B) can listen to events on the Incoming invite:

invite.on('timeout', function() {
 // Missed the call, no need to answer it now
 // dismiss Incoming Call UI
});

invite.on('handled', function() {
 // Another device of User B has accepted or rejected this invite.
 // No need to answer it now - dismiss Incoming Call UI
});

On the invite timeout or if the sender (User A) cancels the outgoing invite, user B will receive the 'missed call' payload.