Variabelen per oproep

Personaliseer een opgeslagen agent voor elke oproep zonder de geïmplementeerde prompt, tools of instellingen te wijzigen.

Plaats placeholders in de prompt van je opgeslagen agent en geef vervolgens een variables- object mee wanneer je een oproep start. De opgeslagen configuratie en versiegeschiedenis blijven ongewijzigd. ThunderPhone rendert de tekst voordat de oproepconfiguratie naar de spraakruntime wordt verzonden.

Wanneer er geen waarden nodig zijn, laat je variables weg; stuur geen null (wordt geweigerd met 400).

Placeholders en standaardwaarden

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

Namen zijn hoofdlettergevoelig en volgen [A-Za-z_][A-Za-z0-9_]*. Witruimte rond de naam is toegestaan; witruimte na | maakt deel uit van de standaardwaarde en blijft behouden. {{name|Friend}} gebruikt Friend wanneer name ontbreekt of null is; een lege tekenreeks is een expliciet opgegeven waarde. Ontbrekende waarden zonder standaardwaarde worden lege tekenreeksen en hun namen verschijnen in unresolved_variables. Tekst tussen dubbele accolades die geen geldige placeholder is, wordt verwijderd. Tekst tussen dubbele accolades binnen elke opgegeven waarde wordt onafhankelijk verwijderd; een waarde kan geen omringende prompttekst of andere waarde verwijderen. Niet-overeenkomende dubbele-accoladebegrenzingen worden ook verwijderd. JSON-voorbeelden in prompts mogen geen {{ gebruiken. Waarden zijn platte tekst en worden nooit als code geëvalueerd of recursief als templates uitgebreid.

Variabelen kunnen ook voorkomen in bevestigingsprompts, uitgaande voicemailberichten en de tekst van de toestemmingsmelding wanneer dat veld voor een telefoongesprek wordt verzonden. De agent heeft geen afzonderlijk veld first_message: plaats de openingsinstructies in de prompt. Bestaande voicemail-placeholders {agent_name} en {org_name} blijven werken.

Waarden kunnen tekenreeksen, getallen, booleaanse waarden of null zijn; booleaanse waarden worden weergegeven als true en false. Unicode-besturingstekens (Cc) behalve nieuwe regel (\n), tab (\t) en carriage return (\r), alle opmaaktekens (Cf) en surrogaatcodepunten (Cs) worden verwijderd; \r\n wordt genormaliseerd naar \n. Elke waarde is bij weergave beperkt tot 2.000 tekens. Opgegeven tekenreeksen worden ook opgeschoond en afgekapt vóór opslag. Het oorspronkelijke object moet binnen 32 KB UTF-8-JSON passen; grotere objecten ontvangen 400 bij oproep-/sessieverzoeken, terwijl campagne-imports ongeldige rijen afzonderlijk rapporteren. Arrays en geneste objecten worden niet als waarden geaccepteerd. Niet-overeenkomende metadatasleutels (bijvoorbeeld een CSV-header met een spatie) blijven behouden en worden teruggegeven, maar kunnen niet door een placeholder worden gebruikt.

Waar waarden vandaan komen

Uitgaande API

Stuur variables mee met agent_id naar 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"
  }
}

Dit werkt ook met de standaard uitgaande agent van het telefoonnummer, of met een inline config.prompt. Een idempotentiesleutel kan niet opnieuw worden gebruikt met andere variabelen.

Campagne-CSV

CSV-kolommen die geen telefoonnummers bevatten, worden al opgeslagen als contactvariabelen. Elke oproep gebruikt ze nu automatisch. Gebruik kopteksten zoals name, account_id en appointment_slot die overeenkomen met je placeholders. De bestaande naammapping kan kolommen voor voor- en achternaam combineren tot de variabele name.

Webhook voor dynamische configuratie

Geef op het pad van de blokkerende configuratiewebhook een opgeslagen agent in je organisatie plus waarden per oproep terug:

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

De sleutels van het antwoord overschrijven variabelen op aanvraagniveau, terwijl andere aanvraagsleutels behouden blijven. Een antwoordwaarde van null selecteert de standaardwaarde van de placeholder. Het samengevoegde object moet ook binnen 32 KB passen. Antwoorden met opgeslagen agents accepteren alleen agent_id en variables; geef een inline configuratie terug wanneer je de prompt of instellingen moet vervangen. Een antwoord met prompt gebruikt altijd een inline configuratie: elke agent_id in dat antwoord wordt genegeerd, inclusief null- of niet-gehele-metagegevens. De inline prompt moet nog steeds de normale validatie doorstaan. Inline webhookantwoorden kunnen ook variables bevatten. Webhookantwoorden met opgeslagen agents gebruiken de geïmplementeerde A/B-verdeling van de agent voor zowel telefoon- als widgetoproepen; variabelen worden weergegeven na de variantselectie. Gebruik voor inkomende telefoonoproepen een nummer zonder toegewezen inkomende agent en configureer de webhook van het telefoonnummer of de organisatie; widgetsleutels gebruiken mode="webhook". Inkomende meldingen van het endpointsysteem leveren geen blokkerende configuratieantwoorden.

POST /v1/widget/session accepteert een variables-object op het hoogste niveau. De publiceerbare sleutel selecteert de opgeslagen agent. Sleutels in webhookmodus sturen deze waarden door naar de configuratiewebhook en voegen het antwoord samen zoals hierboven beschreven. Door de browser aangeleverde widget/realtime-variables worden door de client beheerd, woordelijk doorgestuurd in web.incoming na de hierboven beschreven validatie en opschoning van tekenreeksen, en opgenomen in completion-webhooks en de Oproepgeschiedenis. Behandel ze niet als vertrouwde identiteits- of autorisatiegegevens.

POST /v1/realtime/sessions accepteert variables samen met agent_id (of inline config). Dit zijn API-velden voor het aanmaken van sessies. De Realtime WebSocket- bridge stuurt geen optie voor variabelen door; geef deze rechtstreeks op aan de API voor het aanmaken van sessies. Widgetclients moeten variables opnemen in de geplaatste sessiepayload; SDK-doorsturing maakt geen deel uit van deze API-wijziging. Mic- en gesimuleerde testoproepen in Builder lossen standaardwaarden en ontbrekende placeholders op, maar hebben geen invoer voor variabelen per oproep.

Waarden die na de oproep worden teruggestuurd

GET /v1/calls, GET /v1/calls/{call_id}, telephony.complete en web.complete bevatten de uiteindelijk samengevoegde variables en unresolved_variables. Verouderde completion-payloads die data.history bevatten, bevatten deze ook:

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

Sla je CRM- of taak-ID op in het variabelenobject om de voltooide oproep terug te koppelen aan het bronrecord. Deze velden worden bewaard bij het oproeprecord; stuur alleen informatie die geschikt is om te bewaren in de Oproepgeschiedenis en webhooks.

Compatibiliteit met bestaande prompts

Rendering geldt ook voor bestaande prompts van opgeslagen agents en A/B-varianten, inline uitgaande en realtime configuraties, en prompts die worden teruggestuurd door configuratiewebhooks. Onbekende {{name}}-placeholders worden lege tekst, zelfs wanneer er geen variables zijn opgegeven. Controleer bestaande prompts vóór de uitrol, inclusief extern aangeleverde inline-/webhookprompts die ThunderPhone niet kan inventariseren. Builder-microfoon- en simulatieoproepen gebruiken hetzelfde standaard-/lege gedrag.