Ir para o conteúdo

Integração WebSocket em Tempo Real

Esta documentação descreve o protocolo de comunicação via WebSocket para integração com o servidor de telefonia. O sistema utiliza uma conexão persistente para enviar eventos de status de ramais, filas e agentes em tempo real.

Conexão

  • URL do Endpoint: wss://servidor.com.br/ws/online/
  • Protocolo: WSS (WebSocket Secure)

Requisito

É necessário um token de acesso válido para estabelecer a comunicação e receber eventos.

1. Autenticação

Imediatamente após estabelecer a conexão WebSocket, o cliente deve enviar uma mensagem JSON contendo o token de autenticação.

Envio do Token

Formato: 

{
  "token": "SEU_TOKEN"
}

Resposta de Sucesso (Evento login)

Se a autenticação for bem-sucedida, o servidor retornará um evento do tipo login. Este evento contém os detalhes do usuário autenticado e as listas de permissões (quais ramais/agentes ele pode monitorar).

Exemplo de Resposta: 

{
    "event": "login",
    "message": {
        "username": "gnew@21",
        "extensao": "IP-7340-0mvJC",
        "spy_list": [
            "1137092380",
            "IP-7318-wq784",
            "IP-7307-fhRhs"
            // ... lista completa de peers monitoráveis
        ],
        "agent_list": [
            "1137092380",
            "IP-7318-wq784",
            "IP-7307-fhRhs"
            // ... lista de agentes
        ],
        "queue_list": [
            "Queue_795",
            "Queue_1306",
            "Queue_1308",
            "Queue_1329",
            "Queue_1334"
        ]
    }
}

Campos do objeto

Campo Descrição
username Identificação do usuário conectado.
extensao Ramal associado à conexão atual.
spy_list Lista de IDs (SipPeers) permitidos para monitoria de áudio (spy).
agent_list Lista de agentes visíveis para este usuário.
queue_list Lista de filas de atendimento visíveis.

2. Eventos em Tempo Real

Após a autenticação, o servidor envia eventos assíncronos (push) sempre que ocorre uma alteração relevante no estado dos ramais, filas ou agentes.

2.1. Status de Ramais (blf)

O evento blf (Busy Lamp Field) é enviado para atualizar o status de ocupação dos ramais monitorados.

Exemplo de Payload:

{
  "event": "blf",
  "message": [
    {
      "extensao": "100",
      "nome": "GNEW LOCAL MM",
      "SipPeer": "1137092380",
      "status": "NOT_INFO"
    },
    {
      "extensao": "7342",
      "nome": "José",
      "SipPeer": "IP7342",
      "status": "INUSE"
    },
    {
      "extensao": "500",
      "nome": "Maria",
      "SipPeer": "IPVre0d",
      "status": "UNAVAILABLE"
    }
    // ... lista completa de ramais
  ]
}

Campos do objeto message

Campo Tipo Descrição
extensao String O número do ramal.
nome String O nome de exibição do usuário do ramal.
status String O estado atual do ramal (ver tabela abaixo).
SipPeer String O identificador interno do dispositivo SIP.

Status Possíveis

Status Significado
NOT_INUSE O ramal está livre e pronto para receber chamadas.
INUSE O ramal está em uma chamada ativa.
RINGING O ramal está recebendo uma chamada.
UNAVAILABLE O ramal está desconectado, não registrado ou indisponível.
NOT_INFO O sistema não possui informações precisas sobre o estado atual.

2.2. Visão Geral das Filas (queues)

Este evento fornece métricas consolidadas sobre as filas de atendimento, incluindo contadores de agentes livres, ocupados e em pausa.

Exemplo de Payload:

{
  "event": "queues",
  "message": [
    {
      "extensao": "0001",
      "queuename": "Queue_795",
      "nome": "Atendimento",
      "membros_totais": 6,
      "membros_livres": 2,
      "membros_ocupados": 1,
      "membros_pausados": 0,
      "membros_tocando": 0,
      "membros_indisponiveis": 3,
      "chamadas_espera": 0,
      "membros": [
        {
          "member_name": "SIP/IP-7337",
          "penalidade": "0",
          "chamadas_atendidas": "0",
          "ultima_chamada": "0",
          "pausado": "1",
          "motivo_pausa": "",
          "extensao": "7337",
          "nome": "Maria",
          "status": "UNAVAILABLE",
          "Timestamp": 1764935858.432142
        },
        {
          "member_name": "SIP/IP-7336",
          "penalidade": "0",
          "chamadas_atendidas": "0",
          "ultima_chamada": "0",
          "pausado": "0",
          "motivo_pausa": "",
          "extensao": "7336",
          "nome": "José",
          "status": "NOT_INUSE",
          "Timestamp": 1764948203.88609
        }
        // ... lista completa de agentes
      ]
    }
    // ... lista completa de filas
  ],
  "total": {
    "espera": 0,
    "total": 11,
    "livres": 4,
    "ocupados": 1,
    "tocando": 0,
    "pausado": 1,
    "indisponiveis": 5
  }
}

Campos do objeto message

Campo Descrição
extensao String
queuename String
nome String
nome String
membros_totais Inteiro
membros_livres Inteiro
membros_ocupados Inteiro
membros_pausados Inteiro
membros_tocando Inteiro
membros_indisponíveis Inteiro
chamadas_espera Inteiro
membros Array
total Object

2.3. Detalhes dos Agentes (members)

O evento members foca nos Agentes de Atendimento. Ele fornece detalhes operacionais como pausas, chamadas atendidas e qual chamada está ativa no momento. Diferente do blf, este evento traz dados de produtividade e estado em relação às filas.

Exemplo de Payload:

{
  "event": "members",
  "message": [
    {
      "extensao": "7342",
      "nome": "Manoel",
      "SipPeer": "IP7342",
      "status": "INUSE",
      "pausa": 0,
      "chamadas_atendidas": 1,
      "chamada_corrente": "37092380",
      "sentido": "saida",
      "queue_ch": null,
      "queues_qtdade": 1,
      "queues_status": [
        {
          "queuename": "COMERCIAL",
          "penalidade": "0",
          "chamadas_atendidas": "0",
          "ultima_chamada": "0",
          "pausado": "0",
          "motivo_pausa": ""
        }
        // ... lista completa de filas
      ],
      "Timestamp": 1764947062.338254
    }
    // ... lista completa de agentes
  ],
  "total": {
    "atendidas": 1,
    "total": 10,
    "livres": 3,
    "ocupados": 1,
    "tocando": 0,
    "pausado": 1,
    "indisponiveis": 5
  }
}

Campos do objeto message

Campo Tipo Descrição
extensao String O número do ramal.
nome String O nome de exibição do usuário do ramal.
SipPeer String O identificador interno do dispositivo SIP.
status String O estado atual do ramal.
pausa Inteiro Indica se o agente está em pausa (1) ou ativo (0).
chamadas_atendidas Inteiro Contador de chamadas atendidas pelo agente na sessão atual.
chamada_corrente String/Null O número de telefone com o qual o agente está falando. Retorna null se não houver chamada ativa.
sentido String A direção da chamada atual: entrada ou saida.
queue_ch String Fila por onde a chamada corrente entrou.
queues_qtdade Inteiro Quantidade de filas na qual o agente faz parte.
queues_status Array Lista detalhando a situação do agente em cada fila que ele pertence.
Timestamp float Tempo no qual o agente está no status corrente.
total Object Indicadores gerais.

2.4. Pausa de agentes

A acao permite enviar solicitação de Pause ou Unpause para um agente.

Pause

{
  "acao":"pause",
  "agente":"IP-100-e9nc1"
}

Unpause

{
  "acao":"unpause",
  "agente":"IP-100-e9nc1"
}

2.5. Sussuro e Monitoramento

A acao permite enviar solicitação para sussurrar ou monitorar um agente.

Sussuro

{
  "acao":"sussurrar",
  "agente":"IP-100-e9nc1"
}

Monitoramento

{
  "acao":"monitorar",
  "agente":"IP-100-e9nc1"
}