# Marketplace action request and response flow

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

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**

```html
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**

```json
{
    "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**

| API response field  | Skill variable  |
| ------------------- | --------------- |
| `orderStatus`       | `order_status`  |
| `estimatedDelivery` | `delivery_date` |

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}}`."