Skip to main content
Version: 5.3

1-to-1 audio call

This page provides a code example for making a 1-to-1 audio call.

Prerequisites​

Before you begin, you must do the following:

Considerations for implementing a 1-to-1 audio call​

To receive call notifications on the callee side, you must implement a notification system or integrate an external push notification system such as Apple Push Notification service (APNs) or Firebase Cloud Messaging (FCM).

You also need to know what information must be delivered to the callee. Refer to Role of the app server, which describes cc_param, the data that must be delivered by your application.

Implement an audio element​

On each side of the caller and the callee, prepare an audio element to play the peer's audio.

<html>
    <div>
        <audio id="peer-audio" autoplay></audio>
    </div>
</html>

<script>
    const peerAudioElement = document.getElementById('peer-audio');
</script>

Make an outgoing call (caller side)​

Create a MakeCallParams object.

const makeCallParams = {
    myId: 'MY_ID',
    myServiceId: 'MY_SERVICE_ID',
    peerId: 'PEER_ID',
    peerServiceId: 'PEER_SERVICE_ID',
    accessToken: 'ACCESS_TOKEN',
    mediaType: 'audio',
    mediaHtmlElement: {
        peer: {
            audio: peerAudioElement
        }
    },
    delegate: {
        // For each of the following, add your own implementation or
        // assign an event handler that matches the signature
        evtWaitConnected: () => {},
        evtConnected: () => {},
        evtDisconnected: (disconnectedParam) => {}
    }
};

To make a call, call makeCall() with the MakeCallParams object. If the call to makeCall() fails, you can determine the cause of failure in the following two cases.

  • If the call connection attempt fails
    • You can determine the cause of failure by checking START_FAIL_REASON in MakeCallError returned by Promise.reject().
  • If the call fails after connection
    • After the call is connected, you can determine the cause of failure through the evtDisconnected event of MakeCallParams.delegate. For more information about the reason for the call disconnection, see Disconnect reason.
planetKit.makeCall(makeCallParams)
    .then(() => {
        // Successfully made a call
    })
    .catch((makeCallError) => {
        // Failed to make a call
        // makeCallError.reason: START_FAIL_REASON
        // makeCallError.message: A descriptive message about the failure.
    });

Receive a call notification (callee side)​

FCM is one of web push notification methods. The following is an example of setting FCM using CDN.

<html>
  <script src="https://www.gstatic.com/firebasejs/7.24.0/firebase-app.js"></script>
  <script src="https://www.gstatic.com/firebasejs/7.24.0/firebase-messaging.js"></script>
</html>
<script>
  // Your web app's Firebase configuration
  const firebaseConfig = {
    apiKey: 'SAMPLE_API_KEY',
    authDomain: 'SAMPLE_AUTH_DOMAIN',
    databaseURL: 'SAMPLE_DATABASE_URL',
    projectId: 'SAMPLE_PROJECT_ID',
    storageBucket: 'SAMPLE_STORAGE_BUCKET',
    messagingSenderId: 'SAMPLE_MESSAGING_SENDER_ID',
    appId: 'SAMPLE_APP_ID'
  };
  // Initialize Firebase
  firebase.initializeApp(firebaseConfig);

  // Retrieve a Firebase Messaging object
  fcmSample = firebase.messaging();
  fcmSample.usePublicVapidKey('SAMPLE_VAPID_KEY');

  // Get a web push notification event
  fcmSample.onMessage((payload) => {
    callVerify(payload.data); // See the next step, "Respond to a call(Callee side)"
});
</script>

Respond to an incoming call (callee side)​

The callee comes to know that a new call has arrived through a push notification. When the callee receives a push message, create a VerifyCallParams object based on information received from the app server. You must parse the cc_param from the message and set it as ccParam of the VerifyCallParams object.

To respond to a call, call verifyCall() with the VerifyCallParams object. If the call to verifyCall() fails, you can determine the cause of failure in the following two cases.

  • If the call connection attempt fails
    • You can determine the cause of failure by checking START_FAIL_REASON in VerifyCallError returned by Promise.reject().
  • If the call fails after connection
    • After the call is connected, you can determine the cause of failure through the evtDisconnected event of VerifyCallParams.delegate. For more information about the reason for the call disconnection, see Disconnect reason.
function callVerify(notifyParams) {
    // Set verifyCallParams based on information of notifyParams received from the app server
    const verifyCallParams = {
        myId: notifyParams.app_callee_uid,
        myServiceId: notifyParams.app_callee_sid,
        mediaType: notifyParams.app_call_type, // 'audio'
        ccParam: notifyParams.cc_param,
        mediaHtmlElement: {
            peer: {
                audio: peerAudioElement
            }
        },
        delegate: {
            // For each of the following, add your own implementation or
            // assign an event handler that matches the signature
            evtVerified: (callVerifiedParams) => {},
            evtConnected: () => {},
            evtDisconnected: (disconnectedParam) => {},
        }
    }

    planetKit.verifyCall(verifyCallParams)
        .then(() => {
            // Successfully verified a call
        })
        .catch((verifyCallError) => {
            // Failed to verify a call
            // verifyCallError.reason: START_FAIL_REASON
            // verifyCallError.message: A descriptive message about the failure.
        });
}

Accept an incoming call (callee side)​

Once the session is successfully connected to the peer, the web client will trigger the evtVerified event, which was previously set in the delegate of VerifyCallParams. After receiving the evtVerified event, call acceptCall() to accept the call.

planetKit.acceptCall()
    .then(() => {
        // Successfully accepted a call
    })
    .catch((error) => {
        // Failed to accept a call
    });

End a call​

To end a call, call endCall().

planetKit.endCall();