Webhookok és visszahívások

Áttekintés

Az IntraCord AI webhookot használ a telefonos szolgáltatókkal való kommunikációhoz a hívásesemények és az audio streaming során. A kimenő hívásokhoz az IntraCord összeállítja ezeket az URL-eket, és tárcsázáskor átadja őket a szolgáltatónak – soha nem kell kézzel konfigurálni őket. A bejövő hívások esetén a szolgáltatót egyetlen diszpécser URL-re irányítja; lásd: Bejövő hívások.

Minden webhook elérési út a /api/v1/telephony alatt található.

Webhook típusok

1. Válasz a Webhook-ra

Amikor egy kimenő hívás kapcsolódik, a szolgáltató utasításokat kér. Az elérési út szolgáltató-specifikus, és az IntraCord lekérdezési Stringként hozzáfűzi az útválasztási paramétereket:

?workflow_id={workflow_id}&workflow_run_id={workflow_run_id}&organization_id={organization_id}

Szolgáltató	Módszer	Útvonal
Twilio, Cloudonix	POST	/twiml
Plivo	POST	/plivo-xml
Vobiz	POST	/vobiz-xml
Vonage	GET	/ncco

A Telnyx és az Asterisk ARI nem rendelkezik válasz webhook-kal. A Telnyx hívásvezérlési stílusú – az IntraCord a jelölések visszaadása helyett a stream és az esemény URL-címét POST-ba küldi a Telnyx API-jába. Az ARI csak WebSocket-en keresztül közvetít.

Twilio (TwiML)

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Connect>
        <Stream url="wss://your-domain/api/v1/telephony/ws/123/11/789" />
    </Connect>
</Response>

Vonage (NCCO)

[
  {
    "action": "connect",
    "endpoint": [{
      "type": "websocket",
      "uri": "wss://your-domain/api/v1/telephony/ws/123/11/789",
      "content-type": "audio/l16;rate=16000"
    }]
  }
]

Itt a 123 a workflow, a 11 a szervezet, és a 789 a workflow.

2. Állapot visszahívások

Hívás életciklus-események fogadása. Mindegyik kulcsfontosságú a workflow futtatásakor:

Szolgáltató	Útvonal
Twilio	/twilio/status-callback/{workflow_run_id}
Plivo	/plivo/hangup-callback/{workflow_run_id}, /plivo/ring-callback/{workflow_run_id}
Vobiz	/vobiz/hangup-callback/{workflow_run_id}, /vobiz/ring-callback/{workflow_run_id}
Vonage	/vonage/events/{workflow_run_id}
Telnyx	/telnyx/events/{workflow_run_id}
Cloudonix	/cloudonix/status-callback/{workflow_run_id}, /cloudonix/cdr

A szolgáltatók beszámolnak saját szókincsükről; Az IntraCord egy közös állapothalmazra normalizálja:

• initiated – Hívási kérelem érkezett
• ringing – Csörög a hívás
• in-progress – A hívás csatlakozik és streaming folyamatban van
• answered – A hívást fogadták
• completed – A hívás rendesen befejeződött
• busy – A vonal foglalt volt
• no-answer – A hívást nem fogadták
• canceled - A hívást a csatlakozás előtt megszakították
• failed – A hívás sikertelen
• error – A szolgáltató hibát jelentett

Az IntraCord által nem felismert állapotot változatlan formában továbbítják, nem pedig eldobják.

3. WebSocket Audio Stream

Valós idejű audio streaming a hang interakcióhoz.

Endpoint: /api/v1/telephony/ws/{workflow_id}/{organization_id}/{workflow_run_id}

Ha a TELEPHONY_WS_TOKEN_SECRET be van állítva, az URL IntraCord átadja a szolgáltatónak egy negyedik szegmenst, amely tartalmazza a HMAC aláírást: /api/v1/telephony/ws/{workflow_id}/{organization_id}/{workflow_run_id}/{token}. Ez egy útvonalszegmens, nem pedig egy lekérdezési paraméter, mivel a szolgáltatók nem továbbítják megbízhatóan a lekérdezési Stringokat – a Twilio teljesen kivonja őket a <Stream url>-ből.

Ehelyett az Asterisk ARI csatlakozik a /api/v1/telephony/ws/ari-hez, és ugyanazt a három értéket adja át lekérdezési paraméterként, plusz a token értéket, ha titkos konfigurálva van – lásd: Asterisk ARI.

A workflow tulajdonosa a organization_id szegmens. Az IntraCord minden workflow-t és Workflow Run keresést hatókörébe tartozik, így az egyik szervezethez tartozó futtatást soha nem lehet kiszolgálni egy másik azonosítója alatt.

Hangformátumok:

• Twilio / Plivo / Vobiz: 8 kHz μ-törvény (MULAW), Base64 kódolású JSON-üzenetekben
• Vonage: 16kHz lineáris PCM, bináris keretek
• Csillag ARI: 8 kHz Lineáris PCM external media kapcsolaton keresztül

Hogyan működik

IntraCord AI automatikusan:

1. Webhook URL-eket hoz létre a telepítés alapján
2. Híváskezdeményezéskor átadja őket a telefonszolgáltatónak
3. Ellenőrzi a webhook aláírásokat a biztonság érdekében:
   • Twilio: HMAC-SHA1 aláírás-ellenőrzés
   • Plivo / Vobiz: HMAC-SHA256 aláírás-ellenőrzés
   • Vonage: JWT token ellenőrzése
4. Feldolgozza az állapotfrissítéseket a hívás életciklusának nyomon követéséhez
5. Kezeli a WebSocket kapcsolatokat audio streaminghez
6. Kezeli a szolgáltató-specifikus hangformátumokat és protokollokat

Az aláírás-ellenőrzés a verify_inbound_signature szolgáltatónként valósul meg. Ha szolgáltatót ad hozzá, olvassa el az Egyéni telefonszolgáltató című részt.

Helyi fejlesztés

Helyi fejlesztéshez használja a beépített Cloudflare alagutat:

# docker-compose.yml includes:
cloudflared:
  image: cloudflare/cloudflared:latest
  command: tunnel --no-autoupdate --url http://api:8000

Az alagút URL-címét a rendszer automatikusan észleli és használja a webhookhoz.

Hibaelhárítás

Webhook URL not accessible

• Ellenőrizze, hogy a domain/alagút URL-je nyilvánosan elérhető-e
• Ellenőrizze, hogy a tűzfalszabályok engedélyezik a bejövő HTTPS-forgalmat
• Tesztelje a curl-vel külső hálózatról

Signature verification failures

• A szolgáltatók aláírják a teljes URL-t, beleértve a lekérdezési Stringet is – a lekérdezési paramétereket átíró vagy átrendező proxy érvényteleníti az aláírást
• Győződjön meg arról, hogy a háttérprogram nyilvános URL-címe megegyezik a szolgáltató által megadottal, beleértve a sémát és a portot is

WebSocket connection dropping

• Ellenőrizze, hogy a WebSocket frissítési fejlécek megmaradtak-e
• Ellenőrizze, hogy nincs időtúllépés a terheléselosztóban/proxyban
• Figyelje a memória/CPU korlátokat

Status callbacks not received

• Ellenőrizze, hogy a workflow_run_id szerepel-e az URL-ben
• Ellenőrizze a szolgáltatói konzolt a webhook hibákért
• Tekintse át a webhook újrapróbálkozási naplóit