Ugrás a fő tartalomhoz

API Trigger

Az API Trigger Node lehetővé teszi, hogy programozottan kezdeményezzen kimenő hívásokat a Voice Agenthez. Amikor hozzáad egy API Trigger Node-ot a workflow-hoz, az IntraCord létrehoz egy egyedi endpoint URL-t, amelyet a külső rendszerek meghívhatnak a beszélgetés elindításához.

Ez akkor hasznos, ha saját backendből, CRM-ből vagy automation platformról – például n8nből vagy Zapierből – szeretne hívásokat indítani.

Előfeltételek​

Trigger URL megkeresése​

API Trigger Node hozzáadásakor az IntraCord egyedi UUID-t rendel hozzá. A Trigger Node két, közös UUID-t használó URL-t biztosít:

  • Production URL a publikált workflow-hoz
  • Test URL a legújabb drafthoz

Bármelyik URL-címet kimásolhatja a trigger Node beállítási párbeszédpaneljéről.

POST https://your-IntraCord-instance/api/v1/public/agent/{uuid}        # Production
POST https://your-IntraCord-instance/api/v1/public/agent/test/{uuid}   # Test

Ha a hosztolt verziót használja, cserélje ki a your-IntraCord-instance-t a api.IntraCord.com-re.

Test és production​

ModeURLFuttatott verzió
Production/api/v1/public/agent/{uuid}A Voice Agent publikált verziója.
Test/api/v1/public/agent/test/{uuid}A legújabb draft; draft hiányában a publikált verzió.

Fejlesztés közben használja a Test URL-t, így a production traffic továbbra is a publikált verziót éri el.

A Production URL csak publikált workflow-t futtat. Ha módosítja, de nem publikálja a workflow-t, a production trigger továbbra is a korábbi publikált verziót indítja.

A draft publikálása után mindkét URL ugyanazt a definitiont futtatja.

A request body, a headerek és a response struktúrája mindkét URL esetében azonos.

Request küldése​

Authhoz adja át az API-kulcsot az X-API-Key headerben. A request body kötelező phone_number, valamint opcionális initial_context, telephony_configuration_id és from_phone_number_id mezőket fogad.

curl -X POST https://your-IntraCord-instance/api/v1/public/agent/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'
curl -X POST https://your-IntraCord-instance/api/v1/public/agent/test/{uuid} \
  -H "Content-Type: application/json" \
  -H "X-API-Key: dg_your_api_key" \
  -d '{
    "phone_number": "+14155550100",
    "initial_context": {
      "customer_name": "Jane",
      "appointment_date": "March 15"
    }
  }'

Draft módosítások publikálás előtti ellenőrzéséhez használja a Test URL-t.

Response​

A sikeres request workflow_run_id értéket ad vissza, amellyel lekérhetők az Agent Run részletei, felvétele és átirata.

{
  "status": "initiated",
  "workflow_run_id": 12345,
  "workflow_run_name": "WR-API-7823"
}

Error response-ok​

ÁllapotOk
400A telefonszolgáltató nincs konfigurálva, vagy a hívás kezdeményezése nem sikerült
401Hiányzó vagy érvénytelen API-kulcs
403Az API-kulcs nem fér hozzá ehhez az ügynökhöz
404A trigger nem található vagy nem aktív

Initial context​

Az initial_context JSON object a Voice Agent számára a hívás során elérhető adatokat tartalmazza. Az értékekre a template variable elemekkel, {{ és }} között hivatkozhat a promptokban.

Például, ha kérése a következőket tartalmazza:

{
    "phone_number": "+14155550100",
    "initial_context": {
        "user": {
            "name": "John"
        }
    }
}

Az Agent Promptban {{user.name}} formában hivatkozhat a felhasználó nevére. Az initial_context mezői közvetlenül, az initial_context. prefix nélkül érhetők el. A promptokban és Webhook payloadokban használható pontos szintaxist a Template variable-k oldal mutatja be.

Az adatok híváson belüli flow-ját a Context és változók oldal ismerteti.

Greeting felülírása egyetlen híváshoz​

Adjon át greeting_override értéket az initial_context objektumban, ha egyetlen API Trigger hívásnál felül szeretné írni a Start Call Node mentett greetingjét. Érvényes override esetén ez kap elsőbbséget. Ha nincs override, az IntraCord a mentett greetinget használja; ha egyik sincs, a Start Node normál, greeting nélküli működése érvényesül.

Szöveges greeting:

{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "text",
      "text": "Hi, please confirm account {{account_id}}."
    }
  }
}

Előre rögzített greetinghez adja át a Recordings oldalon látható string ID-t:

{
  "phone_number": "+14155550100",
  "initial_context": {
    "greeting_override": {
      "type": "audio",
      "recording_id": "callback-welcome"
    }
  }
}

Az IntraCord a text override-ot a Pre-Call Data Fetch befejezése után rendereli, ezért az override a fetch által visszaadott változókra is hivatkozhat. Ugyanazok a playback korlátozások érvényesek rá, mint a mentett greetingre. A realtime speech-to-speech modellek nem olvasnak fel statikus text greetinget; ilyen confignál audio override szükséges.

A Pre-Call Data Fetch szintén visszaadhat greeting_override értéket. Mivel a fetched context a trigger context után alkalmazódik, az érvényes fetched override felülírja a triggerben megadott értéket.

Telephony configuration és caller ID kiválasztása​

Alapértelmezés szerint a hívások a szervezet default outbound telephony configurationjén keresztül indulnak. Másik konfiguráció használatához – például regionális számról tárcsázáshoz – adja meg a telephony_configuration_id mezőt a request bodyban.

{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42
}

Az ID a Telephony configurations oldal minden sorában látható (https://app.IntraCord.com/telephony-configurations hosted, http://localhost:3010/telephony-configurations local környezetben). A konfigurációnak az API Triggerrel azonos szervezethez kell tartoznia; különben a request 404 választ ad.

Az adott konfigurációhoz tartozó caller ID kiválasztásához adja át a from_phone_number_id mezőt is:

{
  "phone_number": "+14155550100",
  "telephony_configuration_id": 42,
  "from_phone_number_id": 84
}

A from_phone_number_id a kiválasztott telephony configuration alatt beállított telefonszám ID-ja. A számnak aktívnak kell lennie, és ehhez a configurationhöz kell tartoznia; különben a request 400 választ ad. A konfigurált számok a List phone numbers endpointtal kérhetők le.