wavoip-api (Websocket)

Ao conectar no dispositivo usando essa biblioteca, o dispositivo será atualizado para versão nova automaticamente

Introdução

Essa biblioteca foi feita com o intuito de facilitar a utilização dos dispositivos da Wavoip por meio de websockets. Ela abstrai toda comunicação de eventos entre o cliente e o dispositivo, além de toda parte de áudio de chamadas

Como a comunicação de websockets se dá por meio de eventos, a biblioteca foi feita para ser utilizada por meio callbacks.

Instalação

Instale a biblioteca utilizando seu gerenciador de dependências favorito

PNPM

pnpm add @wavoip/wavoip-api

NPM

Classe Wavoip

Instancie a classe Wavoip e passe os tokens de seus dispositivos como parâmetros

É possível adicionar ou remover tokens de dispositivos após a classe ser instanciada

import { Wavoip } from "@wavoip/wavoip-api"

const wavoip = new Wavoip({
    tokens: ["token 1", "token 2", ...]
})

---

Dispositivos

Acessando os dispositivos

Com a classe instânciada, você poderá resgatar os dispositivos pela propriedade:

Wavoip.devices: Device[]

Cada dispositivo possui as seguintes propriedades:

type Device = {
    token: string;
    status: DeviceStatus | null;
    qrcode: string | null;
    contact: DeviceContacts
    onStatus(cb: (status: DeviceStatus | null) => void): void;
    onQRCode(cb: (qrcode: string) => void): void;
    onContact(cb: (type: CallType, contact: Contact | null) => void): void;
    restart(): Promise<string | null>
    logout(): Promise<string | null>;
    wakeUp(): Promise<DeviceAllInfo | null>;
    pairingCode(phone: string): Promise<{ pairingCode: string; err: null } | { pairingCode: null; err: string }>;
    delete(): void;
};

Tanto a propriedade status, quanto qrcode serão atualizadas em tempo real via websocket, e, ao serem atualizadas, chamarão seus respectivos callbacks. Estes callbacks podem ser definidos ao chamar o onStatus() e o onQRCode() passando uma função como parâmetro.

A função wakeUp() poderá ser usada para ligar o dispositivo caso ele entre em modo de hibernação Hibernating

Vinculando um número de celular

Se seu(s) dispositivo(s) já possui(em) um número vinculado, pule para a seção Status do dispositivo

Para vincular um número é necessário ler o QRCode do dispositivo no celular. Para isso é possível usar duas abordagens.

1. Acessar o QRCode na plataforma

2. Utilizar alguma biblioteca para renderizar QRCode a partir da propriedade device.qrcode. Recomendamos node-qrcode para vanilla JS ou react-qrcode para projetos React

Device.qrcode: string | null

Para saber se o número foi vinculado com sucesso ou não basta olhar o Status do dispositivo

Status do dispositivo

O dispositivo pode possuir os seguintes status:

type DeviceStatus =
    | "disconnected"
    | "close"
    | "connecting"
    | "open"
    | "restarting"
    | "hibernating"
    | "BUILDING"
    | "EXTERNAL_INTEGRATION_ERROR";

Disconnected

O websocket do navegador perdeu conexão com o dispositivo. Normalmente o websocket reconectar ao dispositivo automaticamente

Close

Não existe nenhum número vinculado ao dispositivo. Caso nenhum número seja vinculado o dispositivo poderá entrar em modo Hibernating

Connecting

QRCode pronto e esperando algum número ser vinculado. Caso nenhum número seja vinculado o dispositivo poderá entrar em modo Hibernating

Open

Pronto para realizar chamadas

Restarting

O dispositivo está esperando as chamadas ativas terminarem para reiniciar. Nenhuma nova chamada poderá ser feita

Hibernating

Caso o dispositivo não seja vinculado a um número dentro de 2 minutos e 30 segundos, ele entrará em modo de hibernação e receberá o status "hibernating". Para reativá-lo, basta chamar a função powerOn() do dispositivo

Building

O dispositivo foi inicializado e está em processo de construção. Nenhuma chamada poderá ser feita

EXTERNAL_INTEGRATION_ERROR

Ocorreu algum erro ao usar uma integração externa e o dispositivo não consegue se recuperar (Necessário reiniciar)

Adicionando ou removendo dispositivos

Para adicionar novos dispositivos a instância basta chamar o addDevices() passando os tokens como parâmetro

Wavoip.addDevices(tokens: string[]): Device[]

A função retorna somente os dispositivos adicionados, para acessar todos dipositivos ver Acessando os dispositivos

Para remover, basta chamar o removeDevices() passando os mesmos parâmetros. Essa função retorna os dispositivos que ficaram

Wavoip.removeDevices(tokens: string[]): Device[]

---

Objeto Call

Todas chamadas, ofertas (incoming) e saintes (outgoing) herdarão as propriedades desse objeto

type Call = {
    id: string;
    type: "official" | "unofficial"
    device_token: string;
    direction: "INCOMING" | "OUTGOING";
    status: "RINGING" | "CALLING" | "NOT_ANSWERED" | "ACTIVE" | "ENDED" | "REJECTED" | "FAILED" | "DISCONNECTED" | "DEVICE_RESTARTING",
    peer: {
        phone: string;
        displayName: string | null;
        profilePicture: string | null;
        muted: boolean;
    };
    muted: boolean;
}

• id: Cada chamada possui um ID único

• device_token: Qual dispositivo a chamada veio

• direction: Ofertas de chamada (INCOMING), chamadas saintes (OUTGOING)

• status: Status atual da chamada

• peer: Objeto representando o outro participante da chamada

• muted: Se você está mutado

---

Recebendo ligações (Incoming)

Para receber ofertas de chamadas (incoming) é necessário definir um callback para a função onOffer() da sua instância

Wavoip.onOffer((offer: CallOffer) => {
    // faça algo
})

O callback receberá um objeto do tipo CallOffer

type CallOffer = Call & {
    accept(): Promise<{ call: CallActive; err: null} | { call: null, err: string }>;
    reject(): Promise<{ err: string | null;}>;
    onAcceptedElsewhere(cb: () => void): void;
    onRejectedElsewhere(cb: () => void): void;
    onUnanswered(cb: () => void): void;
    onEnd(cb: () => void): void;
    onStatus(cb: (status: CallStatus) => void): void;
};

Objeto herda propriedades do Objeto Call

Com esse objeto você poderá aceitar, rejeitar e escutar alguns eventos de uma oferta de chamada

onAcceptedElsewhere: Outro cliente conectado no mesmo dispositivo aceitou essa oferta. Ela não pode mais ser aceita

onRejectedElsewhere: Outro cliente conectado rejeitou essa oferta.

onUnanswered: A oferta terminou sem ser aceita ou rejeitada

onEnd: Callback que será chamada ao fim de eventos negantes (onRejectedElsewhere, onUnanswered)

Aceitando ofertas

Ao aceitar uma chamada com offer.accept() a função retornará uma promise

CallOffer.accept(): Promise<
    | { call: CallActive; err: null} 
    | { call: null, err: string }
>;

Desse modo vc poderá verificar se conseguiu aceitar a chamada com sucesso usando a forma que achar mais apropriada. Exemplo:

CallOffer.accept().then(({ call, err }) => {
    if(err) {
        // Faça algo em relação ao erro
        return
    }
    
    // Faça algo com a call
})

Para controlar a chamada ativa olhar seção wavoip-api (Websocket)

Rejeitando ofertas

A lógica é a mesma de aceitar uma chamada. A função offer.reject() retorna uma promise

CallOffer.reject(): Promise<{ err: string | null}>;

Exemplo de tratativa:

CallOffer.reject().then(({ err }) => {
    if(err) {
        // Faça algo em relação ao erro
        return
    }
    
    // Faça algo com a call
})

---

Realizando uma ligação (Outgoing)

Por meio de uma função assíncrona

Como as ligações funcionam por meio de websockets, sua utilização é por meio de eventos. Dessa forma, a biblioteca foi pensada para ser usada por meio de callbacks para esses eventos.

Para realizar uma ligação, basta chamar a função startCall() e passar um objeto de parâmetros. Nesses parâmetro será indicado para quem será a ligação e alguns callbacks

Wavoip.startCall({
    to: string;
    fromTokens?: string[];
}): Promise<
    | { call: CallOutgoing; err: null }
    | { 
        call: null; 
        err: { message: string; devices: { token: string; reason: string }[]
      }
>

to: Número de telefone que irá ligar

fromTokens: Quais dispositivos deverão ser utilizados para ligar

Caso não passe nada ou uma array vazia para o fromTokens a instância tentará ligar em todos dispositivos

A função retornará uma chamada sainte (outgoing) caso consiga ligar ou uma array indicando o erro em cada dispositivo no qual foi tentado ligar. Exemplo:

Wavoip.startCall({ 
    to: "00999998888", 
    fromTokens: ["token1", "token2"]
}).then(({ call, err }) => {
    if(err) {
        // Faça algo
        return
    }
    
    // Continue com a chamada
})

Por meio de um Generator assíncrono

Existe uma maneira de realizar uma chamada e tratar as falhas dos dispositivos de modo iterativo com um generator chamando o startcalliterator()

for await (const result of Wavoip.startcalliterator({ to: "5511999999999" })) {
  if (result.err) {
   // Trate o erro
  } else {
   // Trate a chamada
  }
}

Controlando uma chamada outgoing

Uma chamada sainte possui a seguinte estrutura

type CallOutgoing = Call & {
    onPeerAccept(cb: (call: CallActive) => void): void;
    onPeerReject(cb: () => void): void;
    onUnanswered(cb: () => void): void;
    onEnd(cb: () => void): void;
    mute(): Promise<{ err: string | null }>;
    unmute(): Promise<{ err: string | null }>;
    end(): Promise<{ err: string | null }>;
    onStatus(cb: (status: CallStatus) => void): void;

};

Objeto herda propriedades do Objeto Call

Aqui segue o mesmo raciocínio do Aceitando ofertas. Você pode escutar eventos e realizar ações

onPeerAccept: Chamada foi aceita pelo outro lado

onPeerReject: Chamada foi rejeitada pelo outro lado

onUnanswered: O outro lado não respondeu nada

onEnd: Callback final para eventos negantes (onPeerReject, onUnanswered)

Todas ações retornam promises que podem resultar em um erro ou não, trate-as como achar melhor

Quando o outro lado aceitar a chamada, o evento onPeerAccept será chamado e você terá em mãos uma chamada ativa

---

Controlando uma Chamada Ativa

Ao aceitar uma oferta de chamada ( Recebendo ligações (Incoming)) ou aceitarem uma chamada sua ( Realizando uma ligação (Outgoing)) você receberá uma chamada Ativa

type CallActive = Call & {
    connection_status: "disconnected" | "connected" | "connecting";
    audio_analyser: Promise<AnalyserNode>;
    mute(): Promise<{ err: string | null }>;
    unmute(): Promise<{ err: string | null }>;
    end(): Promise<{ err: string | null }>;
    onError(cb: (err: string) => void): void;
    onPeerMute(cb: () => void): void;
    onPeerUnmute(cb: () => void): void;
    onEnd(cb: () => void): void;
    onStats(cb: (stats: CallStats) => void): void;
    onConnectionStatus(callback: (status: TransportStatus) => void): void;
    onStatus(cb: (status: CallStatus) => void): void;
};

Objeto herda propriedades do Objeto Call

Seguimos com o mesmo raciocínio de eventos para serem escutados e ações a serem tomadas

onPeerMute: O outro lado se mutou

onPeerUnmute: O outro lado se desmutou

onError: Ocorreu algum erro durante a chamada

onEnd: A chamada foi finalizada

onStats: Foi recebida estatisticas da chamada

Todas ações retornam promises que podem resultar em um erro ou não, trate-as como achar melhor

Analisando o áudio de uma chamada

Toda chamada ative possui uma promise que resulta em um AnalyserNode. Esse objeto serve para fazer a análise do áudio de uma chamada e possibilita, por exemplo, criar efeitos visuais em relação ao volume da voz.

Estatísticas da chamada

Ao entrar em uma chamada você receberá algumas estatísticas pelo evento onStats

export type CallStats = {
    rtt: {
        client: {
            min: number;
            max: number;
            avg: number;
        };
        whatsapp: {
            min: number;
            max: number;
            avg: number;
        };
    };
    tx: {
        total: number;
        total_bytes: number;
        loss: number;
    };
    rx: {
        total: number;
        total_bytes: number;
        loss: number;
    };
};

RTT

Round Time Trip, ou mais comument chamado de ping. Você terá o ping entre o navegador e o dispositivo (rtt.client) e do dispositivo ao Whatsapp (rtt.whatsapp)

TX

Quantidade de pacotes de áudio enviados e perdidos

RX

Quantidade de pacotes de áudio recebidos e perdidos