Applicatiegegevens gebruiken in een spraaksequentie

Gebruik voice.webhook wanneer je applicatie gegevens heeft die het gesprek nodig heeft: een orderstatus, een team of een afspraakbevestiging. De stap geeft die gegevens terug op success. Een latere Branch-stap kiest op basis daarvan het pad.

Het antwoord definiëren

Stel config.output_schema in op een objectschema voor de teruggegeven gegevens. De stap heeft twee uitgangen: success bevat gegevens volgens dat schema en failure handelt technische problemen af. Als je de configuratie weglaat, is de uitvoer een leeg object.

De invoer bevat een statische HTTPS url en een optioneel object data. Voor de gegevens kun je een letterlijk object, $literal of een volledig object via $expr gebruiken. Dynamische URL's, zelf opgegeven headers en inloggegevens worden niet ondersteund.

Verzoeken verifiëren

Bird ondertekent elk verzoek, ook vervolgaanroepen, met het callbackgeheim van je werkruimte en headers volgens Standard Webhooks: webhook-id, webhook-timestamp en webhook-signature. De handtekening dekt de ID, de tijdstempel en de exacte body. In de 24 uur na het roteren van een geheim bevat webhook-signature één v1,-vermelding per actief geheim, zodat beide geheimen de verificatie laten slagen. Het kan ongeveer een minuut duren voordat calls met een nieuw geheim ondertekenen, dus blijf het vorige geheim accepteren tot de overlapperiode voorbij is. Je antwoord wordt niet ondertekend: Bird valideert het TLS-certificaat van je ontvanger, en de HTTPS-verbinding authenticeert wat je ontvanger teruggeeft.

Verifieer de headers over de onbewerkte body met de verify-aanroep van een Standard Webhooks-bibliotheek, voordat je de body parseert. De webhooks.unwrap van de SDK's parseert platformevents en is niet bedoeld voor deze verzoeken. Roteer eerst het geheim onder Webhooks → Direct callbacks, want het eerste geheim wordt nooit getoond. De handtekening laat zien dat iemand met het geheim van je werkruimte het verzoek heeft ondertekend. Je SMS-callbackontvangers hebben hetzelfde geheim en kunnen ook ondertekenen, dus bewaar het alleen op ontvangers die je vertrouwt. Iedereen die de sequenties van de werkruimte kan bewerken, kiest de URL en data. Controleer of target_url je eigen URL is, zodat je een verzoek weigert dat Bird voor een andere ontvanger heeft ondertekend, en autoriseer zakelijke acties in je ontvanger. Autorisatie van de klant wordt nooit doorgestuurd.

Webhookverzoeken van sequenties presenteren geen clientcertificaat, ook niet als je werkruimte mTLS afdwingt. Configureer de ontvanger zo dat die een verbinding zonder clientcertificaat accepteert, en authenticeer in plaats daarvan het ondertekende verzoek.

Controleer de ondertekende webhook-timestamp, een Unix-tijdstempel in seconden, tegen een gesynchroniseerde serverklok. Weiger verzoeken die meer dan vijf minuten in het verleden of de toekomst liggen. Ontdubbel op webhook-id voordat je bijwerkingen uitvoert. Sla de ID en het resultaat waar mogelijk atomair op samen met de actie, en geef bij een herhaald verzoek het opgeslagen resultaat terug. Elke vervolgaanroep heeft een eigen ID. Gebruik een aparte zakelijke idempotentiesleutel als verschillende verzoeken niet dezelfde actie mogen herhalen.

Gegevens teruggeven

De ontvanger geeft dit gesloten antwoordformaat terug:

{
  "schema_version": 1,
  "type": "outcome",
  "output": { "status": "confirmed", "message": "Your appointment is confirmed." }
}

output moet overeenkomen met het geconfigureerde schema. Het antwoord geeft gegevens terug, geen poort, node-ID of nieuwe opdrachten. Een vervolgaanroep is {"schema_version":1,"type":"continue","url":"https://example.com/voice/next"} op de canonieke origin van de oorspronkelijke URL.

Wil je op basis van de data routeren, verbind dan success met een logic.branch-stap met cases zoals steps.decision.output.status == 'confirmed'. Declareer het veld in het schema als string-enum, zodat de receiver alleen die waarden kan teruggeven.

Het verzoek bevat de identiteit van de run, sessie en call, de identiteit van de toegelaten sequence en node, je gematerialiseerde data en results. Zet zakelijke invoer in data. Een direct privéresultaat van Gather kan één keer in results verschijnen, en afgeronde opnamen bevatten een ID als die beschikbaar is. Deze observaties worden niet automatisch expressievelden.

Het verzoek aan de receiver lezen

Een testrun van een concept stuurt deze vorm. De ID's en tijdstempels hieronder zijn fictief. Het echte verzoek gebruikt de toegelaten run en de huidige node-occurrence:

{
  "schema_version": 1,
  "method": "POST",
  "target_url": "https://example.com/decision",
  "run_id": "vsr_01k5yb7p000000000000000000",
  "sequence": {
    "id": "vsq_01k5yb7p000000000000000000",
    "version_id": null,
    "draft_revision": 1,
    "entry_node_id": "start",
    "mode": "test"
  },
  "session_id": "vcs_01k5yb7p000000000000000000",
  "call": { "id": "vcl_01k5yb7p000000000000000000", "orig": null, "dest": null },
  "node": { "id": "decision", "occurrence_id": "00000000-0000-4000-8000-000000000001" },
  "data": { "appointment_id": "appointment_123" },
  "results": []
}

Bij een gepubliceerde run identificeert version_id de geselecteerde versie en is draft_revision null. Bij een call die een inline definitie heeft uitgevoerd, zijn id, version_id en draft_revision allemaal null. mode kan test of production zijn. Herkomst en bestemming gebruiken nullable call-partijobjecten. Verifieer de handtekening voordat je deze identiteitsvelden vertrouwt.

Een Gather-observatie in results heeft type: "gather", node_id, UUID command_id, digits en reason. Een opname-observatie heeft type: "recording", UUID command_id, state en een recording_id als die beschikbaar is. Gebruik privécijfers alleen voor het bedoelde verzoek. Ze worden geen bewaarde expressie-outputs. Vervolgverzoeken behouden dezelfde node-occurrence, waarbij al afgeleverde observaties uit results zijn verwijderd.

Fouten afhandelen

Een technisch voorbeeld gebruikt de poort failure met {"code":"webhook_unavailable"} of {"code":"webhook_invalid_response"}. Een verbonden fout volgt het herstelpad. Een niet-verbonden fout laat de run mislukken. Een niet-verbonden success beëindigt de run op de normale manier. Live webhookverzoeken hebben een deadline van drie seconden en worden niet automatisch opnieuw geprobeerd. Preview doet geen verzoek.

De deadline van drie seconden omvat het lezen van het ondertekeningsgeheim. Verbind failure met een herstelpad, zodat de call kan doorgaan als de receiver niet beschikbaar is of een ongeldig antwoord geeft. Een verzoek met een time-out kan bij de receiver al een neveneffect hebben veroorzaakt.

Behandel data, de call-identiteit en Gather-cijfers als privé. Beperk de toegang tot de receiver en het geheim, log geen bodies of geheimen, en bewaar invoer van bellers alleen zolang je applicatie die nodig heeft. Zet geen privédata of inloggegevens in URL's: de calltrace bewaart de volledige URL, inclusief de query. De opgegeven URL en data en de gevalideerde output worden bewaard in de rungeschiedenis. Tijdelijke Gather-cijfers worden uitgesloten van de vastgelegde stapinvoer. Geef alleen data terug die de sequence nodig heeft.

Lees teruggegeven data bij steps.decision.output en technische fouten bij steps.decision.error.code. Als beide paden samenkomen, controleer de wrapper dan met has(steps.decision.output) of has(steps.decision.error) voordat je hem gebruikt. Een HTTP 200 van je receiver betekent pas een geldige uitkomst als de body aan het contract voldoet.