English

Português

English

Português

Appearance

Tutorial de Integração Asterisk com SipPulse AI ​

Este tutorial completo vai mostrar como configurar a integração entre um servidor Asterisk e os serviços SipPulse AI, permitindo recursos como transcrição de chamadas e agentes de voz.

Índice ​

  1. Visão Geral
  2. Pré-requisitos
  3. Configuração do PJSIP (trunk-ai)
  4. Configuração do extensions.conf
  5. Script de Transcrição
  6. Configuração de Agente de Voz
  7. Testes e Verificação
  8. Solução de Problemas

1. Visão Geral ​

A integração entre o Asterisk e o SipPulse AI permite:

  • Encaminhar chamadas do Asterisk para os agentes de voz do SipPulse AI
  • Transcrever chamadas gravadas usando a API do SipPulse AI
  • Realizar chamadas de saída para clientes através do agente de voz AI
  • Enviar parâmetros adicionais para personalizar as chamadas

2. Pré-requisitos ​

  • Servidor Asterisk configurado (versão 16+ recomendada com suporte PJSIP)
  • Conta ativa no SipPulse AI com um agente de voz configurado
  • Acesso root ao servidor Asterisk
  • Diretório para gravações configurado e acessível (/var/spool/asterisk/recordings/)
  • Python 3 instalado para o script de transcrição

3. Configuração do PJSIP (trunk-ai) ​

Primeiro, vamos configurar o trunk SIP para o SipPulse AI em /etc/asterisk/pjsip.conf:

;;; Transporte UDP padrão ;;;
[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0
external_media_address=<seu_ip_externo>  ; Opcional: apenas se atrás de NAT
external_signaling_address=<seu_ip_externo>  ; Opcional: apenas se atrás de NAT

;;; Configuração Trunk SipPulse AI ;;;
[trunk-ai]
type=registration
outbound_auth=trunk-ai-auth
server_uri=sip:sip.sippulse.ai:5060
client_uri=sip:<seu_número>@sip.sippulse.ai:5060  ; Substitua com seu número formato E.164
retry_interval=60

[trunk-ai-auth]
type=auth
auth_type=userpass
password=<sua_senha>  ; Substitua pela senha criada no SipPulse AI
username=<seu_usuário>  ; Substitua pelo usuário criado no SipPulse AI

[trunk-ai-aor]
type=aor
contact=sip:sip.sippulse.ai:5060
qualify_frequency=60

[trunk-ai]
type=endpoint
context=from-ai  ; Contexto que lidará com chamadas recebidas do SipPulse AI
disallow=all
allow=ulaw
allow=alaw
allow=g729
dtmf_mode=rfc4733
direct_media=no
ice_support=no
outbound_auth=trunk-ai-auth
aors=trunk-ai-aor

[trunk-ai]
type=identify
endpoint=trunk-ai
match=sip.sippulse.ai

4. Configuração do extensions.conf ​

Baseado na configuração fornecida, vamos ajustar o arquivo /etc/asterisk/extensions.conf para integrar corretamente com o SipPulse AI:

[globals]
OPERATOR = PJSIP/e1
RECORDING_DIR = /var/spool/asterisk/recordings

[from-siptrunk]
exten => 9999,1,Dial(${OPERATOR},20)

[from-internal]
exten => 6000,1,Dial(PJSIP/e1,20)
exten => 6001,1,Dial(PJSIP/e2,20)

; Chamadas de saída para PSTN
exten => _9.,1,NoOp(--- Outbound PSTN Call Starting with 9 ---)
exten => _9.,2,Set(ORIGINAL_EXTEN=${EXTEN})
exten => _9.,3,Set(CALLERID(num)=${FILTER(0-9,${CALLERID(num)})})
exten => _9.,4,Set(MIXMONITOR_FILENAME=${RECORDING_DIR}/${UNIQUEID}.wav)
exten => _9.,5,MixMonitor(${MIXMONITOR_FILENAME})
exten => _9.,6,Dial(PJSIP/${EXTEN:1}@trunk-sip,20,gr)
exten => _9.,7,Hangup()

; Manipulador de hangup para transcrição
exten => h,1,NoOp(Stopping MixMonitor to ensure file is complete)
exten => h,2,StopMixMonitor
exten => h,3,NoOp(Delaying execution to ensure file is fully written...)
exten => h,4,System(/bin/sh -c 'sleep 3 && /usr/bin/python3 /var/lib/asterisk/agi-bin/sippulse_transcription.py "${MIXMONITOR_FILENAME}" "${CALLERID(num)}" "${ORIGINAL_EXTEN}" "${CALLERID(name)}" > /var/log/asterisk/python_script.log 2>&1 &')

; Chamadas diretas para o SipPulse AI Voice Agent
exten => 2488770,1,Dial(PJSIP/+1209${EXTEN}@trunk-ai,20,tT)
; Exemplo de padrão para números com prefixo específico
exten => _*5548333285XX,1,Dial(PJSIP/${EXTEN}@trunk-ai,20,tT)

; Contexto para chamadas recebidas do SipPulse AI
[from-ai]
exten => _.,1,NoOp(--- Incoming call from SipPulse AI ---)
exten => _.,2,Answer()
exten => _.,3,Wait(1)
exten => _.,4,Playback(tt-monkeys)
exten => _.,5,Hangup()

5. Script de Transcrição ​

Crie o script de transcrição em /var/lib/asterisk/agi-bin/sippulse_transcription.py:

python
#!/usr/bin/env python3
import sys
import requests
import os
import json
import base64

# Argumentos da linha de comando
recording_filename = sys.argv[1]
caller_number = sys.argv[2]
called_number = sys.argv[3]
caller_name = sys.argv[4]

# Configuração da API SipPulse
API_KEY = "sua_api_key_aqui"
API_ENDPOINT = "https://api.sippulse.ai/transcription"

def main():
    # Verificar se o arquivo existe
    if not os.path.exists(recording_filename):
        log_error(f"Arquivo de gravação não encontrado: {recording_filename}")
        return
    
    # Verificar tamanho do arquivo (para evitar enviar arquivos vazios)
    file_size = os.path.getsize(recording_filename)
    if file_size < 1024:  # Menor que 1KB
        log_error(f"Arquivo muito pequeno ({file_size} bytes), possivelmente vazio ou corrompido")
        return
    
    try:
        # Preparar metadados
        metadata = {
            "caller_number": caller_number,
            "called_number": called_number,
            "caller_name": caller_name,
            "call_id": os.path.basename(recording_filename).replace(".wav", "")
        }
        
        # Enviar arquivo para transcrição
        with open(recording_filename, 'rb') as audio_file:
            files = {
                'audio': (os.path.basename(recording_filename), audio_file, 'audio/wav'),
                'metadata': (None, json.dumps(metadata), 'application/json')
            }
            headers = {
                'Authorization': f'Bearer {API_KEY}'
            }
            
            response = requests.post(API_ENDPOINT, files=files, headers=headers)
            
            # Verificar resposta
            if response.status_code == 200:
                result = response.json()
                log_success(f"Transcrição enviada com sucesso. ID: {result.get('id')}")
            else:
                log_error(f"Erro ao enviar transcrição: {response.status_code} - {response.text}")
    
    except Exception as e:
        log_error(f"Exceção durante envio da transcrição: {str(e)}")

def log_success(message):
    with open("/var/log/asterisk/transcription_success.log", "a") as log_file:
        log_file.write(f"{message}\n")

def log_error(message):
    with open("/var/log/asterisk/transcription_error.log", "a") as log_file:
        log_file.write(f"{message}\n")

if __name__ == "__main__":
    main()

Não se esqueça de tornar o script executável:

chmod +x /var/lib/asterisk/agi-bin/sippulse_transcription.py

6. Configuração de Agente de Voz ​

Para configurar um Voice Agent no SipPulse AI que se conectará ao seu Asterisk:

  1. Acesse o painel do SipPulse AI e vá para a seção "Voice Agent"
  2. Crie um novo agente de voz ou configure um existente
  3. Na configuração SIP do agente, configure:

Para receber chamadas do Asterisk (Inbound Trunk):

  • Destination URI: sip:sip.sippulse.ai
  • Port: 5060
  • Number: Seu número em formato E.164 (ex: +5548333285XX)
  • Allowed IP Addresses: IP público do seu servidor Asterisk
  • Enable Authentication: Yes
  • Username: Crie um nome de usuário único
  • Password: Crie uma senha forte

Para fazer chamadas para o Asterisk (Outbound Trunk):

  • Address: sip:seu_ip_ou_dominio_do_asterisk:5060
  • Number: Número que será mostrado como origem das chamadas
  • Enable Authentication: Se necessário
  • Username: Se necessário
  • Password: Se necessário

7. Testes e Verificação ​

Verificar o Status da Conexão SIP: ​

asterisk -rx "pjsip show endpoints"
asterisk -rx "pjsip show registrations"

O endpoint trunk-ai deve aparecer como "Registered" se a conexão estiver funcionando corretamente.

Testar Chamada para o Agente de Voz: ​

Disque 2488770 de uma extensão interna para testar a conexão com o agente de voz do SipPulse AI.

Verificar Logs: ​

tail -f /var/log/asterisk/full
tail -f /var/log/asterisk/python_script.log
tail -f /var/log/asterisk/transcription_*.log

Testar Chamada de Saída do Agente de Voz: ​

Para realizar uma chamada de saída através da API do SipPulse AI, você pode usar:

bash
curl -X POST "https://api.sippulse.ai/bots/{id}/outbound-call" \
  -H "Authorization: Bearer {sua_api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "+5511999999999",
    "initial_text": "Olá, esta é uma chamada de teste do SipPulse AI.",
    "additional_instructions": "{\"cliente_nome\":\"João Silva\",\"id_pedido\":\"12345\"}",
    "activation_threshold": 3.5
  }'

Substitua {id} pelo ID do seu agente de voz e {sua_api_key} pela sua chave de API.

8. Solução de Problemas ​

Problemas de Registro SIP: ​

Se o trunk não estiver registrando:

asterisk -rx "pjsip set logger on"

Verifique os logs para ver detalhes do problema:

tail -f /var/log/asterisk/full

Problemas com Chamadas de Entrada/Saída: ​

  1. Verifique se o contexto correto está sendo usado
  2. Confirme que o endereço IP do seu servidor está na lista de IPs permitidos no SipPulse AI
  3. Verifique as configurações de firewall:
    ufw status
iptables -L
    Certifique-se de que as portas 5060 (SIP) e 10000-20000 (RTP) estão abertas

Problemas com Transcrição: ​

  1. Verifique se o arquivo de áudio está sendo criado corretamente:
    ls -la /var/spool/asterisk/recordings/
  2. Verifique os logs do script:
    cat /var/log/asterisk/transcription_error.log
  3. Teste o script manualmente:
    python3 /var/lib/asterisk/agi-bin/sippulse_transcription.py "/var/spool/asterisk/recordings/exemplo.wav" "5511999999999" "5522999999999" "Nome Teste"

Conclusão ​

A integração do Asterisk com o SipPulse AI oferece recursos avançados como transcrição automática de chamadas e agentes de voz inteligentes. As configurações acima permitem que seu Asterisk se comunique de forma eficiente com a plataforma SipPulse AI, habilitando recursos de IA para sua central telefônica.

Para mais informações e recursos avançados, consulte a documentação oficial do SipPulse AI em https://docs.sippulse.ai.