gitplelive-voice-sdk

Gitple Live Voice SDK

Table of Contents

1. Install
2. Import and Init
3. Use
   • Init
   • Connect
   • Disconnect
   • Call
   • Dial Up
   • Hang Up
   • Mute
   • Unmute
   • Check Destination Session
   • Event Listener
4. Error
5. Migration

Install

# npm
$ npm i gitplelive-voice-sdk

# yarn
$ yarn add gitplelive-voice-sdk

Import and Init

es6

import { VoiceClient } from 'gitplelive-voice-sdk';

const config = {
  host, // gitplelive api host (ex. live.example.com ), Without http:// or https:// or url path
  app_id,
  user_id,
  token
};

const gitpleLiveVoiceClient = new VoiceClient(config);

browser

<script src="./node_modules/gitplelive-voice-sdk/dist/voice.min.js"></script>

const config = {
  host,
  app_id,
  user_id,
  token
};

const gitpleLiveVoiceClient = new GitpleLiveVoice.VoiceClient(config);

Use

Get User Token

• api
  • GET https://{Gitple Live API Host}/v1/voice/users/{USER_ID}/token
  • header

    {
      APP_API_KEY: 'APP API KEY',
      APP_ID: 'APP ID'
    }

  • response

    {
      token: 'TOKEN'
    }

  • expire: 24h

Init

• Initialize the SDK.

try {
  const config = {
    host,
    app_id,
    user_id,
    token
  };
  // es6
  const gitpleLiveVoiceClient = new VoiceClient(config);

  // browser
  const gitpleLiveVoiceClient = new GitpleLiveVoice.VoiceClient(config);
} catch (error) {
  // handle error
}

Connect

• Use to connect users to voice services.

try {
  await gitpleLiveVoiceClient.connectUser();
} catch (error) {
  // handle error
}

Disconnect

• Use to terminate a voice service connection.

try {
  await gitpleLiveVoiceClient.disconnectUser();
} catch (error) {
  // handle error
}

Call

• Use to make a call.

try {
  await gitpleLiveVoiceClient.call("{Other USER ID}");
} catch (error) {
  // handle error
}

Dial Up

• Use to receive calls.

try {
  await gitpleLiveVoiceClient.dialUp();
} catch (error) {
  // handle error
}

Hang Up

• Use to end or decline a call.

try {
  await gitpleLiveVoiceClient.hangUp();
} catch (error) {
  // handle error
}

Mute

• Use it to mute my voice. Available after the call is connected.

try {
  await gitpleLiveVoiceClient.mute(true);
} catch (error) {
  // handle error
}

Unmute

• Use to unmute. Available after the call is connected.

try {
  await gitpleLiveVoiceClient.mute(false);
} catch (error) {
  // handle error
}

Check Destination Session

• Use to check that the destination session exists. Lets you determine if the destination is connected to the SDK.
  • Returns the boolean value. (true = session present, false = no session)
  • CAUTION! If multiple sessions are not created indiscriminately and explicitly disconnected, the session may remain. If possible, please use the 'disconnectUser()' function to explicitly terminate the connection.

try {
  const flag = await gitpleLiveVoiceClient.checkSession("{Other USER ID}");
  if (flag) {
    // handle
  } else {
    // handle
  }
} catch (error) {
  // handle error
}

Event Listener

// Received when the call is created.
gitpleLiveVoiceClient.on('call', (data) => {
  // data: { id: {Call ID}, status: {Call Status}, direction: {Call direction}, from: {User ID}, to: {User ID} }

  // handle event
});

// Received whenever the status of the call changes.
gitpleLiveVoiceClient.on('call_status_changed', (data) => {
  // data: { id: {Call ID}, status: {Call Status}, direction: {Call direction}, from: {User ID}, to: {User ID} }

  // handle event
});

Event Payload

• payload

  {
    id: '{Call ID}',
    status: '{Call Status}',
    direction: '{Call direction}',
    from: '{User ID}',
    to: '{User ID}'
  }

• status

  |status|desc| |:---|:---| |started|The call connection has been started| |ringing|The destination has confirmed that the call is ringing. It may be missing depending on the situation of the destination.| |answered|The destination has answered the call| |completed|The call is completed successfully| |failed|The call connection failed| |rejected|The call attempt was rejected by the destination| |unanswered|There is no response to the call connection from the server|

  • call flow
    • nomal: started -> ringing (optional) -> answered -> completed
    • exception: started -> ringing(optional) -> unanswered | rejected | failed

• direction

  |direction|desc| |:---|:---| |outbound|Outgoing call| |inbound|incoming call|

Error

Payload

{
  code: number;
  name: string;
  message: string;
  stack: string;
}

Code

|code|name|Desc| |:---|:---|:---| |80101|invalid_parameter|Invalid Parameter |80102|not_found_user_session_id|User Session ID Not Found |80103|same_caller_and_destination|Same caller and destination |80201|already_connected_session|Already Connected Session |80202|already_busy_call|Already Busy Call |80401|invalid_token|Invalid Token |80402|no_connected_session|No Connected Session |80403|no_connected_call|No Connected Call |80404|no_connected_destination|Destination is not connected |80801|not_found_device|Device Not Found (microphone) |80802|permission_denied|Permission Denied (microphone) |80999|unknown_error|Unknown Error. Please contact us at Gitple

Migration

Migration guide from SDK 0.0.x to 0.1.X

• Initialize the SDK.
  • The host field has been added to the initialization information.

    try {
      const config = {
        host,  // Added Fields
        app_id,
        user_id,
        token
      };
      // es6
      const gitpleLiveVoiceClient = new VoiceClient(config);
    
      // browser
      const gitpleLiveVoiceClient = new GitpleLiveVoice.VoiceClient(config);
    } catch (error) {
      // handle error
    }