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