FreePBX, Asterisk 16 e Interface RESTful do Asterisk (ARI)

Sejam muito bem-vindos a mais uma postagem do site FreePBX Brasil, esta documentação vai lhe auxiliar a fazer as configurações para uso do ARI no FreePBX.

O intuito deste é contribuir com a comunidade auxiliando para execução discagens via API, um caso comum é quem faz o uso de discadores, que normalmente usam os famosos “aquivo.call” e/ou AMI para efetuar as discagens, ambos funcionam muito bem, mas fazendo uso de RESTful você vai dar um upgrade na sua aplicação.

A Interface RESTful do Asterisk (ARI) é uma API assíncrona que permite aos desenvolvedores construir aplicativos de comunicação no asterisk, fazendo uso de objetos por meio de eventos JSON e WebSocket, o ARI está no asterisk a partir da versão 12.

Antes de seguir, vale ressaltar que se caso identificar algum problema ou erro neste post, não deixe de nos reportar, o feedback é de suma importância para dar ainda mais qualidade aos conteúdos do site.

Laboratório:

  1. FreePBX 15;
  2. Asterisk 16;
  3. Insomnia - Versão free.

Vamos iniciar as configurações no FreePBX, primeiro criar o usuário RESTful.

Em seguida salve e aplique!

A seguir será necessário ir nas configurações avançadas para habilitar o WebService do FreePBX para aceitar as requisições para o ARI.

Acima apresenta as configurações avançadas do FreePBX, aonde será configurado habilitando o WebService para as requisições de interação com o nosso core de telefonia, lembrando que estas configurações feitas via GUI do FreePBX são somente para interações com o asterisk. Lembre-se, qualquer alteração via GUI do FreePBX faz necessário logo em seguida salvar e aplicar, usando o "Submit" e o "Apply"!

Agora que já foi criado o usuario da API e habilitado o serviço de WebService, será necessário identificar se de fato temos o ARI ativo em nosso asterisk, vamos ao CLI. 

[root@freepbx15 ~]# rasterisk -vvvvvvvcgi
Asterisk 16.4.1, Copyright (C) 1999 - 2018, Digium, Inc. and others.
Created by Mark Spencer 
Asterisk comes with ABSOLUTELY NO WARRANTY; type 'core show warranty' for details.
This is free software, with components licensed under the GNU General Public
License version 2 and other licenses; you are welcome to redistribute it under
certain conditions. Type 'core show license' for details.
=========================================================================
Connected to Asterisk 16.4.1 currently running on freepbx15 (pid = 2212)
freepbx15*CLI> ari show 
app     apps    status  user    users   
freepbx15*CLI>

No CLI digitando ari show e pressionando a tecla TAB será apresentado algumas opções que estão disponiveis para consulta, a seguir consultaremos os usuarios ativos ARI, status do serviço e se o WebService está ativo. 


freepbx15*CLI> ari show users
r/o?  Username
----  --------
No    freepbxuser
No    kowalski

freepbx15*CLI>


freepbx15*CLI> ari show status 
ARI Status:
Enabled: Yes
Output format: compact
Auth realm: Asterisk REST Interface
Allowed Origins: *
User count: 2

freepbx15*CLI>


freepbx15*CLI> http show status 
HTTP Server Status:
Prefix: 
Server: Asterisk/16.4.1
Server Enabled and Bound to 0.0.0.0:8088

Enabled URI's:
/httpstatus => Asterisk HTTP General Status
/static/... => Asterisk HTTP Static Delivery
/ari/... => Asterisk RESTful API
/ws => Asterisk HTTP WebSocket

Enabled Redirects:
  None.

freepbx15*CLI>

Aqui observamos que nos serviços WEB do asterisk temos o ARI ativo, a linha "/ari/... => Asterisk RESTful API" os demais podemos abordar em um outro post. Idetificado que as configurações estão corretas com o ARI, será necessário agora, no asterisk criar um contexto para os testes. 

vim /etc/asterisk/extensions_custom.conf
[freepbxbrasil]

exten => 1000,1,NoOp( ..:: ------------------------- )
 same =>      n,NoOp( ..:: Comunidade FreePBX Brasil )
 same =>      n,NoOp( ..:: Prof. Kowalski )
 same =>      n,NoOp( ..:: ------------------------- )
 same =>      n,Hangup()

Em seguida saia do vim salvando, vou pode usar o ":wq" ou ":x" que acho mais prático, após contexto criado e salvo, será necessario recarrega-lo , por que até então o asterisk não reconhece o mesmo, no CLI digite dialplan reload, para ter certeza que o contexto existe, certique usando o comando abaixo. 

freepbx15*CLI> dialplan show freepbxbrasil 
[ Context 'freepbxbrasil' created by 'pbx_config' ]
  '1000' =>         1. NoOp( ..:: ------------------------- )     [extensions_custom.conf:3]
                    2. NoOp( ..:: Comunidade FreePBX Brasil )     [extensions_custom.conf:4]
                    3. NoOp( ..:: Prof. Kowalski )                [extensions_custom.conf:5]
                    4. NoOp( ..:: ------------------------- )     [extensions_custom.conf:6]
                    5. Hangup()                                   [extensions_custom.conf:12]

-= 1 extension (5 priorities) in 1 context. =-
freepbx15*CLI>

Pronto, agora está certificado que o contexto existe, agora será feito uma requisição API que vamos executa-lo e apresentar essas mensagens no console, para isso vamos usar o Insomnia na versão free, este muito usado para testes de rotas de API, assim como POSTMAN e muitos outros.

Este que será usado uma requisição POST, conforme orienta a documentação oficial do asterisk que ao término deste deixarei explicíto.

Acima em ❶ temos criado a nossa requisição de API do tipo "POST", seguindo a documentação do ari no site oficial do asterisk, que ao final informo o link. Em ❷ a requisição da api com os devidos parâmetros este que detalho a seguir, em ❸ aonde ao clicar será enviado sua requisição, em ❹ é um dos pontos mais importante deste processo, o codigo de retorno HTML, neste caso está como "200 OK" ou seja nossa requisição foi executar e o retorno foi sucesso, se o retorno for direfente disso, valide na documentação da API que na maioria das vezes alguns códigos de retornos são mapeados e documentados para lhe auxiliar em problemas.

Explicando item ❷ , para ficar de facíl entendimento, será colocado a url e vamos particiona-la para explicar cada parte da mesma.

URL = http://kowalski:freepbxbrasil@192.168.200.24:8088/ari/channels?endpoint=Local/1000@freepbxbrasil&extension=1000&context=freepbxbrasil&priority=1&callerid=9000

Dados de autentição da API:
User ➜ kowalski
Password ➜ freepbxbrasil
IP do Server ➜ 192.168.200.24
Porta do WebService ➜ 8088

Dados do Asterisk baseado na documentação oficial:
channels ➜ Rota da API ARI
endpoint ➜ O canal usado para comunicação interna com o asterisk
extension ➜ Extensão criada no nosso contexto
freepbxbrasil ➜ Contexto criado para homologação conforme acima.
priority ➜ a nivel de dialplan estamos iniciando nesta posição do contexto
callerid ➜ o callerid que vamos utilizar para essa requisição

Agora com as informações acima validada, já pode ser feita a requisição via insomnia e o retorno deve ser um "200 OK", acompanhe no seu asterisk via terminal (CLI), abaixo um exemplo de quando o asterisk recebe a requisição via ARI.

Acima temos o retorno de quando a requisição foi executada com sucesso, assim como o contexto do asterisk como esperado.

Pronto, agora que você aprendeu o básico de usabilidade do recurso ARI que tem disponível em seu asterisk, aproveite que este assim como muitos outros recursos no asterisk fazem o diferencial na solução de telefonia.

A seguir vou documentar as referências utilizadas nesta documentação, obrigado e até a próxima.

1- Asterisk REST Interface (ARI)
2- Introduction to ARI and Channels
3- Asterisk 16 Channels REST API
4- Local Channel


"Começar é a parte mais importante de qualquer trabalho" - Platão


     

Instale o dongle no seu FreePBX 14 e Asterisk 13


Sejam muito bem-vindos a mais uma postagem do site freepbx brasil. Esta documentação vai lhe auxiliar a fazer a instalação do seu modem Dongle e utilizar para receber e efetuar ligações no freepbx. Antes de qualquer coisa não deixe de colaborar com conteúdos para alimentar essa base de conhecimentos. Vamos ao trabalho!

Laboratório:

  1. FreePBX 14;
  2. Asterisk 13;
  3. Dongle: Modelo E1553;
  4. Modulo Dongle: Huawei 3G Dongle Channel Driver, Version 1.1, Revision 43gh=47cg

[ Processo de Instalação ]

yum install asterisk13-devel automake git -y
git clone https://github.com/wdoekes/asterisk-chan-dongle.git
cd asterisk-chan-dongle
./bootstrap
./configure --with-astversion=13.32.0
Obs.: --with-astversion=13.32.0 onde "13.32.0" será a versão do seu asterisk
make
make install
fwconsole restart
chown asterisk:asterisk /etc/asterisk/dongle.conf
chmod 755 /etc/asterisk/dongle.conf
asterisk -rx "dongle show devices"
echo 'KERNEL=="ttyUSB*", MODE="0666", OWNER="asterisk", GROUP="dialout"'>/etc/udev/rules.d/92-dongle.rules
Obs.: A linha acima, fique atento que estamos exectando um echo no conteúdo para dentro do arquivo. Se dentro do diretório do seu asterisk (Caminho: /etc/asterisk/) não existir o arquivo "dongle.conf", faça o download aqui do arquivo pronto, só ajustar para o seu ambiente.

aviso Se no momento de rodar o "MAKE" se deparar com o erro:
smsdb.c:26:21: fatal error: sqlite3.h: No such file or directory #include

Rode o seguinte comando: yum install libsqlite3x-devel -y

Agora partindo do principio que o processo de instalação foi finalizado com sucesso, antes seguir para as configurações no painel do seu freepbx, vamos fazer alguns ajustes no arquivo de configuração o "dongle.conf" para que seu Laboratório funcione perfeitamente. 

[root@freepbxbrasil ~]# vim /etc/asterisk/dongle.conf




[root@freepbxbrasil ~]# asterisk -rx "dongle show devices"

Obs.: O comando acima você identifica o status do seu dongle,com informações da operadora, IMEI do chip e numero, antes de seguir precisa ter certeza que está tudo correto com os passos anteriores.

Agora vamos as configurações no freepbx.

No caminho: Connectivity ➔ Trunks

Opção: + Add Custom Trunk

Na guia "General" defina apenas o nome do tronco como "Dongle0".

Ainda na mesma tela de configuração, vá até a guia "custom Settings", adicione a seguinte linha: "Dongle/dongle0/$OUTNUM$" em seguinda pressione o Submit (Salvar) e apply (Aplicar).

Agora que já criou o tronco de saida das suas chamadas, precisamos configurar duas coisas para que funcione de fato, sua rota de saida e entrada, para receber e efetuar ligações.

No caminho: Connectivity ➔ Outbound Routes

Será configurada a rota de saída.

Opção: + Add Outbound Route

Na guia "Route Settings" defina o nome da sua rota de saída neste laboratório será "Saida Dongle" na mesma tela, penultima opção é a "Trunk Sequence for Matched Routes" aqui você define por qual tronco, essa rota que está criando vai sair com chamadas, neste caso vamos definir o tronco que foi criado dongle0, na mesma tela mas na guia "Dial Patterns" deve ser configurado as suas regras de discagens, vou descreva-las e também deixa a imagem abaixo pra ficar facil o entendimento. Vamos definir uma regra apenas para chamadas locais e DDD para movel(Celular) que seria "9XXXXXXXX" observe que estamos tratando apenas ligações que comecem com "Nove" mais oito digitos que somando tormam "nove digitos" exatamente uma discagem para celular local e para DDD adicionamos mais dois digitos, que deve ficar assim, "ZZ9XXXXXXXX", vale lembra que no caso de chamadas longa distância nacional, é necessario adicionar o codigo da operadora, no meu caso estou usando um chip da operadora vivo, logo a discagem pra longa distancia deve ser "015 + DDD + NumeroDestino."


No caso estamos usando o "ZERO" para efetuar uma chamada, com as regras de dialplan acima podem ser feitas chamadas tanto local quanto DDD, ligações para outro estado o usuario local não precisa colocar o código da operadora somente "0 + DDD + NumeroDestino". Após definir essas configurações salve e aplique, assim você deve conseguir efetuar chamadas de saida pelo seu modem.

No caminho: Connectivity ➔ Inbound Routes
Será configurada a rota de entrada, que pode direcionar para uma URA, Fila etc.

Opção: + Add Inbound Route

No campo "Description" defina uma descrição para sua rota de entrada, no campo "DID Number" adicione o numero do chip adicionado ao dongle que foi definido no campo exten=5511988775544 dentro do arquivo dongle.conf, coloque somente o numero "5511988775544", na mesma tela a ultima opção "Set Destination" você vai definir o destino que vai receber a chamada quando a ligação externa chegar pelo seu chip/dongle, em seguida salve e aplique as configurações, agora se seguiu atentamente os passos anteriores, já deve conseguir, receber e efetuar ligações usando o seu dongle.

Qualquer dúvida sobre modelos de modens compatíveis veja o link sobre requisitos e limitações.

Espero que essa documentação tenha lhe auxiliado, não deixe de nos enviar o seu feedback, até a proxima!

     

FreePBX 15 crie seu phonebook para seus aparelhos IP

Olá sejam muito bem-vindos a nosso primeiro post de 2020, antes de qualquer coisa não deixe de contribuir, nos envie seus materiais, assim faremos deste site um grande repositório de informações sobre FreePBX e tecnologias associadas para todos.

Este material auxiliará na criação de um phonebook(Lista de contatos) no seu FreePBX 15, desta forma seus aparelhos ip conseguem provisionar uma lista de contatos. Vamos lá?!

Laboratório:

  • Linux CentOS 7;
  • FreePBX 15.0.16.20;
  • TFTP;
  • Aparelho IP Yealink T21P E2 - Firmware: 52.80.0.3

Antes de iniciarmos, vale informar que neste laboratório foi feito o start do provisionamento manual na parte aparelho, assim o mesmo busca no repositorio do servidor seu arquivo de phonebook, mas para funcionar de forma automática, existe a necessidade de configurar o recurso option66 no DHCP server, basicamente a função deste é fazer com que todo novo dispositivo que subir na rede ele vai até o seu TFTP checar se existe algum tipo de configuração para aquele modelo. Essas configurações não se limita apenas a aparelhos da linha yealink, qualquer aparelho que tenha suporte a provisionamento pode-se fazer o uso deste método.

Primeiramente vamos preparar o terreno no lado do FreePBX com nosso arquivo de contatos para provisionamento e o principal, o arquivo de provisionamento do aparelho, este é o master, nele você define tudo que vai ser configurado no aparelho, aqui nao vamos abordar ele a fundo, somente a linha de provisionamento dos contatos, mostro abaixo e o arquivo usado no laboratório está disponivel($exemplo_mac.cfg) ,observe que o arquivo é estruturado pelo endereço mac do aparelho "$mac.cfg". 

 
    #to specify a XML phonebook for update
    #lan example for a right server_address:http://192.168.0.132:9/file_provision/contactData1.xml
    local_contact.data.url = tftp://192.168.1.88/phonebook/phonebook.xml

Abaixo o modelo de phonebook usando XML conforme o padrão aceito pelo aparelho.

Obs. Na dúvida defina as permissões no arquivo para usuario e grupo asterisk.

Agora nas configurações do yealink vamos setar o ip do servidor de TFTP.

Seguindo os passos da imagem acima, primeiro clique em "Settings > Auto Provision" no campo "Server URL" precisa adicionar o seu servidor que esta hospedado a sua lista de contatos, por fim clique em "Autoprovision Now", assim ele vai buscar de imediato no servidor o arquivo de provisionamento, faça isso.

Agora vamos conferir se a nossa lista de contatos foi provisionada, na imagem acima estamos checando pela GUI do aparelho, os contatos foram carregados com sucesso, agora quando algum ramal da sua lista ligar para o aparelho vai apresentar o nome do mesmo.

Espero que essa documentação possa lhe auxiliar, encerramos por aqui, até a proxima!