Variabler per samtal

Anpassa en sparad röstagent för varje samtal utan att ändra dess driftsatta prompt, verktyg eller inställningar.

Placera platshållare i din sparade agents prompt och ange sedan ett variables-objekt när du startar ett samtal. Den sparade konfigurationen och versionshistoriken förblir oförändrade. ThunderPhone återger texten innan samtalskonfigurationen skickas till röstkörmiljön.

När inga värden behövs utelämnar du variables; skicka inte null (avvisas med 400).

Platshållare och standardvärden

You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.

Namn är skiftlägeskänsliga och följer [A-Za-z_][A-Za-z0-9_]*. Blanksteg runt namnet är tillåtna; blanksteg efter | ingår i standardvärdet och bevaras. {{name|Friend}} använder Friend när name saknas eller är null; en tom sträng är ett uttryckligen angivet värde. Saknade värden utan ett standardvärde blir tomma strängar och deras namn visas i unresolved_variables. Text mellan dubbla klamrar som inte är en giltig platshållare tas bort. Text med dubbla klamrar i varje angivet värde tas bort separat; ett värde kan inte ta bort omgivande prompttext eller ett annat värde. Omatchade avgränsare med dubbla klamrar tas också bort. JSON-exempel i prompter får inte använda {{. Värden är vanlig text och utvärderas aldrig som kod eller expanderas rekursivt som mallar.

Variabler kan också visas i bekräftelseprompter, utgående röstmeddelanden och texten för samtyckesmeddelandet när det fältet skickas för ett telefonsamtal. Agenten har inget separat first_message-fält: lägg dess inledande instruktioner i prompten. Befintliga platshållare för röstmeddelanden, {agent_name} och {org_name}, fortsätter att fungera.

Värden kan vara strängar, tal, booleska värden eller null; booleska värden återges som true och false. Unicode-kontrolltecken (Cc) utom nyrad (\n), tabulator (\t) och vagnretur (\r), alla formateringstecken (Cf) och surrogatkodpunkter (Cs) tas bort; \r\n normaliseras till \n. Varje värde är begränsat till 2 000 tecken när det återges. Angivna strängar rensas och trunkeras även före lagring. Det ursprungliga objektet måste rymmas inom 32 KB UTF-8-JSON; större objekt får 400 vid samtals-/sessionsbegäranden, medan kampanjimporter rapporterar ogiltiga rader var för sig. Arrayer och nästlade objekt accepteras inte som värden. Metadatatangenter som inte matchar (till exempel en CSV-rubrik med ett mellanslag) behålls och ekas men kan inte refereras av en platshållare.

Var värden kommer från

Utgående API

Skicka variables tillsammans med agent_id i POST /v1/call:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

Det fungerar även med telefonnumrets standardagent för utgående samtal eller med en infogad config.prompt. En idempotensnyckel kan inte återanvändas med andra variabler.

Kampanj-CSV

CSV-kolumner som inte är telefonnummer lagras redan som kontaktvariabler. Varje uppringning använder dem nu automatiskt. Använd rubriker som name, account_id och appointment_slot för att matcha dina platshållare. Den befintliga namnkopplingen kan kombinera kolumner för förnamn och efternamn till variabeln name.

Webhook för dynamisk konfiguration

I sökvägen för den blockerande konfigurationswebhooken returnerar du en sparad agent i din organisation plus eventuella värden per samtal:

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

Svarens nycklar skriver över variabler på begärandenivå, medan övriga nycklar i begäran behålls. Ett svarsvärde på null väljer platshållarens standardvärde. Det sammanslagna objektet måste också rymmas inom 32 KB. Svar för sparade agenter accepterar endast agent_id och variables; returnera en infogad konfiguration när du behöver ersätta prompten eller inställningarna. Ett svar som innehåller prompt använder alltid infogad konfiguration: eventuell agent_id i svaret ignoreras, inklusive null eller metadata som inte är heltal. Den infogade prompten måste fortfarande klara vanlig validering. Infogade webhooksvar kan också innehålla variables. Webhooksvar för sparade agenter använder agentens driftsatta A/B-fördelning för både telefon- och widget-samtal; variabler återges efter val av variant. För inkommande telefonsamtal använder du ett nummer utan tilldelad inkommande agent och konfigurerar dess webhook för telefonnummer eller organisation; widgetnycklar använder mode="webhook". Inkommande aviseringar från endpoint-systemet tillhandahåller inte blockerande konfigurationssvar.

POST /v1/widget/session accepterar ett variables-objekt på toppnivå. Dess publicerbara nyckel väljer den sparade agenten. Nycklar i webhook-läge vidarebefordrar dessa värden till konfigurationswebhooken och slår samman svaret enligt beskrivningen ovan. Widget-/realtime-variables som tillhandahålls av webbläsaren styrs av klienten, vidarebefordras ordagrant i web.incoming efter valideringen och strängrensningen som beskrivs ovan, och återges i avslutswebhooks och samtalshistorik. Behandla dem inte som betrodd identitets- eller auktoriseringsdata.

POST /v1/realtime/sessions accepterar variables tillsammans med agent_id (eller infogad config). Dessa är API-fält för att skapa sessioner. Realtime WebSocket- bryggan vidarebefordrar inte ett alternativ för variabler; ange det direkt till API:et för att skapa sessioner. Widgetklienter måste inkludera variables i den skickade sessionsnyttolasten; SDK-vidarebefordran ingår inte i denna API-ändring. Builder-mikrofonen och simulerade testsamtal löser standardvärden och saknade platshållare men har ingen inmatning för variabler per samtal.

Värden som returneras efter samtalet

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete och web.complete innehåller de slutliga sammanslagna variables och unresolved_variables. Äldre nyttolaster för slutförande som innehåller data.history inkluderar dem också:

{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}

Lagra din CRM- eller uppgiftsidentifierare i variabelobjektet för att koppla det slutförda samtalet tillbaka till dess källpost. Dessa fält behålls tillsammans med samtalsposten; skicka endast information som är lämplig att behålla i samtalshistorik och webhooks.

Kompatibilitet med befintliga promptar

Rendering tillämpas även på befintliga promptar för sparade agenter och A/B-varianter, infogade utgående konfigurationer och realtidskonfigurationer samt promptar som returneras av konfigurationswebhooks. Okända platshållare som {{name}} blir tom text, även när inga variables anges. Kontrollera befintliga promptar före lansering, inklusive externt tillhandahållna infogade promptar och webhook-promptar som ThunderPhone inte kan inventera. Byggarens mikrofon- och simuleringssamtal använder samma standardbeteende för tomma värden.