# Define Data Mapping and Webhook Payloads import Alert from "react-bootstrap/Alert"; # Define Data Mapping and Webhook Payloads Preserving customer context during a bot-to-agent transition requires careful configuration of payload delivery channels. In this step, we will have to map outbound variables into the voice path signaling layer and configure the automated bot platform to push structured JSON context payloads back into Zoom's secure REST endpoints. ### Establish Inbound Integration Data Strategies First, we will have to analyze incoming payload attributes and select the appropriate ingestion method based on data size, structure, and classification type. | Ingestion Strategy | Architectural Requirement | Production Use Case Example | | :---------------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | | **SIP Header Mapping** | Lightweight, non-PII primitive values processed natively by telephony routing layers. | Passing a simple intent flag like `X-Intent: Billing` or a verification status string like `X-Auth: True`. | | **API Webhook Mapping** | Complex arrays, lengthy texts, markdown structures, or sensitive PII that must not appear in cleartext SIP traces. | Delivering an interactive `account_summary` paragraph, explicit verification logs, or active chat `interaction_transcripts`. | ### Map Outbound Telephony Metadata (Zoom ──> Bot) Next, we will have to capture call attributes originating from Zoom Contact Center and pass them directly into the bot platform within the network signaling stream. > **Protocol Constraint:** Outbound parameter mapping from the Zoom Contact Center engine directly to an external voice destination platform is executed exclusively via **SIP Headers**. Natively triggered outbound HTTP REST calls are not driven from this widget block. - **`X-ZOOM-DNIS`**: we will have to map this header to deliver the original dialed destination identification strings to the bot engine. - **`X-ZOOM-WEBHOOK`**: we will have to map this header to deliver the unique runtime Static Webhook URL string assigned to your connection instance. > **Architectural Benefit:** Delivering the `X-ZOOM-WEBHOOK` parameter within the outbound signaling layer removes the operational requirement for the third-party voice platform to maintain hardcoded lookups mapping termination phone numbers to specific destination API tenants. The bot platform reads this header value dynamically to discover its callback destination. ### Program Asynchronous Inbound Telemetry (Bot ──> Zoom) Next, we will have to configure the automated bot platform to issue programmatic HTTP `POST` requests directly to the extracted unique **Static URL** endpoint. > **Critical Timing Constraints:** Webhook payloads **must** be successfully transmitted to and acknowledged by Zoom with an HTTP `200 OK` response status **prior** to line termination or the execution of a `SIP REFER` handoff sequence. Any payload submitted after call tear-down or line disconnection will be rejected. #### A. Metadata Context Delivery (`voicebot_metadata`) To link bot context variables to active Zoom Engagement or Consumer profile fields, we will have to structure the payload array to exactly match the variable names pre-registered inside the **Inbound from Bot** visual configurations. - **Method:** `POST` - **Content-Type:** `application/json` ##### Request Schema Example: ```json { "event": "voicebot_metadata", "conversationId": "c8221dc1-0af6-4daf-9e89-259a4b36164c", "metadata": [ { "key": "engagement_notes", "value": "Customer requires immediate support for a billing anomaly." }, { "key": "customer_city", "value": "San Francisco" }, { "key": "customer_email", "value": "john.doe@example.com" }, { "key": "detected_intent", "value": "billing_inquiry" } ] } ``` ### B. Conversational Abstract Delivery (`voicebot_conversation_summary`) To display a text summary inside the live agent's active desktop panel view immediately upon transfer, structure the JSON object text block as follows: **Method:** `POST` **Content-Type:** `application/json` **Request Schema Example:** ```json { "event": "voicebot_conversation_summary", "conversationId": "c8221dc1-0af6-4daf-9e89-259a4b36164c", "text": "The caller reached out regarding their recent invoice. They questioned a $49.99 subscription fee. The bot verified identity and clarified the charge. The user requested agent escalation for credential modifications." } ``` ### C. Continuous Dialogue Log Delivery (`voicebot_conversation_transcript`) To map conversation strings to the historical agent panel viewer log layout, send an ordered array containing timestamps and speaker identity booleans. **Method:** `POST` **Content-Type:** `application/json` **Request Schema Example:** ```json { "event": "voicebot_conversation_transcript", "conversationId": "c8221dc1-0af6-4daf-9e89-259a4b36164c", "messages": [ { "bot": true, "message": "Hello! Thank you for calling Customer Support. How can I assist you today?", "timestamp": 1767318930000 }, { "bot": false, "message": "Hi, I have a question about my recent bill.", "timestamp": 1767318935000 } ] } ``` ### Configure Queue Re-Entry Routing (SIP REFER) Finally, program the voice bot architecture to cleanly release media anchor points and transfer call execution tracking back into active Zoom Contact Center human agent queues. To return line processing control back to Zoom, the external telephony platform must issue a standard SIP REFER directive. The `Refer-To` parameter field configuration format must align with this precise URI structure: ```http Refer-To: ```