Csillag ARI integráció

Áttekintés

Az Asterisk ARI (Asterisk REST Interface) lehetővé teszi az IntraCord AI Voice Agentek csatlakoztatását a meglévő Asterisk PBX-hez. Az ARI WebSocket-alapú eseménymodellt biztosít a hívások Stasis alkalmazásokon keresztül történő vezérléséhez, így az IntraCord teljes mértékben irányíthatja a hívásfolyamat és az audio streaminget.

Ez az útmutató az IntraCord-specifikus konfigurációra összpontosít. Az Asterisk általános telepítésével és adminisztrációjával kapcsolatban lásd a hivatalos Asterisk dokumentációt.

Előfeltételek

Az ARI-integráció beállítása előtt győződjön meg arról, hogy rendelkezik:

• Elérhető egy futó Asterisk példány chan_websocket és res_websocket_client modulokkal. Ismert működő beállítások: (a) Asterisk 22+, (b) Asterisk 20 LTS ezekkel a modulokkal
• Az ARI modul engedélyezve van az Asteriskben
• A chan_websocket (WebSocket csatorna-illesztőprogram) és a res_websocket_client (a websocket_client.conf betöltése) engedélyezve van az Asterisk buildben. Ellenőrizze a asterisk -rx "module show like chan_websocket" és a asterisk -rx "module show like res_websocket_client" segítségével – mindkettőnek Futás jelentést kell adnia.
• Hálózati kapcsolat az IntraCord-példány és az Asterisk között
• IntraCord AI példány fut és elérhető

i

Ha forrásból fordította le az Asterisk-et, győződjön meg arról, hogy a chan_websocket és a res_websocket_client is szerepel az összeállítás során. Ezek a modulok szükségesek az Asterisk és az IntraCord közötti külső media streaminghez. A modulok engedélyezésével kapcsolatos részletekért tekintse meg az Asterisk build system dokumentációt.

Csillag konfiguráció

A következő Asterisk konfigurációs fájlokat kell beállítani az IntraCord használatához. Ezek az IntraCord-integrációra összpontosító minimális példák – a konfigurációs részletekért tekintse meg az Asterisk dokumentációt.

ARI engedélyezése (ari.conf)

Hozzon létre egy ARI-felhasználót, amelyet az IntraCord a hitelesítéshez használ:

[general]
enabled = yes

[IntraCord]
type = user
read_only = no
password = your_secure_password

i

A felhasználónévnek (szakasznév, pl. IntraCord) és jelszónak meg kell egyeznie az IntraCordban beállított Stasis alkalmazásnévvel és alkalmazásjelszóval.

A HTTP szerver engedélyezése (http.conf)

Az ARI megköveteli, hogy az Asterisk HTTP szerver engedélyezve legyen:

[general]
enabled = yes
bindaddr = 0.0.0.0
bindport = 8088

Állítsa be a Stasis Dialplant (extensions.conf)

A bejövő hívásokat a Stasis alkalmazásba irányítsa, hogy az IntraCord kezelni tudja őket:

[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(IntraCord)
 same => n,Hangup()

Cserélje ki a IntraCord elemet a ari.conf és az IntraCord alkalmazásban konfigurált alkalmazásnévre.

A external media streaming konfigurálása (websocket_client.conf)

Az IntraCord az Asterisk külső media streamjét használja a hang küldésére és fogadására a WebSocketen keresztül. Konfiguráljon egy WebSocket-ügyfélkapcsolatot, amely az IntraCord-példányra mutat:

IntraCord Cloud

[IntraCord]
type = websocket_client
uri = wss://api.IntraCord.com/api/v1/telephony/ws/ari
protocols = media
tls_enabled = yes
ca_list_file = /etc/ssl/certs/ca-certificates.crt

i

A tls_enabled = yes szükséges annak ellenére, hogy az URI-séma wss:// – enélkül az Asterisk nem tárgyalja a TLS-t, és a kapcsolat meghiúsul. Az ARI Credentials adatoknak (Stasis App Name és App Password) meg kell egyeznie azzal, amit az IntraCord Dashboardján a Telefonálási beállítások alatt konfigurált.

Self-hosted

[IntraCord]
type = websocket_client
uri = ws://your-IntraCord-host:port/api/v1/telephony/ws/ari
protocols = media

i

A belső hálózat saját üzemeltetésű központi telepítései titkosítatlan WebSocketet (ws://) használhatnak. Ha az IntraCord-példány HTTPS-en keresztül érhető el, használja helyette a wss://-t és a megfelelő gazdagépnevet.

i

A szakasz neve (pl. IntraCord) a WebSocket Client Name, amelyet az IntraCord telefóniai beállításában kell megadni. Ez a név mondja meg az Asterisknek, hogy hívás közben melyik WebSocket-kapcsolatot használja a external media streamingjéhez.

i

Konfigurálja a uri-t csak alap URL-ként, lekérdezési String nélkül. Minden hívás során az IntraCord megkéri az Asterisket, hogy hozzon létre egy externalMedia csatornát, és az Asterisk hozzáfűzi a workflow_id, organization_id és workflow_run_id workflow_run_id átviteli adatait az adott híváshoz. A /api/v1/telephony/ws/ari megnyitása közvetlenül a böngészőben vagy a wscat segítségével visszaadhatja a HTTP 403-at, mert ezek az útválasztási paraméterek hiányoznak; ez várható, és nem websocket_client.conf hibás konfigurációt jelez.

i

Az IntraCord külső médiacsatornája a G.711 μ-törvényt (ulaw) használja. Győződjön meg arról, hogy minden PJSIP endpoint vagy SIP-trönk, amely az IntraCord-on keresztül kezdeményez vagy fogad hívásokat, engedélyezi a ulaw kódot (pl. a allow=ulaw az endpoint konfigurációjában).

A további websocket_client.conf opciókat és a TLS-konfigurációt az Asterisk WebSocket dokumentációban találja.

Alkalmazza a konfigurációs módosításokat

A fenti fájlok bármelyikének szerkesztése után töltse be újra az érintett Asterisk modulokat az Asterisk CLI-ből (asterisk -rvvv):

ari reload                                 # picks up ari.conf changes
dialplan reload                            # picks up extensions.conf changes
module reload res_websocket_client.so      # picks up websocket_client.conf changes

A http.conf módosításához teljes Asterisk újratöltésre (core reload) vagy a szolgáltatás újraindítására van szükség.

Konfiguráció az IntraCordban

1. lépés: Lépjen a Telefonálási beállítások elemre

1. Lépjen a /telephony-configurations oldalra, és kattintson a Konfiguráció hozzáadása lehetőségre.
2. Válassza ki a Asterisk ARI szolgáltatót

2. lépés: Adja meg ARI Credentials adatait

Állítsa be a következő mezőket:

Mező	Leírás	Példa
ARI endpoint URL	Az Asterisk ARI szerver HTTP alap URL-je	http://asterisk.example.com:8088
Stasis alkalmazás neve	A ari.conf	-ben konfigurált ARI-felhasználónév IntraCord
Alkalmazásjelszó	A ari.conf	-ben konfigurált ARI-jelszó your_secure_password
WebSocket ügyfél neve	A kapcsolat neve a websocket_client.conf	IntraCord
A bővítményekből	Opcionális SIP mellékek vagy fővonali számok kimenő hívásokhoz	PJSIP/6001 vagy 6001

3. lépés: Bővítmények mentése és hozzáadása

1. Kattintson a Konfiguráció mentése gombra
2. Nyissa meg az imént létrehozott konfigurációt, és adjon hozzá minden olyan SIP-bővítményt, amelynek telefonszámként elérhetőnek kell lennie (pl. 8000). Bejövő hívások esetén minden mellékhez külön kell hozzárendelnie a workflow-t – lásd alább a Bejövő hívás részt.
3. Hozzon létre egy teszt workflow-t, és indítson teszthívást a kapcsolat ellenőrzésére.

Bejövő hívás

Más telefonszolgáltatókkal ellentétben, amelyek HTTP webhookot használnak a bejövő hívásokhoz, az ARI StasisStart eseményekként kézbesíti a bejövő hívásokat az ARI WebSocket-en. Az IntraCord automatikusan észleli ezeket az eseményeket, és aktiválja a hívott kiterjesztéshez rendelt workflow-t.

Hogyan működik

1. Külső hívás érkezik az Asteriskhez, és a tárcsázási terv a Stasis(IntraCord) címre irányítja
2. Az Asterisk egy StasisStart eseményt indít el az ARI WebSocket felett, a csatorna Ring állapotban, a tárcsázott mellék pedig a tárcsázási terv környezetében
3. Az IntraCord megkeresi a hívott melléket a telefóniai beállítás telefonszámaiban, megkeresi a hozzárendelt workflow-t, érvényesíti a kvótát, és létrehoz egy workflow-t.
4. A hívást fogadják, áthidalják egy külső médiacsatornára, és megkezdődik a Voice Agent workflow-ja

A workflow-hozzárendelés bővítményenként történik, így ugyanazon a csillagon lévő különböző bővítmények különböző ügynökökhöz irányíthatnak.

Bejövő hívások beállítása

1. lépés: Állítsa be az Asterisk tárcsázási tervet

Győződjön meg arról, hogy a tárcsázási terv az Ön számára fontos mellékeket a Stasis alkalmazásba irányítja. Vagy irányítson egy adott melléket:

[from-external]
exten => 8000,1,NoOp(Incoming call to 8000)
 same => n,Stasis(IntraCord)
 same => n,Hangup()

…vagy használjon olyan mintát, amely elkapja az IntraCord-ban regisztrált összes bővítményt:

[from-external]
exten => _X.,1,NoOp(Incoming call to ${EXTEN})
 same => n,Stasis(IntraCord)
 same => n,Hangup()

Cserélje ki a IntraCord elemet a ari.conf és az IntraCord alkalmazásban konfigurált alkalmazásnévre.

2. lépés: Adja hozzá a melléket telefonszámként az IntraCord-ban

1. Lépjen a /telephony-configurations oldalra, és nyissa meg az Asterisk ARI konfigurációját

2. A Telefonszámok részben adjon meg egy telefonszámot, amelynek címe a SIP mellék (pl. 8000)

3. Állítsa be a Bejövő workflow-t arra az ügynökre, akinek válaszolnia kell

4. Mentés

   i

   A kiterjesztés hozzáadása az IntraCordhoz nem változtatja meg az Asterisk tárcsázási tervét – ez van mire való az 1. lépés. Az IntraCord bejegyzés megmondja a StasisStart kezelőnek, hogy melyik workflow futtatásához, amikor a mellékállomás hívása eléri a Stasis alkalmazást.

Ismételje meg a 2. lépést minden olyan mellékre, amelynek el kell érnie a Voice Agentet.

3. lépés: Bejövő hívás tesztelése

Hívjon a konfigurált mellékek egyikén. Látnia kell, hogy a hozzárendelt workflow aktiválódik, és a Voice Agent válaszol.

Bejövő hívás kontextusa

Amikor egy bejövő hívás aktivál egy workflow-t, a következő kontextus érhető el a workflow számára:

Mező	Leírás
caller_number	A hívó telefonszáma vagy melléke
called_number	A tárcsázott szám vagy mellék
direction	Mindig inbound
call_id	A csillag csatornaazonosító
provider	Mindig ari

Hibaelhárítás

Cannot connect to ARI endpoint

• Ellenőrizze, hogy az ARI endpoint URL-címe helyes-e, és elérhető-e az IntraCord-példányból
• Ellenőrizze, hogy fut-e az Asterisk HTTP szerver (a http.conf enabled = yes-vel rendelkezik)
• Győződjön meg arról, hogy a tűzfalszabályok lehetővé teszik a forgalmat az ARI porton (alapértelmezett: 8088)
• Ellenőrizze, hogy az ARI modul be van-e töltve: futtassa a module show like res_ari-t az Asterisk CLI-ben

Authentication failed

• Ellenőrizze, hogy a Stasis alkalmazás neve megegyezik-e az ARI felhasználói szakasz nevével a ari.conf-ben
• Ellenőrizze, hogy az alkalmazásjelszó megegyezik-e a ari.conf jelszavával
• Győződjön meg arról, hogy a Credentials mezőkben nincs felesleges szóköz

No audio during calls

• Ellenőrizze, hogy a chan_websocket be van-e töltve: futtassa a module show like chan_websocket-t az Asterisk CLI-ben
• Ellenőrizze, hogy a websocket_client.conf megfelelően van-e konfigurálva a megfelelő IntraCord URI-vel
• Győződjön meg arról, hogy a WebSocket ügyfél neve az IntraCordban megegyezik a websocket_client.conf szakasz nevével
• Ellenőrizze, hogy a hálózati kapcsolat és a tűzfalszabályok lehetővé teszik a WebSocket-forgalmat az Asterisk és az IntraCord között

Calls not reaching IntraCord

• Győződjön meg arról, hogy a tárcsázási terv a hívásokat a Stasis(your_app_name) címre irányítja
• Ellenőrizze, hogy a tárcsázási tervben szereplő alkalmazásnév megegyezik-e a ari.conf ARI-felhasználójával
• Ellenőrizze az Asterisk CLI-t a hibákért: asterisk -rvvv
• Győződjön meg arról, hogy az ARI WebSocket kapcsolat aktív

Inbound calls are immediately hung up

• Ellenőrizze, hogy a hívott mellék telefonszámként szerepel-e az ARI-ban konfiguráció a /telephony-configurations alatt, és van egy Bejövő workflow hozzárendelt
• Győződjön meg arról, hogy a workflow létezik, és ugyanahhoz a szervezethez tartozik, mint a ARI konfig
• Ellenőrizze, hogy szervezete rendelkezik-e rendelkezésre álló kvótával
• Tekintse át az IntraCord naplóit olyan figyelmeztetésekért, mint a „nincs regisztrálva egyező telefonszám for config" vagy "nincs hozzárendelve bejövő workflow ID"

WebSocket client connection issues

• Ellenőrizze a websocket_client.conf URI-t, amely a megfelelő IntraCord gazdagépre és portra mutat
• Győződjön meg arról, hogy az IntraCord példány fut, és elfogadja a WebSocket kapcsolatokat
• Ha TLS-t használ, győződjön meg arról, hogy a tanúsítványok mindkét oldalon megfelelően vannak konfigurálva

Legjobb gyakorlatok

• Az optimális hangminőség érdekében tartsa az Asterisk-példányt ugyanazon a hálózaton vagy alacsony késleltetésű IntraCord-kapcsolaton
• Használjon erős jelszavakat az ARI-hitelesítéshez
• Korlátozza az ARI-hozzáférést az ismert IP-címekre a tűzfalszabályok segítségével
• Figyelje az Asterisk naplókat az IntraCord naplók mellett a hívási problémák hibakeresése során
• A biztonság és a kompatibilitás érdekében frissítse az Asterisket a legújabb stabil verzióra

További olvasás

• Asterisk dokumentáció -- hivatalos referencia az összes Asterisk konfigurációhoz
• ARI dokumentáció -- részletes ARI konfiguráció és API hivatkozás