Webphone

Introdução

Essa biblioteca foi feita com o intuito de facilitar a realização de ligações por dispositivos da Wavoip. Ela disponibiliza uma interface customizável e isolada do projeto onde está instalada. Esse webphone usa o wavoip-api (Websocket) por debaixo dos panos

Instalação

Instale a biblioteca utilizando seu gerenciador de dependências favorito

PNPM

pnpm add @wavoip/wavoip-webphone

NPM

CDN

Primeiros Passos

Biblioteca instalada

Importe o objeto do webphone e chame a função render()

import WavoipWebphone from "@wavoip/wavoip-webphone"

WavoipWebphone.render()

Simples assim, a interface será renderizada na tela.

Para remover a interface, basta chamar a função destroy()

WavoipWebphone.destroy()

CDN

Use a variável wavoipWebphone que se encontra dentro da variável window

window.wavoipWebphone.render()
window.wavoipWebphone.destroy()

Controlando o Webphone em Código (API)

Ao renderizar o webphone, ele retornára uma Promise de uma API para controlá-lo, além de criar uma propriedade wavoip na variável window com a mesma API

WavoipWebphone.render(): Promise<WavoipAPI>

A partir disso, você pode utilizar a API da forma que escolher:

Instalado

import WavoipWebphone from "@wavoip/wavoip-webphone"

const webphoneAPI = await WavoipWebphone.render()
webphoneAPI.call.start("00999998888")

// OU 

await WavoipWebphone.render()
window.wavoip.call.start("00999998888")

CDN

É importante usar um await ao chamar o render(). Não fazer isso pode levar a comportamentos inesperados

WebphoneAPI

type WebphoneAPI = {
    call: CallAPI;
    device: DeviceAPI;
    notifications: NotificationsAPI;
    widget: WidgetAPI;
    theme: ThemeAPI;
    position: PositionAPI;
    settings: SettingsAPI;
};

Controlando as Chamadas (CallAPI)

type CallAPI = {
  start( to: string, config: { fromTokens?: string[], displayName?: string }) => Promise<
    | { err: { message: string; devices: { token: string; reason: string }[] } }
    | { err: null }
  >;
  startCall( to: string, fromTokens: string[] | null ) => Promise<
    | { err: { message: string; devices: { token: string; reason: string }[] } }
    | { err: null }
  >; // Deprecated
  getCallActive(): CallActiveProps | undefined;
  getCallOutgoing(): CallProps | undefined;
  getOffers(): CallProps[];
  setInput(to: string): void;
  onOffer(cb: (offer: CallProps) => void): void;
}

type CallProps = {
  id: string;
  type: CallType;
  device_token: string;
  direction: CallDirection;
  status: CallStatus;
  peer: {
    phone: string;
    displayName: string | null;
    profilePicture: string | null;
    muted: boolean;
  };
  muted: boolean;
}

Para informações sobre como iniciar uma call leia: Realizando uma ligação (Outgoing)

• setInput(): Seta o input de número para ligar na interface do webphone

Controlando os Dispositivos (DeviceAPI)

type DeviceAPI = {
    get(): Devices[]
    getDevices(): Devices[]; // Depreciado
    add(token: string, persist?: boolean): void;
    addDevice(token: string, persist?: boolean): void; // Depreciado
    remove(token: string): void;
    removeDevice(token: string): void; // Depreciado
    enable(token: string): void;
    enableDevice(token: string): void; // Depreciado
    disable(token: string): void;
    disableDevice(token: string): void; // Depreciado
}

Para informações sobre os dispositivos, leia Dispositivos

Ao adicionar um dispositivo com addDevice passando o parâmetro persist como True o dispositivo e suas configurações serão salvas no Local Storage do navegador, persistindo entre sessões

Desabilitar um dispositivo mata a conexão entre o webphone e o dispositivo, mas o dispositivo continua rodando

Controlando as Notificações (NotificationsAPI)

type NotificationsAPI = {
    get(): NotificationsType[];
    getNotifications(): NotificationsType[]; // Depreciado
    add(notification: NotificationsType): void;
    addNotification(notification: NotificationsType): void;  // Depreciado
    remove(id: Date): void;
    removeNotification(id: Date): void;  // Depreciado
    clear(): void;
    clearNotifications(): void;  // Depreciado
    read()
    readNotifications(): void;  // Depreciado
}

type NotificationsType = {
    id: Date;
    type: "INFO" | "CALL_FAILED";
    message: string;
    detail: string;
    token: string;
    isRead: boolean;
    isHidden: boolean;
    created_at: Date;
}

Controlando o Widget (WidgetAPI)

type WidgetAPI = {
    isOpen: boolean;
    open(): void;
    close(): void;
    toggle(): void;
    buttonPosition: {
        value: { x: number, y: number }
        set(position: "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center" | { x: number; y: number; }): void;
    }
}

Controlando o Tema (ThemeAPI)

type ThemeAPI = {
    value: "light" | "dark" | "system"
    set(theme: "light" | "dark" | "system"): void;
    setTheme(theme: "light" | "dark" | "system"): void; // Depreciado
}

Controlando a Posição (PositionAPI)

type PositionAPI = {
   value: { x: number; y: number };
   set(position: "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center" | { x: number; y: number; }): void;
}

Configurando o Webphone

Inicialização

Ao renderizar o webphone com o render() você pode passar alguns parâmetros

WavoipWebphone.render(config?: WebphoneSettings)

Os parâmetros são os seguintes

type WebphoneSettings = {
  theme?: "system" | "dark" | "light"; // (default: "system")
  statusBar?: {
    showNotificationsIcon?: boolean; // Mostrar o sino que abre as notificações (default: true)
    showSettingsIcon?: boolean; // Mostrar a engrenagem que abre o menu de configurações (default: true)
  };
  settingsMenu?: {
    deviceMenu?: {
      show?: boolean; // Mostrar o menu de dispositivos dentro do menu de configurações (default: true)
      showAddDevices?: boolean; // Mostrar o botão de habilitar/desativar dispositivos na tela de configurações (default: true)
      showEnableDevicesButton?: boolean; // Mostrar o switch de habilitar/desativar dispositivos na tela de configurações (default: true)
      showRemoveDevicesButton?: boolean; // Mostrar o botão de remover dispositivos na tela de configurações (default: true)
    };
  };
  widget?: {
    showWidgetButton?: boolean;  // Mostrar o botão de telefone que abre o discador (botão verde no canto da tela ao renderizar o webphone (default: true)
    startOpen?: boolean; // Renderizar o webphone com o discador aberto (default: false)
  };
  position?: "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right" | "center" | { x: number; y: number; }; // (default: "bottom-right")
}

Enquanto roda (SettingsAPI)

Ao renderizar, a variável window terá uma propriedade wavoip que pode ser usada para mudar as configurações em tempo real

type SettingsAPI = {
    // Mostrar o sino que abre as notificações
    showNotifications: boolean; 
    setShowNotifications(show: boolean): void;
    // Mostrar a engrenagem que abre o menu de configurações
    showSettings: boolean; 
    setShowSettings(show: boolean): void;
    // Mostrar o menu de dispositivos dentro do menu de configurações
    showDevices: boolean; 
    setShowDevices(show: boolean): void;
    // Mostrar o botão de adicionar dispositivos no menu de configurações
    showAddDevices: boolean; 
    setShowAddDevices(show: boolean): void;
    // Mostrar o botão de habilitar/desativar dispositivos na tela de configurações
    showEnableDevices: boolean; 
    setShowEnableDevices(show: boolean): void;
    // Mostrar o botão de remover dispositivos na tela de configurações
    showRemoveDevices: boolean; 
    setShowRemoveDevices(show: boolean): void;
    // Mostrar o botão de telefone que abre o discador (botão verde no canto da tela ao renderizar o webphone)
    showWidgetButton: boolean; 
    setShowWidgetButton(show: boolean): void; 
}