Marketplace action request and response flow

A Marketplace action follows a clear sequence:

• Trigger
• Request
• Validation
• Response
• Mapping

Trigger the action

A user interaction or system event triggers the action. Common trigger sources:

• Zoom Virtual Agent (ZVA)
• Contact Center flow
• External system via API

Example

When a user says "Get my order status," ZVA triggers the GetOrderStatus action.

Format the request

The skill sends an HTTP request to your app endpoint through Zoom Marketplace. You should include:

• Action name
• Input parameters (for example, order ID or phone number)
• User or session context
• Authentication token or signature

Example request

POST /getOrderStatusContent-Type: application/json { "orderId": "ORD1002"}

The Virtual Agent captures ORD1002 from user input and passes it to the API request.

Validate and authenticate the request

Your backend must validate and secure every request.

• Verify the request signature to confirm authenticity.
• Authenticate the request using OAuth or JWT.
• Validate all required input parameters and formats.
• Return an error immediately if validation fails. Do not continue processing.

Process and return the response

Your API processes the request and returns a structured JSON response.

Example response

{
    "success": true,
    "orderId": "ORD1002",
    "customerName": "David Smith",
    "orderStatus": "Processing",
    "trackingNumber": null,
    "estimatedDelivery": "2026-03-25"
}

Handle the response in the skill

Zoom processes the API response and updates the conversation.

• Map response fields to skill variables
• Inject data into the active flow
• Generate a natural language response for chat or voice

Example response to the user

"Your order has been shipped and will arrive by March 25."

Map response variables in AI Studio

Map API response fields to skill variables so the agent can use the returned data in responses.

Example mapping

This mapping enables the agent to reference structured data in responses.

Example usage

"Your order status is {{order_status}} and the estimated delivery date is {{delivery_date}}."