FreePBX / Asterisk

Diese Anleitung zeigt, wie Sie eine bestehende FreePBX-Telefonanlage (Asterisk / PJSIP) mit der One100 KI-Telefonassistent:in verbinden - inklusive ausgehender SIP-Verbindung, eingehender Anrufroute und optionalem Rück-Transfer (REFER) an eine interne Nebenstelle.

Was Sie in dieser Anleitung einrichten

• Einen SIP-Trunk von FreePBX zu One100 (IP-basiert, ohne Registrierung)
• Eine Outbound-Route, die Anrufe an die KI-Nummer über den One100-Trunk leitet
• Eine Inbound-Route (oder Direkt-DID via Dialplan), die eingehende Anrufe an die KI weiterleitet
• Einen REFER-Handler, damit die KI Anrufe an eine interne Nebenstelle übergeben kann ("mit Mensch verbinden")
• Caller-ID-Pass-Through via P-Asserted-Identity, damit die KI die echte Anrufer-Nummer sieht

Geplante Dauer: 45 bis 90 Minuten (je nach Komplexität Ihrer bestehenden Routen).

Was Sie vorher brauchen

• Eine funktionierende FreePBX-Anlage (getestet mit FreePBX 17, Asterisk 22, PJSIP)
• Admin-Zugang zur FreePBX-GUI und SSH/CLI-Zugriff auf den Asterisk-Server (für den Custom-Dialplan)
• Die öffentliche IP Ihrer FreePBX-Anlage
• Eine bestehende interne Nebenstelle (PJSIP-Endpoint), an die die KI Anrufe zurückgeben können soll

Einen aktiven One100-Account

So funktioniert das Setup im Überblick

Anrufer  ->  PSTN-/SIP-Provider  ->  FreePBX
                                       │
                                       │  Inbound-Route / Direkt-DID
                                       ▼
                            custom-call-one100 (Dialplan)
                                       │
                                       │  Outbound-Route -> One100-Trunk
                                       ▼
                              INVITE sip:+43999XXXX@sip-eu.one100.ai
                                       │
                                       ▼
                                 One100 KI nimmt entgegen

Wenn die KI "mit Mensch verbinden" sagt:
   One100  ->  REFER  Refer-To: sip:<Nebenstelle>@<Ihre-Public-IP>:25060
                                       │
                                       ▼
                              FreePBX dialt PJSIP/<Nebenstelle>

Sieben Bausteine müssen eingerichtet werden:

1.Vorbereitung mit One100

Bevor Sie in FreePBX etwas konfigurieren, koordinieren Sie drei Dinge mit dem One100-Team.

1.1 Custom Number anfordern

Das One100-Team weist Ihnen eine Custom Number zu, z.B. `+43999XXXX`. Diese ist die interne Kennung Ihrer KI-Telefonassistent:in im One100-System - keine PSTN-Nummer, kann nicht von außen direkt angerufen werden.

Sie brauchen die Custom Number in Schritt 2, 3 und 5 dieser Anleitung. Notieren Sie sich die Nummer.

1.2 PBX-IP an One100 schicken

Damit One100 nur Verbindungen von Ihrer eigenen PBX akzeptiert, müssen wir die öffentliche IP Ihrer Anlage in unsere Whitelist eintragen.

Senden Sie die Public-IP Ihrer FreePBX an support@one100.ai. Wir tragen sie in die Whitelist ein und bestätigen, sobald aktiviert.

1.3 transfer_to-Ziel für REFER festlegen

Wenn die KI Anrufe an eine reale Person übergeben soll ("mit Mensch verbinden"), schickt One100 einen SIP-REFER zurück an Ihre PBX. Das Refer-To-Ziel muss vorher im One100-Forward-Tool hinterlegt werden:

transfer_to: sip:<INTERNE-NEBENSTELLE>@<IHRE-PUBLIC-IP>:25060

Beispiel:
transfer_to: sip:1100@<IHRE-PUBLIC-IP>:25060

2.SIP-Trunk anlegen

In der FreePBX-GUI: Connectivity -> Trunks -> + Add Trunk -> Add SIP (chan_pjsip) Trunk.

2.1 General-Tab

2.2 pjsip-Settings -> General

2.3 pjsip-Settings -> Advanced

2.4 Codecs

• `alaw`
• `ulaw`
• `opus`

Submit -> Apply Config.

3.Outbound-Route anlegen

Connectivity -> Outbound Routes -> + Add Outbound Route.

4.Inbound-Route + Custom Destination

Wir brauchen zwei Dinge: eine Custom Destination, die in den `custom-call-one100`-Dialplan-Kontext springt, und eine Inbound-Route, die eingehende DIDs auf diese Destination zeigt.

4.1 Custom Destination anlegen

Admin -> Custom Destinations -> + Add:

4.2 Inbound-Route anlegen

Connectivity -> Inbound Routes -> + Add Inbound Route:

4.3 Optional: Direkt-DID über Dialplan-Pattern abfangen

Wenn Sie eine einzelne Durchwahl (z.B. interne `1100`, deren externe E.164-Form mit Ihrer Hauptnummer beginnt - also `<Hauptnummer-E.164>1100`) direkt an die KI routen wollen, ohne dafür eine eigene Inbound-Route anzulegen, übernehmen wir das in Schritt 5 im `from-pstn-custom`-Dialplan.

5.Custom-Dialplan

Der folgende Dialplan ist das Herzstück des Setups. Er macht drei Dinge:

• Normalisiert die ausgehende Caller-ID auf E.164 (so dass die KI die Nummer richtig sieht)
• Wählt die One100 Custom Number über den `one100_trunk`
• Empfängt REFERs von der KI und routet sie an die richtige interne Nebenstelle

5.1 extensions_custom.conf

Datei: `/etc/asterisk/extensions_custom.conf` (auf der FreePBX hinzufügen oder anhängen).

[from-pstn-custom]
; Optional: Direkt-DID 1100 (E.164 = <Hauptnummer-E.164>1100) -> KI
; Ersetzen Sie XXXXXXXXX durch Ihre Hauptnummer in E.164 ohne führendes "+":
exten => _43XXXXXXXXX1100,1,NoOp(Direkt-DID 1100 -> One100 KI)
exten => _43XXXXXXXXX1100,n,Set(__FROM_DID=${EXTEN})
exten => _43XXXXXXXXX1100,n,Goto(custom-call-one100,s,1)

; REFER-Forward von der KI: Refer-To sip:<Nebenstelle>@... -> direkt die PJSIP-Nebenstelle anrufen
exten => 1100,1,NoOp(REFER 1100 -> direkter Dial 210)
exten => 1100,n,Dial(PJSIP/210,30)
exten => 1100,n,Hangup()

; Sicherheitsnetz: Refer-To-Varianten, in denen One100 die Custom Number als User mitschickt
exten => _+43999XXXXX.,1,Goto(from-pstn-custom,1100,1)
exten => +43999XXXX,1,Goto(from-pstn-custom,1100,1)
exten => _43999XXXXX.,1,Goto(from-pstn-custom,1100,1)
exten => 43999XXXX,1,Goto(from-pstn-custom,1100,1)

[custom-call-one100]
exten => s,1,NoOp(Outbound zu One100 KI Agent +43999XXXX)
; Caller-ID nach E.164 normalisieren (00... -> +..., 0... -> +43...)
exten => s,n,ExecIf($["${CALLERID(num):0:2}"="00"]?Set(CALLERID(num)=+${CALLERID(num):2}))
exten => s,n,ExecIf($["${CALLERID(num):0:1}"="0" & "${CALLERID(num):0:2}"!="00"]?Set(CALLERID(num)=+43${CALLERID(num):1}))
exten => s,n,Set(CONNECTEDLINE(num)=${CALLERID(num)})
exten => s,n,Set(CONNECTEDLINE(name)=${CALLERID(num)})
; Falls die KI später ein REFER schickt: dessen Refer-To im from-pstn aufloesen
exten => s,n,Set(__TRANSFER_CONTEXT=from-pstn)
exten => s,n,Answer()
exten => s,n,Wait(1)
exten => s,n,Dial(PJSIP/+43999XXXX@one100_trunk,60)
exten => s,n,Hangup()

; Channel-Context-Variante des REFER-Handlers (PJSIP loest manchmal im Channel-Context auf)
exten => 1100,1,NoOp(REFER 1100 (Channel-Context) -> direkter Dial 210)
exten => 1100,n,Dial(PJSIP/210,30)
exten => 1100,n,Hangup()

5.2 pjsip.endpoint_custom_post.conf

Datei: `/etc/asterisk/pjsip.endpoint_custom_post.conf` (stellt sicher, dass `send_pai` und `trust_id_outbound` auch beim Reload erhalten bleiben):

; Caller-ID an One100 weitergeben (P-Asserted-Identity)
[one100_trunk](+)
send_pai=yes
trust_id_outbound=yes

5.3 Reload nach Änderungen

asterisk -rx 'dialplan reload'
asterisk -rx 'module reload res_pjsip.so'
# nach DB-/GUI-Änderungen zusätzlich:
fwconsole reload

6.Netzwerk / Firewall

Folgende Ports / Richtungen müssen auf Ihrer Firewall freigeschaltet sein:

7.Reload + Testanruf

7.1 Trunk-Status prüfen

asterisk -rx 'pjsip show endpoints' | grep one100

Status sollte `Avail` sein. Falls `Unavail`: prüfen Sie Whitelist (Schritt 1.2), Firewall (Schritt 6) und SIP-Server-Hostname im Trunk.

7.2 Outbound-Trockentest

asterisk -rx 'channel originate PJSIP/+43999XXXX@one100_trunk application Wait 5'

Erwartung: `200 OK` von One100, die KI hebt ab (auch ohne realen Anrufer).

7.3 Echter Testanruf

Rufen Sie die Telefonnummer an, auf der Sie in Schritt 4 die Weiterleitung konfiguriert haben.

Häufige Probleme und Lösungen

Quick-Test-Kommandos

Für Debug-Sessions:

# Trunk-Status (Avail = OK)
asterisk -rx 'pjsip show endpoints' | grep one100

# Outbound-INVITE Trockentest (sollte 200 OK zurueckkommen)
asterisk -rx 'channel originate PJSIP/+43999XXXX@one100_trunk application Wait 5'

# Letzten REFER + Antwort sehen
grep -B 2 -A 30 'REFER sip:asterisk' /var/log/asterisk/full | tail -80

# CDR der letzten KI-Calls
mysql -e 'USE asteriskcdrdb; SELECT calldate,clid,src,dst,dstchannel,disposition,duration FROM cdr WHERE dstchannel LIKE "%one100%" ORDER BY calldate DESC LIMIT 10;'

# Verbose hochsetzen fuer Debug
asterisk -rx 'core set verbose 5'
asterisk -rx 'pjsip set logger on'   # SIP-Pakete in /var/log/asterisk/full

Backups

Vor jeder Konfig-Änderung Backups anlegen:

cp /etc/asterisk/extensions_custom.conf            \
   /etc/asterisk/extensions_custom.conf.bak.$(date +%Y%m%d_%H%M%S)

cp /etc/asterisk/pjsip.endpoint_custom_post.conf   \
   /etc/asterisk/pjsip.endpoint_custom_post.conf.bak.$(date +%Y%m%d_%H%M%S)

# DB-Dump (Trunks / PJSIP / Outbound-Routes / Inbound-Routes)
mysqldump asterisk pjsip pjsip_aor pjsip_auths outbound_routes incoming \
   > /root/asterisk_backup_$(date +%Y%m%d_%H%M%S).sql

Rollback: `mv` der Backup-Datei zurück, dann `asterisk -rx 'dialplan reload'` bzw. `mysql asterisk < backup.sql` + `fwconsole reload`.

Geschafft

Ihre FreePBX leitet eingehende Anrufe jetzt an die One100 KI-Telefonassistent:in weiter, die KI sieht die echte Anrufer-Nummer und kann Anrufe per REFER an eine interne Nebenstelle zurückgeben.

Hilfe und Support

Support: support@one100.ai

Dokumentation: one100.ai/resources/introduction