Laboratório: Integração de Asterisk com SuiteCRM via Webhook REST para registro automático de chamadas

Duração estimada

120 min

Passos

12

Validações

4

Versões da documentação consultada

Asterisk 20 (consulte a documentação) · SuiteCRM 8.x (consulte a documentação) · Linphone a versão estável atual

Topologia

Três VMs em uma rede privada: (1) Asterisk (IP 192.168.56.10), (2) SuiteCRM (IP 192.168.56.20), (3) um softphone (IP 192.168.56.30). O Asterisk recebe ligações do softphone e, ao atender, dispara um webhook para o SuiteCRM registrar a atividade.

+-----------+         +-------------+         +----------+
| Softphone | <-----> |  Asterisk   | <-----> | SuiteCRM |
|192.168.56.30|       |192.168.56.10|         |192.168.56.20|
+-----------+         +-------------+         +----------+

Equipamentos e software

Roteiro

1. Preparar as VMs e rede privada

   Crie três VMs em uma rede privada (NAT ou bridge), com IPs fixos 192.168.56.10 (Asterisk), 192.168.56.20 (SuiteCRM), 192.168.56.30 (Softphone).

   O que você deve ver: Todas as VMs se pingam mutuamente.

2. Instalar o Asterisk

   No Debian, instale o Asterisk pelo repositório oficial. O Asterisk é o PBX de código aberto mais usado no mundo.

   sudo apt update && sudo apt install asteriskCopiar

   O que você deve ver: Asterisk instalado. Serviço ativo: systemctl status asterisk

3. Configurar ramal SIP no Asterisk

   Crie um ramal SIP para o softphone. Isso permite que o softphone registre e faça chamadas.

   Edite /etc/asterisk/pjsip.conf e adicione:
   
   [6001]
   type=endpoint
   aor=6001
   auth=6001
   context=from-internal
   
   [6001]
   type=aor
   max_contacts=1
   
   [6001]
   type=auth
   auth_type=userpass
   password=senha123
   username=6001Copiar

   O que você deve ver: Arquivo salvo sem erros de sintaxe.

4. Recarregar configuração do Asterisk

   Aplique as alterações sem reiniciar o serviço.

   sudo asterisk -rx 'pjsip reload'Copiar

   O que você deve ver: Mensagem de reload concluído.

5. Instalar e configurar o Linphone

   No softphone, instale o Linphone e configure o usuário SIP 6001 apontando para 192.168.56.10.

   sudo apt install linphoneCopiar

   O que você deve ver: Linphone instalado. Conta SIP registrada.

6. Instalar o SuiteCRM

   No Debian, instale Apache, PHP (consulte a documentação para a versão), MariaDB e SuiteCRM. O SuiteCRM será o repositório das interações.

   sudo apt install apache2 mariadb-server php php-mysql php-xml php-mbstring
   # Baixe e extraia o SuiteCRM
   # Consulte https://docs.suitecrm.com/admin/installation-guide/download-suitecrm/ para instruções detalhadasCopiar

   O que você deve ver: SuiteCRM acessível em http://192.168.56.20

7. Criar usuário API no SuiteCRM

   No SuiteCRM, crie um usuário dedicado para integração API. Isso é necessário para autenticação segura dos webhooks.

   Acesse o painel de administração do SuiteCRM, crie usuário 'asterisk_api' com senha forte.Copiar

   O que você deve ver: Usuário criado e ativo.

8. Configurar endpoint REST para registrar chamadas

   No SuiteCRM, habilite o módulo API REST v8. Crie um endpoint customizado para registrar chamadas. Consulte a documentação para detalhes de customização.

   Consulte https://docs.suitecrm.com/developer/api/api-8/ para criar endpoints customizados.Copiar

   O que você deve ver: Endpoint REST disponível para POST em /Api/V8/module/Calls

9. Criar script AGI para disparo de webhook

   No Asterisk, crie um script shell ou Python em /var/lib/asterisk/agi-bin/ que faça POST para o endpoint do SuiteCRM ao receber ligação.

   Exemplo de script shell:
   
   #!/bin/bash
   CALLERID="$1"
   curl -u asterisk_api:senha_do_usuario -X POST \
     -H 'Content-Type: application/json' \
     -d '{"name": "Chamada de $CALLERID", "status": "Planned"}' \
     http://192.168.56.20/Api/V8/module/CallsCopiar

   O que você deve ver: Script salvo e com permissão de execução.

10. Configurar dialplan para executar AGI

    No /etc/asterisk/extensions.conf, adicione lógica para executar o script AGI ao receber chamadas.

    [from-internal]
    exten => 6001,1,Answer()
    exten => 6001,n,AGI(agi_registra_chamada.sh,${CALLERID(num)})
    exten => 6001,n,Hangup()Copiar

    O que você deve ver: Dialplan salvo sem erros.

11. Recarregar dialplan

    Aplique as alterações do dialplan.

    sudo asterisk -rx 'dialplan reload'Copiar

    O que você deve ver: Dialplan reloaded.

12. Testar chamada e integração

    Do Linphone, ligue para 6001. O Asterisk deve executar o script e registrar a chamada no SuiteCRM.

    O que você deve ver: Chamada recebida. Nova atividade de chamada aparece no SuiteCRM.

Como saber que funcionou

Troubleshooting

Segurança e hardening

• Use senhas fortes para todos os usuários, especialmente o usuário API do SuiteCRM
• Restrinja o acesso à porta SIP (5060/UDP) apenas à rede interna
• Garanta que o endpoint REST do SuiteCRM só aceite conexões autenticadas
• Scripts AGI não devem conter senhas em texto claro em ambientes de produção
• Revise permissões dos arquivos de configuração e scripts para evitar execução não autorizada

Checklist final

• VMs configuradas e se comunicando na rede privada
• Asterisk instalado e com ramal SIP funcional
• SuiteCRM acessível via navegador
• Usuário API criado no SuiteCRM
• Script AGI criado e executável
• Chamada registrada automaticamente no SuiteCRM