ys-webrtc-sdk-core

中文 | English

Yeastar WebRTC SDK Core is a web development toolkit designed for Yeastar P-Series PBX, which is pre-integrated with PBX calling functionality. It simplifies the complexity of WebRTC implementation and facilitates the deployment of third-party applications for audio and video communication.

• ys-webrtc-sdk-core
  • react demo
  • Obtain the signature
  • PBXOperator
  • PhoneOperator
  • Session
  • Result
  • Types

SDK selection

Yeastar WebRTC SDK Core supports several module formats: UMD, CJS, ESM, and IIFE. You can choose the module format according to your needs.

Note: If you prefer a smaller SDK bundle size or have existing projects that support ESM, it is recommended to import the ESM module.

Installation

Use either of the following methods to install Yeastar WebRTC SDK Core to your project.

• Use npm to install Yeastar WebRTC SDK Core.

  npm install ys-webrtc-sdk-core

• Use script to init Yeastar WebRTC SDK Core.

  <script src="./ys-webrtc.umd.js"></script>
  <script>
    // Upon successful loading, initialize the Yeastar WebRTC SDK Core using the 'YSWebRTC' object. 
    YSWebRTC.init({
      username: '1000',
      secret: 'sdkshajgllliiaggskjhf',
      pbxURL: 'https://192.168.1.1:8088',
    })
      .then((operator) => {
        // Obtain the 'PhoneOperator' instance, 'PBXOperator' instance, and 'destroy' method.
        const { phone, pbx, destroy } = operator;
      })
      .catch((error) => {
        console.log(error);
      });
  </script>

Getting started

The brief code example below demonstrates the basic workflow for making and receiving calls via Yeastar WebRTC SDK Core.

import { init } from 'ys-webrtc-sdk-core';

init({
    username: '1000',
    secret: 'sdkshajgllliiaggskjhf',
    pbxURL: 'https://192.168.1.1:8088'
})
    .then(operator => {
        // Obtain the 'PhoneOperator' instance, 'PBXOperator' instance, and 'destroy' method.
        const { phone, pbx, destroy } = operator;

        // Create an RTC instance.
        phone.on('newRTCSession', ({callId,session})=>{
            const {status} = session

            // Listen for events in the session.
            session.on('confirmed', {callId,session})=>{
                // A call is successfully connected, the 'session.status.callStatus' changes to 'talking'.
                // Update the user interface to start the call timer.
            })

        })
        // Listen for the 'startSession' events.
        phone.on('startSession',({callId,session})=>{
            const {status} = session
            if(status.communicationType === 'outbound') {
                // Outbound call.
                // Update the user interface to display 'Calling', indicating the callee side is ringing.
            }else{
                // Inbound call.
                // Update the user interface to display 'Connecting'.
            }

        });

        // Listen for Incoming call events.
        phone.on('incoming', (callId,session)=>{
            const {status} = session
            // Pop up an incoming call dialog displaying the caller's phone number and contact name on the User interface.
            // ...
            // Click the 'Answer' button to trigger the 'answer' method and the 'startSession' event.
            phone.answer(status.number); 
        });

        // After events subscription, start connecting to the SIP UA.
        phone.start();

        // ...
        // Click the 'Call' button to call 1001.
        phone.call('1001')

    })
    .catch(error => {
        console.log(error);
    });

Yeastar WebRTC SDK Core export init methods to initialize the SDK.

• init: Initialize Yeastar WebRTC SDK Core. Upon successful initialization, two instantiated Operator objects 'PhoneOperator' and 'PBXOperator', and a method 'destroy' are returned:
  • PhoneOperator: The object contains methods and attributes related to the call handling, such as 'call', 'hangup', and others.
  • PBXOperator: The object contains methods and attributes related to the PBX operations, such as querying CDR.
  • destroy: This method is used to destroy Yeastar WebRTC SDK Core.

Initialization (init) parameters

| Parameter | Type | Required | Description | | ---- | ---- | ---- | ---- | | username | string | Yes | Extension number. | | secret | string | Yes | Login signature，which can be obtained using the OPEN API. For more information, see Obtain a Server-side Signature. | | pbxURL | URL | string | Yes | The URL for accessing your PBX system, including the transfer protocol and the port number.For example, https://192.168.1.1:8088 or https://xx.xxx.com. | | enableLog | boolean | No | Whether to enable log output and report error logs to PBX. This feature is enabled by default. | | reRegistryPhoneTimes | number | No | Define the number of attempts to reconnect to the SIP service. By default, it is unlimited. | | userAgent | "WebPC" | "WebClient" | No | The UA (user agent ) in Asterisk, which indicates the client type. The default value is WebClient. | | deviceIds | { cameraId?: string; microphoneId?: string;} | No | Specify the IDs of the audio and video input devices, including the camera ID and microphone ID. | | disableCallWaiting | boolean | No | Whether to disable call waiting. When setting this value to true, the PBX call waiting value does NOT take effect and PBX only handles single calls. |

Ringtone resources

The assets directory contains the available ringtone resources for Yeastar WebRTC SDK Core, as shown in the following table.

| Name | Description | | ---- | ---- | | Ring | Incoming call ringtone | | Callend | Call end tone | | Callwaiting | Call waiting tone | | ringback | Outgoing call tone | | DTMF00 | Keypad 0 tone | | DTMF01 | Keypad 1 tone | | DTMF02 | Keypad 2 tone | | DTMF03 | Keypad 3 tone | | DTMF04 | Keypad 4 tone | | DTMF05 | Keypad 5 tone | | DTMF06 | Keypad 6 tone | | DTMF07 | Keypad 7 tone | | DTMF08 | Keypad 8 tone | | DTMF09 | Keypad 9 tone | | DTMFStar | Keypad * tone | | DTMFPound | Keypad # tone |

Ringtone resources can be provided in either of the following ways:

• Provide the original audio files of the ringtone resources.

• Use the base64-encoded strings of the ringtone resources, as shown in the example code below.

  import sounds from '/assets/sounds';
  const { Ring, Callend } = sounds;
  const audio = new Audio(Ring);
  audio.play();
    
  // Change the value of "audio.src" to play different ringtones.
  audio.src = Callend;
  audio.play();

License

Copyright (c) 2023 Xiamen Yeastar Digital Technology Co., Ltd.