SDK JS

Métodos e objetos JS para trabalhar com o Kommo

Esta seção fornece detalhes sobre como acessar o ambiente de forma fácil, incluindo informações do widget, informações do usuário autorizado e como chamar vários elementos da interface.

Notificação pop-up

Uma das funcionalidades que o sistema oferece é a capacidade de exibir uma janela de notificação no canto inferior direito da tela. Essa funcionalidade pode ser usada para notificar os usuários sobre uma chamada recebida por VoIP.

Você pode usar o objeto fornecido para realizar essa ação. No exemplo a seguir, foi criada uma função para trabalhar com esse objeto.

self.add_call_notify = function(mess){
    const w_name = self.i18n('widget').name,
        date_now = Math.ceil(Date.now()/1000),
        lang = self.i18n('settings'),
        n_data = {
            from: mess.from,
            to: mess.to,
            duration: mess.duration,
            link: mess.link,
            text: w_name + ': ' + mess.text,
            date: date_now
        };
 
    if (mess.element && mess.element.id && mess.element.type){
        n_data.element = mess.element;
    }
   
    APP.notifications.add_call(n_data);
};
 
/*---------------------------------------*/
const notify_data={};
notify_data.from = '+7 (999) 111 22 33';
notify_data.to = 'Nome de usuário';
notify_data.duration = 65;
notify_data.link = 'https://example.com/dialog.mp3';
notify_data.text = 'Texto do Widget';
notify_data.element = { id: 1003619, type: "contact" };
 
self.add_call_notify(notify_data);

No exemplo, a função não apenas chama a janela de notificação, mas também adiciona um link.

Notificação de Erro

Se o JavaScript realiza ações em segundo plano que estão ocultas do usuário, é importante notificá-lo sobre quaisquer problemas que possam surgir. Isso ajuda o usuário a tomar as medidas necessárias para corrigir o problema e evitar frustrações.

Por exemplo, se você estiver desenvolvendo um widget VoIP que, ao se conectar ao servidor em segundo plano, aguarda eventos de chamadas recebidas, é fundamental notificar o usuário caso haja algum problema na conexão com o servidor. Fornecendo uma mensagem de erro clara e uma descrição do problema, você pode ajudá-lo a entender a situação e até mesmo fornecer informações de contato para suporte técnico.

Da mesma forma, se um usuário digitar a senha errada, é melhor notificá-lo do erro imediatamente. Assim, ele não ficará se perguntando por que a funcionalidade esperada não está funcionando.

O objeto a seguir, semelhante à notificação descrita anteriormente, pode ser útil para isso. Ele exibe uma mensagem de erro e armazena o evento de fechamento no cookie do usuário, garantindo que o usuário não seja incomodado novamente com a mesma notificação.

const  errors = APP.notifications,
    date_now = Math.ceil(Date.now()/1000),
    header = self.get_settings().widget_code,
    text = 'error'
    const n_data = {
                header: header, // código do widget  
                text:'<p>'+text+'</p>',// mensagem de texto do erro
                date: date_now // /date
            },
    callbacks = { done: function(){console.log('done');}, // adicionado e salvo com sucesso. AJAX concluído
                  fail: function(){console.log('fail');}, //AJAX falhou
                  always: function(){console.log('always');} // sempre chamado
                };
 
    errors.add_error(n_data,callbacks);
  • header (string) - nome do widget que será exibido no título.
  • text(string) - mensagem de erro
  • date - data
  • callbacks(object) - no processo de envio de uma nova mensagem ou tratamento de um erro AJAX, uma solicitação é enviada ao servidor. Se os dados forem salvos com sucesso, o servidor retorna o número da mensagem. Dependendo se a solicitação foi bem-sucedida ou não, uma das funções passadas do objeto é acionada.

Status online do usuário

Este método permite obter informações sobre o status online do usuário. O status pode ser true (se o usuário estiver online) ou false (se o usuário estiver offline).

Obtendo status online para todos os usuários

APP.sdk.showUserStatus() //objeto com todos os IDs de usuários e seus status
//Examplo de resposta:
{
    {
        id: 123456 ,
        online: true
    },
    {
        id: 123456 ,
        online: false
    }, ...
}

Para obter todos os usuários e seus status online, o método é chamado sem um sinalizador e retorna um objeto com todos os IDs de usuários e seus status online.

Obtendo os IDs de todos os usuários na rede

APP.sdk.showUserStatus(‘online’) // array de todos os IDs de usuários online\
//Examplo de resposta:
[123456 , 123457...]

Para obter uma lista de todos os usuários online, este método deve ser chamado com o sinalizador ""online"". Nesse caso, ele retornará um array contendo os IDs dos usuários online.

Obtendo o status online de um usuário por meio de seu ID

const id_user = 123456; // ID de conta exclusivo\
const status_user = APP.sdk.showUserStatus (id_user); // status online do usuário (true ou false)

Para obter o status de um usuário pelo ID, você precisa chamar o método com um identificador de conta exclusivo. Este método retornará true (se o usuário estiver online) ou false (se o usuário não estiver online).

Configurando o status da chamada

Este método permite definir o status da chamada. Parâmetro de entrada booleano (true/false).

Configurar o status da chamada

APP.sdk.setCallingStatus(boolean)

Obtendo o status da chamada

Este método permite descobrir o status de uma chamada telefônica. O resultado da execução é booleano.

Obtendo o status da chamada

if (APP.sdk.getCallingStatus()) {  
    // code
} else {
    // code
}

Esta funcionalidade é necessária para evitar que a chamada seja interrompida pelo widget de telefonia quando a Kommo for atualizada (as alterações são aplicadas).