API - Recursos disponíveis



Equipes: Crie equipes para gerenciar os seus times de atendimento. Cada time terá o seu próprio número de identificação e estratégia de distribuição de chamadas diferente. É nas equipes que são definidas as permissões do grupo: permissões de captura e permissões de saída de ligações.


Agentes: Agentes representam os colaboradores da empresa. Cada agente possui o seu próprio ramal, que poderá ter uma das seguintes tecnologias: SIP (telefones IP e softphones), WebRTC (navegador web) ou Microsoft Teams 1. Cada agente fará parte de uma equipe principal, e também poderá fazer parte de outras equipes como agente externo para receber chamadas que chegam por estas outras equipes.


1. Necessário ter a licença Office 365 Enterprise E3 (including SfB Plan2, Exchange Plan2, and Teams) + Phone System, ou Office 365 Enterprise E5 (including SfB Plan2, Exchange Plan2, Teams, and Phone System.



Operadoras: A plataforma Voice poderá se conectar com operadoras de 3 tipos:


  • SIP com autenticação
  • SIP sem autenticação
  • Microsoft Teams


Estas operadoras serão utilizadas nas configurações das permissões de saída e de entrada para realizar o roteamento das chamadas.


Permissões de saída: Nas permissões de saída é onde definimos os tipos de ligações de saída que poderão ser discados por uma certa equipe, e por quais operadoras esta ligação poderá completar.


Permissões de entrada: Nas permissões de entrada é onde podemos configurar o roteamento das chamadas que entram no Voice. Você poderá fazer o roteamento da ligação baseado em determinados horários e restringir os números de origem ao qual uma permissão se aplica.


Playlists e áudios: Gerencie as playlists do sistema fazendo upload de seus próprios áudios, ou baixando os áudios padrões da plataforma.




Primeiros passos


Neste guia vamos utilizar a API para construir o ambiente abaixo:


  • 2 Equipes 
  • 3 Agentes
  • 1 URA
  • 2 Operadoras: 1 SIP + 1 Microsoft Teams
  • 2 Permissões de saída: para fixo e celular
  • 1 Permissão de entrada: para rotear a chamada para a URA


A sequência dos passos será:







1. Autenticar na API


A autenticação da API é baseada nas credenciais de um dos agentes do SZChat. Para obtê-las iremos acessar o portal do SZChat e criar um agente. Ao cadastrar você receberá por e-mail um link para definir a senha deste agente:








Agora que você possui as credenciais de acesso à API, basta acessar a rota /voice/docs do seu ambiente, clicar em Authorize e inserir o usuário e senha:



Experimente utilizar o endpoint GET pbx/agent/all para listar os agentes disponíveis. Caso receba o código 200 como resposta e um lista vazia, significa que o seu acesso à API está funcionando normalmente. Caso receba um retorno diferente, verifique se as suas credenciais de acesso estão corretas e tente novamente:






2. Cadastrar as equipes


Agora utilize o endpoint POST pbx/campaigns para cadastrar as 2 equipes utilizando os payloads abaixo:



{
  "name": "Suporte PBX",
  "extension": "60",
  "ring_time": 30,
  "ring_type": "random",
  "allow_internal": true,
  "dialing_permissions": [
  ],
  "capture_permissions": [
  ],
  "ring_group": [
  ]
}



{
  "name": "Suporte SZ",
  "extension": "61",
  "ring_time": 30,
  "ring_type": "random",
  "allow_internal": true,
  "dialing_permissions": [
  ],
  "capture_permissions": [
  ],
  "ring_group": [
  ]
}






3. Cadastrar os agentes


Utilize o endpoint POST pbx/agent para cadastrar os agentes. No parâmetro campaign você precisará informar o ID da equipe ao qual o agente irá pertencer. No parâmetro email utilize endereços de e-mail válidos, pois após o cadastro o link de definição da senha do ramal do agente será encaminhado para este e-mail.  Utilize o endpoint GET pbx/campaigns/all para listar os IDs de todas das equipes cadastradas:



{
  "name": "Agente 1",
  "codename": "agente1",
  "extension": "1000",
  "email": "agente1@voicelight.com.br",
  "begin": "08:00",
  "end": "18:00",
  "campaign": "6477c7454f35c8001f4fb7a3",
  "tech": "sip",
  "country_code": "+55",
  "record_in": "on",
  "record_out": "on",
  "extension_lock": 0,
  "dtmf_mode": "rfc4733",
  "call_limit": 2,
  "user_password": 1234,
  "allowed_ips": "0.0.0.0/0"
}




{
  "name": "Agente 2",
  "codename": "agente2",
  "extension": "1001",
  "email": "agente2@voicelight.com.br",
  "begin": "08:00",
  "end": "18:00",
  "campaign": "6477c7904f35c8001f4fb7a5",
  "tech": "webrtc",
  "country_code": "+55",
  "record_in": "on",
  "record_out": "on",
  "extension_lock": 0,
  "dtmf_mode": "rfc4733",
  "call_limit": 2,
  "user_password": 1234,
  "allowed_ips": "0.0.0.0/0"
}





{
  "name": "Agente 3",
  "codename": "agente3",
  "extension": "8143",
  "email": "agente3@voicelight.com.br",
  "begin": "08:00",
  "end": "18:00",
  "campaign": "6477c7904f35c8001f4fb7a5",
  "tech": "msteams",
  "country_code": "+55",
  "record_in": "on",
  "record_out": "on",
  "extension_lock": 0,
  "dtmf_mode": "rfc4733",
  "call_limit": 2,
  "user_password": 1234,
  "allowed_ips": "0.0.0.0/0"
}



Para cada agente cadastrado, você receberá um e-mail para definição da senha de autenticação do ramal do agente:


Caso necessário utilize o endpoint POST pbx/agent/reset_password para reenviar o link de redefinição da senha do ramal do agente.





4. Testar os ramais

Após definir a senha de todos os ramais,  você poderá utilizá-los no softphone e no navegador:



Microsip

                                                Microsip



                                                Navegador


URL para logar no navegador: https://voicelight.sz.chat/voice/webrtc/login.php?username=RAMAL&password=SENHADORAMAL


Discando para *65 você deverá ouvir o número do ramal do agente.



5. Cadastrar as operadoras


Para cadastrar uma operadora SIP, utilize  o endpoint POST pbx/trunk com o payload abaixo, mudando o host e as credenciais de usuário e senha:


{
  "name": "Voip Fortics",
  "auth_type": 1,
  "carrier_type": "voip",
  "username": "xxxxx",
  "password": "yyyyy",
  "protocol": "sip",
  "dtmf_mode": "rfc4733",
  "codecs": [
    "alaw",
    "ulaw"
  ],
  "ip_host": "voip.myprovider.com.br",
  "call_limit": 30,
  "callerid_type": "fixed",
  "callerid_number": 30303030,
  "initial_did": 8100,
  "final_did": 8199,
  "enabled": 1,
  "tariffs_ids": []
}



Para integrar com o Microsoft Teams, adicione a operadora abaixo, , mudando o from_domain para o domínio correspondente ao seu SBC (normalmente com o valor <empresa>-voice.sz.chat). Em caso de dúvidas, entre em contato com nosso suporte.


{
    "name": "Ms Teams",
    "auth_type": 0,
    "carrier_type": "voip",
    "username": "",
    "password": "",
    "protocol": "msteams",
    "from_domain": "voicelight-voice.sz.chat",
    "dtmf_mode": "rfc4733",
    "codecs": [
      "alaw",
      "ulaw"
    ],
    "ip_host": "sip.pstnhub.microsoft.com",
    "call_limit": 0,
    "callerid_type": "fixed",
    "callerid_number": 0,
    "initial_did": 0,
    "final_did": 0,
    "enabled": 1,
    "tariffs_ids": []
  }




6. Cadastrar as permissões de saída


Utilize o endpoint POST pbx/outcalls para cadastrar as permissões de saída. O campo trunk_id deverá ser o ID da operadora Voip cadastrada anteriormente.


  • Fixo local   


{
  "name": "Fixo local",
  "number_format": "[2-5]XXXXXXX",
  "enabled": 1,
  "time_group_id": null,
  "transhipments": [
    {
      "type": "main",
      "trunk_id": "64790c4d4f35c8001f4fb7ae",
      "del_initial_digits": 0,
      "add_digits_before": "",
      "add_digits_after": ""
    }
  ]
}



  • Celular local  


{
  "name": "Celular local",
  "number_format": "9XXXXXXXX",
  "enabled": 1,
  "time_group_id": null,
  "transhipments": [
    {
      "type": "main",
      "trunk_id": "64790c4d4f35c8001f4fb7ae",
      "del_initial_digits": 0,
      "add_digits_before": "",
      "add_digits_after": ""
    }
  ]
}




1. O roteamento de chamadas entre a plataforma Voice e o Microsoft Teams não depende do cadastro de permissões de saída, pois a discagem para ramais do Microsoft Teams funciona como uma ligação interna no Voice. 

2. Utilize os campos del_initial_digits, add_digits_before e add_digits_after para manipular o número antes de enviá-lo para a operadora.




7. Associar as permissões de saída em cada equipe


Agora que você criou as permissões de saída, liste as equipes existentes e depois use o endpoint PUT pbx/campaigns para associar estas permissões às equipes para que elas possam realizar ligações externas:


  • Listando as equipes existentes (GET pbx/campaigns/all)



  • Atualizando as equipes existentes para associar as novas permissões



{
    "_id": "6477c7454f35c8001f4fb7a3",
    "name": "Suporte PBX",
    "extension": "60",
    "ring_time": 30,
    "ring_type": "random",
    "allow_internal": true,
    "dialing_permissions": ["6479f8204f35c8001f4fb7b2","6479f8914f35c8001f4fb7b3"],
    "capture_permissions": [],
    "ring_group": [
      {
        "agent_id": "64789f9a4f35c8001f4fb7a7",
        "is_muted": false,
        "order": 1
      }
    ]
  }



  {
    "_id": "6477c7904f35c8001f4fb7a5",
    "name": "Suporte SZ",
    "extension": "61",
    "ring_time": 30,
    "ring_type": "random",
    "allow_internal": true,
    "dialing_permissions": ["6479f8204f35c8001f4fb7b2","6479f8914f35c8001f4fb7b3"],
    "capture_permissions": [],
    "ring_group": [
      {
        "agent_id": "6478a0fc4f35c8001f4fb7a9",
        "is_muted": false,
        "order": 1
      },
      {
        "agent_id": "6478a13d4f35c8001f4fb7ab",
        "is_muted": false,
        "order": 2
      }
    ]
  }



Teste os ramais realizando uma discagem externa para fixo ou móvel.



8. Fazendo upload dos áudios que serão utilizados na URA


Para fazer o upload dos áudios utilize o endpoint POST pbx/audios. Os áudios deverão possuir os formatos wav ou mp3, e ter o tamanho máximo de 20MB.


Todos os áudios que vão ser utilizados pela URA deverão ser importados para a playlist Sistema. Neste caso você precisará listar as playlists existentes para obter o ID da playlists Sistema e só então fazer a importação. 


Você pode utilizar o site https://voicemaker.in/ para criar áudios personalizados gratuitamente utilizando TTS (Text to Speech).


  •  Listagem das playlists:



Diferente de outras plataformas, o Voice vai aceitar qualquer variante do formato WAV (stereo, mono, diferentes frequências, etc), pois no momento do upload será feita a conversão para o formato nativo: WAV mono 8khz.


  • Importação dos áudios para a playlist "Sistema":





9. Cadastrar a URA


Utilize o payload abaixo para cadastrar uma URA com as segunites características:


Nome: Fluxo de exemplo com 2 menus

Número da URA: 01 

Mensagem inicial: voice-menu-inicial

Número máximo de repetições: 2

Desvio caso o máximo de tentativas seja atingido: 61

Mensagem em caso de timeout: voice-desculpe-nao-entendi

Mensagem em caso de opção inválida: voice-desculpe-nao-entendi

Redirecionamento ao apertar 1: Equipe 60

Redirecionamento ao apertar 2: Equipe 61



{
      "name": "Fluxo de exemplo com 2 menus",
      "flow_id": "01",
      "flow": [
        {
          "component": "menu",
          "tts": false,
          "message": "",
          "language": "pt-br",
          "number_id": "001",
          "name": "Menu inicial",
          "direct_access": true,
          "audio_messages": [
            "647ce662a221e4e2a4a360bc"
          ],
          "limit_chars": 1,
          "next_component": null,
          "group_hours": {
            "continue": null,
            "exit": null
          },
          "max_attempts": {
            "value": 2,
            "redirect": "01002",
            "timeout_between_attempts": 5,
            "audios_on_retry": [
              "647ce66240a48cd3bccd0111"
            ],
            "audios_on_invalid": [
              "647ce66240a48cd3bccd0111"
            ]
          },
          "options": [
            {
              "num": 1,
              "description": "Suporte PBX",
              "redirect": "60"
            },
            {
              "num": 2,
              "description": "Suporte SZ",
              "redirect": "61"
            }
          ]
        },
        {
          "component": "menu",
          "tts": false,
          "message": "",
          "language": "pt-br",
          "number_id": "002",
          "name": "Mensagem final",
          "direct_access": false,
          "audio_messages": [
            "647cee579e76bea52c1508d5"
          ],
          "limit_chars": 1,
          "next_component": null,
          "group_hours": {
            "continue": null,
            "exit": null
          },
          "max_attempts": {
            "value": 1,
            "redirect": null,
            "timeout_between_attempts": 1,
            "audios_on_retry": [
            ],
            "audios_on_invalid": [
            ]
          },
          "options": [
          ]
        }
      ]
    }




Atualmente a versão Voice Lite conta com apenas com o componente menu na URA, porém outros componentes serão criados posteriormente como equipe, nota de atendimento, etc.



10. Cadastrar as permissões de entrada


As permissões de entrada vão possibilitar o roteamento das chamadas que chegam da operadora para dentro de algum componente do Voice como uma equipe ou URA. No exemplo abaixo vamos rotear todas as ligações de todos os DDRs para o componente menu (01001) da URA com o endpoint POST pbx/incalls desta maneira:


{
  "name": "IN DDRs",
  "did": "_.",
  "dst": "01001",
  "enabled": 1,
  "tags": [],
  "source_numbers": [],
  "trunk_id": "64790c4d4f35c8001f4fb7ae",
  "route_by_time": []
}



Agora basta ligar no número da operadora e ouvir a URA.