{
  "openapi": "3.1.0",
  "info": {
    "title": "Wave API",
    "version": "1.0.0",
    "description": "Wave API Platform — voice, numbers, and messaging for Saudi Arabia. Request schemas are GENERATED from the @wave-sa/shared Zod schemas — do not edit by hand (run `pnpm --filter @wave-sa/api generate:openapi`)."
  },
  "servers": [
    {
      "url": "https://api.wave.sa"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/callback": {
      "post": {
        "summary": "Place a web callback",
        "description": "Initiates a sandbox click-to-call: Wave dials `to` and bridges it to the destination. Returns immediately with `status: \"initiated\"`. Terminal statuses (`answered`/`ended`) are not emitted yet — see the Web Callback guide.",
        "operationId": "placeCallback",
        "tags": ["Callbacks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "x-wave-simulate",
            "in": "header",
            "required": false,
            "description": "Sandbox-only. Force a simulated error variant for testing. Ignored by production keys.",
            "schema": {
              "type": "string",
              "enum": [
                "rate_limit",
                "invalid_queue",
                "queue_unavailable",
                "server_error",
                "invalid_number",
                "success",
                "missed",
                "timeout"
              ]
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$"
                  },
                  "from_queue": {
                    "type": "string"
                  },
                  "caller_id_name": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "caller_id_number": {
                    "type": "string"
                  },
                  "webhook_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https\\:\\/\\/"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                },
                "required": ["to"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Callback initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallbackAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Sandbox trial expired or permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded, or the organization is over a call velocity limit (CALL_VELOCITY_EXCEEDED; see the Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls": {
      "post": {
        "summary": "Place an outbound call",
        "description": "Programmatically originates a call to `to`. Requires the `calls:write` scope. A production key (`sk_live_`) places the call from your project's own number. A sandbox key (`sk_sandbox_`) places a real call from the shared Wave number; it counts toward the project's 15 sandbox minutes and is not billed. When the minutes are used up, a real sandbox call returns `403 SANDBOX_MINUTES_EXCEEDED`. **Test your IVR:** send `callflow` (the name of a stored callflow of your organization) with a sandbox key, and the call plays that flow from the first turn: its live version, or its newest saved version when none is live. A production key gets `400 VALIDATION_ERROR` for `callflow`; an unknown name gets `404 NOT_FOUND`; `callflow` cannot be combined with `machine_detection`; a callflow that is not a menu or a graph gets `400 VALIDATION_ERROR`. With `machine_detection: true`, Wave checks who answers first: a machine → Wave hangs up; a person (or not sure) → the call goes on as usual. The verdict is `machine_detection_result` on the call log and in `call.answered` / `call.ended`. `machine_detection` returns 400 where campaigns are not enabled yet.",
        "operationId": "placeCall",
        "tags": ["Calls"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "to": {
                    "type": "string",
                    "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$"
                  },
                  "caller_id_name": {
                    "type": "string",
                    "maxLength": 64
                  },
                  "caller_id_number": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "machine_detection": {
                    "type": "boolean"
                  },
                  "callflow": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9 _-]+$"
                  }
                },
                "required": ["to"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Call initiated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Permission denied, or the project's sandbox minutes are used up (SANDBOX_MINUTES_EXCEEDED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The named `callflow` does not exist",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded, or the organization is over a call velocity limit (CALL_VELOCITY_EXCEEDED; see the Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List call logs",
        "description": "Returns the project's call logs (CDR), newest first, with masked customer numbers. Requires the `calls:read` scope.\n\n**Two ways to page.** *Cursor mode* (the default): send `cursor` and `limit`; the answer has `next_cursor` (pass it back as `cursor`; `null` on the last page). *Page mode*: send `page` and/or `page_size`; the answer has `total_count`, `page` and `page_size`. Send one mode, not both: `cursor` together with `page` or `page_size` is a `400`. Existing clients that send only `cursor` and `limit` are not affected.\n\n**Filters** work in both modes and can be combined. `from` and `to` are inclusive and filter on the time the call was created; with neither, all calls are returned (there is no default range). `from` must not be later than `to`. `status` takes one raw call status. `queue_id` matches calls that carry a queue id; only callback calls carry one, so web-calling and inbound calls never match.\n\n**Environments.** A sandbox key (`sk_sandbox_`) lists, reads and acts on sandbox rows only; a production key (`sk_live_`) on production rows only. A row of the other environment returns `404`, as if it did not exist. This also holds for the in-call control, transfer, conference and recording routes of a call.",
        "operationId": "listCalls",
        "tags": ["Calls"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Cursor mode: the `next_cursor` of the previous page. Cannot be sent with `page` or `page_size`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Cursor mode: page size.",
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page mode: the page number, starting at 1. Cannot be sent with `cursor`.",
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Page mode: calls per page (default 20). Cannot be sent with `cursor`.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only calls with this status (one raw value).",
            "schema": {
              "type": "string",
              "enum": [
                "initiated",
                "ringing",
                "answered",
                "ended",
                "missed",
                "failed",
                "cancelled",
                "timeout"
              ]
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Only calls created at or after this time (ISO 8601 date-time).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Only calls created at or before this time (ISO 8601 date-time).",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "queue_id",
            "in": "query",
            "required": false,
            "description": "Only calls from this queue. Only callback calls carry a queue id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key_id",
            "in": "query",
            "required": false,
            "description": "Only calls that this API key placed (a UUID). A revoked key of the project works too.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "environment",
            "in": "query",
            "required": false,
            "description": "`sandbox` or `production`. An API key reads only its own key environment: leave this out, or send the key's own value. Another value returns `400 VALIDATION_ERROR`.",
            "schema": {
              "type": "string",
              "enum": ["sandbox", "production"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of call logs. Cursor mode returns `CallList`; page mode returns `CallListPage`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/CallList"
                    },
                    {
                      "$ref": "#/components/schemas/CallListPage"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query: a bad date, `from` later than `to`, an unknown `status`, `page_size` over 100, `cursor` sent together with `page` or `page_size`, or `environment` is not your key's environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `calls:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/hangup": {
      "post": {
        "summary": "Hang up a call",
        "description": "Ends a live call (a callback, an outbound call or an inbound call). Allowed while the call is `initiated`, `ringing` or `answered`. With `leg: \"agent\"`, drops only the connected agent leg. The `call.hangup` / `call.ended` webhooks still come from the call's normal end event. Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "hangupCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/hold": {
      "post": {
        "summary": "Put a call on hold",
        "description": "Puts an answered call on hold. Both sides hear silence (no hold music yet). Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "holdCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/unhold": {
      "post": {
        "summary": "Take a call off hold",
        "description": "Takes an answered call off hold and restores the audio. Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "unholdCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/mute": {
      "post": {
        "summary": "Mute a call",
        "description": "Mutes the chosen leg of an answered call (default: the customer leg). Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "muteCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/unmute": {
      "post": {
        "summary": "Unmute a call",
        "description": "Unmutes the chosen leg of an answered call (default: the customer leg). Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "unmuteCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/dtmf": {
      "post": {
        "summary": "Send DTMF digits into a call",
        "description": "Sends DTMF tones into an answered call, for example to drive a remote IVR. `digits` is 1 to 32 characters from `0-9`, `*` and `#`. The digits are not stored in the audit log. Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "sendCallDtmf",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "digits": {
                    "type": "string",
                    "pattern": "^[0-9*#]{1,32}$"
                  },
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "required": ["digits"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/play": {
      "post": {
        "summary": "Play audio into a call",
        "description": "Plays an audio file into an answered call. `url` must be a public `https` URL (at most 2048 characters) that the voice engine can fetch; a URL that points to a private, loopback, link-local or other internal address is refused with `400 INVALID_PLAY_URL`. The URL is not stored in the audit log. Wave checks the host's DNS answer when you call this route; the engine fetches the file afterwards. Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "playCallAudio",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2048
                  },
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "required": ["url"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/recording/start": {
      "post": {
        "summary": "Start recording a call",
        "description": "Starts recording an answered call. When the recording is ready, fetch it with `GET /v1/calls/{call_id}/recording`. This route also needs in-call recording control to be enabled on the environment (503 until then). Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "startCallRecording",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/recording/stop": {
      "post": {
        "summary": "Stop recording a call",
        "description": "Stops a recording started on an answered call. This route also needs in-call recording control to be enabled on the environment (503 until then). Requires the `calls:write` scope. A `200` means the voice engine accepted the command; it does not wait for the action to finish. Works on calls that Wave placed and on inbound calls to your numbers; web-calling calls are not controllable (the calling SDK controls the browser's own leg). **Correction (30 Oct 2026):** web-calling calls stay not controllable here; to hold its own call, the browser uses session hold (`POST /v1/webrtc/call/hold` / `unhold`, called by the SDK's `holdCall()` / `resumeCall()`). The optional body field `leg` picks the leg: `customer` (default) or `agent` — the agent leg that is connected now (by a `<Dial>` or a queue). The agent leg needs agent-leg control to be enabled on the environment (503 until then); with no connected agent the API answers `409 AGENT_LEG_NOT_CONNECTED`.",
        "operationId": "stopCallRecording",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallControlAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (for example, an unknown `leg`)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not complete the action",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control (or, for `leg: \"agent\"`, agent-leg control) not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/transfer": {
      "post": {
        "summary": "Transfer a call",
        "description": "Blind-transfers the caller (the customer leg) of an answered call to a `target`, with no announcement to the target first. Do not depend on the current agent leg staying connected after the transfer. `target.type` is `number` (a KSA phone number; the caller-ID is your Wave number on this call), `user` (a web-calling identity of your organization) or `queue` (a queue of your organization). Works on calls that Wave placed and on inbound calls; web-calling calls are not controllable. Wave answers `202` at once; one `call.transferred` webhook later reports the `outcome`: `answered`, `no_answer`, `busy`, `failed`, `cancelled`, `enqueued` or `expired`. If the target does not answer, the call ends. On a simulated sandbox call the transfer completes at once with `answered`. Requires the `calls:write` scope. Needs in-call control and call transfer to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "transferCall",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "target": {
                    "type": "object",
                    "properties": {
                      "type": {
                        "type": "string",
                        "enum": ["number", "user", "queue"]
                      },
                      "value": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    },
                    "required": ["type", "value"],
                    "additionalProperties": false
                  }
                },
                "required": ["target"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The transfer was requested",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallTransferAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (a missing or unknown target type)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The call has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), already has a transfer in progress (TRANSFER_IN_PROGRESS), already had 3 transfers (TRANSFER_LIMIT_REACHED), or its type does not accept in-call actions (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The target has a bad format or is not your organization's (TRANSFER_TARGET_INVALID)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded, or the organization is over a call velocity limit (CALL_VELOCITY_EXCEEDED; see the Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Call transfer is not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not start the transfer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control or call transfer not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/transfers": {
      "get": {
        "summary": "List a call's transfers",
        "description": "Returns the call's transfers, newest first, with their status (`requested`, `dialing`, or an outcome). Requires the `calls:read` scope. Needs call transfer to be enabled on the environment (503 until then).",
        "operationId": "listCallTransfers",
        "tags": ["In-call control"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The call's transfers",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallTransferList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the calls:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control or call transfer not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/conference": {
      "post": {
        "summary": "Add a call to a conference room",
        "description": "Puts a live, answered call into the conference room named `room` (your label: 1 to 64 letters, digits, `.`, `_` or `-`). The first call that joins a label starts a new room; later calls with the same label join it. Labels are per project, and an ended room is never reused (the next join starts a new room). `leg` is `customer` (default) or `agent` (the connected agent leg; needs agent-leg control). A call is in at most one room; joining the same room again returns `200` with no change. A room holds at most 10 members. To remove a member, hang up that call (`POST /v1/calls/{call_id}/hangup`) — this ends the call. A member who is alone in the room hears silence. Webhooks: `conference.created` (first join) and `conference.member_joined`. Works on calls that Wave placed and on inbound calls; web-calling calls cannot join. Live keys only. Requires the `conferences:write` scope. Needs in-call control and conferencing to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "joinConference",
        "tags": ["Conferencing"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "room": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9._-]{1,64}$"
                  },
                  "leg": {
                    "type": "string",
                    "enum": ["customer", "agent"],
                    "default": "customer"
                  }
                },
                "required": ["room"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The call is in the room",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConferenceJoined"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (a bad `room` label or `leg`), or a sandbox key (SANDBOX_KEY_NOT_ALLOWED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the conferences:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call in your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The room is full (CONFERENCE_FULL, 10 members), the call is in another room (CALL_ALREADY_IN_CONFERENCE), has ended (CALL_NOT_ACTIVE), is not answered yet (CALL_NOT_ANSWERED), has no connected agent leg for `leg: \"agent\"` (AGENT_LEG_NOT_CONNECTED), or cannot join (CALL_NOT_CONTROLLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Conferencing is not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not add the call",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control or conferencing not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conferences/{conference_id}": {
      "get": {
        "summary": "Get a conference room",
        "description": "Returns the room (status, label, member count) and every call that was in it, with its leg, join time and, once it left, its leave time and reason. Rooms of other projects return 404. Requires the `conferences:read` scope. Needs in-call control and conferencing to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "getConference",
        "tags": ["Conferencing"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "conference_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The room and its members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Conference"
                }
              }
            }
          },
          "400": {
            "description": "A sandbox key (SANDBOX_KEY_NOT_ALLOWED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the conferences:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such room in your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control or conferencing not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/conferences/{conference_id}/end": {
      "post": {
        "summary": "End a conference room",
        "description": "Ends the room: every member leaves it, and the room status becomes `ended`. Webhooks: one `conference.member_left` per member (reason `room_ended`), then `conference.ended`. Requires the `conferences:write` scope. Needs in-call control and conferencing to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "endConference",
        "tags": ["Conferencing"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "conference_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The room ended",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConferenceEnded"
                }
              }
            }
          },
          "400": {
            "description": "A sandbox key (SANDBOX_KEY_NOT_ALLOWED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the conferences:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such room in your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The room has already ended (CONFERENCE_ENDED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "Conferencing is not supported on this environment yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not end the room",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control or conferencing not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns": {
      "post": {
        "summary": "Create a campaign",
        "description": "Creates a campaign: Wave calls each recipient, paces the calls under your concurrency cap and call limits, retries the ones that did not answer, and runs machine detection first on each answered call. A person hears the stored callflow `callflow_name`; a machine gets the optional `voicemail_message` after the beep. Recipients: 1 to 10000 KSA numbers (5 with a sandbox key), each with an optional `reference` (at most 64 characters, never spoken). Duplicates are removed; the response gives the accepted and removed counts. `caller_id` must be a number your account owns (a sandbox key always presents the shared sandbox number). `max_concurrent` defaults to half your concurrency cap and must be below it. Without `start_at` (or with a past one) the campaign starts at once. `calling_window` is a daily window in KSA time. The body may be up to 2 MB. Your account can hold at most 50000 recipients that are still waiting, across all its campaigns (409 CAMPAIGN_LIMIT_REACHED); stopped and completed campaigns do not count. Send an `Idempotency-Key` header so that a retry returns the first campaign and does not create a second one (the key is kept 24 hours; a refused request is not kept). A key creates a campaign of its own key environment: `environment` is optional, and another value than the key's own returns 400. Requires the `campaigns:write` scope, and stored callflows to be enabled (409 CAMPAIGN_NEEDS_IVR). Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "createCampaign",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Repeat-safe key; a retry returns the same campaign without creating a second one."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "callflow_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 100
                  },
                  "caller_id": {
                    "type": "string",
                    "maxLength": 20
                  },
                  "environment": {
                    "type": "string",
                    "enum": ["sandbox", "production"]
                  },
                  "recipients": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "phone": {
                          "type": "string",
                          "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$"
                        },
                        "reference": {
                          "type": "string",
                          "maxLength": 64
                        }
                      },
                      "required": ["phone"],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 10000
                  },
                  "start_at": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "calling_window": {
                    "type": "object",
                    "properties": {
                      "start": {
                        "type": "string",
                        "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                      },
                      "end": {
                        "type": "string",
                        "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$"
                      }
                    },
                    "required": ["start", "end"],
                    "additionalProperties": false
                  },
                  "max_attempts": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 5,
                    "default": 3
                  },
                  "retry_after_minutes": {
                    "type": "integer",
                    "minimum": 10,
                    "maximum": 1440,
                    "default": 30
                  },
                  "max_concurrent": {
                    "type": "integer",
                    "minimum": 1
                  },
                  "voicemail_message": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["play"]
                          },
                          "url": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 2048
                          }
                        },
                        "required": ["type", "url"],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "type": {
                            "type": "string",
                            "enum": ["say"]
                          },
                          "text": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 500
                          },
                          "language": {
                            "type": "string",
                            "enum": ["ar", "en"]
                          }
                        },
                        "required": ["type", "text"],
                        "additionalProperties": false
                      }
                    ]
                  }
                },
                "required": ["name", "callflow_name", "recipients"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The campaign; no call is placed yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignCreated"
                }
              }
            }
          },
          "400": {
            "description": "Validation error: a bad phone row (the message names it), too many recipients, an unknown callflow, a missing caller ID, `max_concurrent` at or above your cap, a bad play URL, or `environment` is not your key's environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:write scope, or the caller ID is not yours (CLI_NOT_OWNED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Stored callflows are not enabled on this environment (CAMPAIGN_NEEDS_IVR); your account has too many recipients still waiting (CAMPAIGN_LIMIT_REACHED); or a request with the same Idempotency-Key is still running (IDEMPOTENCY_KEY_CONFLICT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "The body is over 2 MB",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List campaigns",
        "description": "The project's campaigns, newest first, as a cursor page. A sandbox key lists sandbox campaigns only, and a production key production campaigns only. Requires the `campaigns:read` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "listCampaigns",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "environment",
            "in": "query",
            "required": false,
            "description": "`sandbox` or `production`. An API key reads only its own key environment: leave this out, or send the key's own value. Another value returns `400 VALIDATION_ERROR`.",
            "schema": {
              "type": "string",
              "enum": ["sandbox", "production"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of campaigns",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignPage"
                }
              }
            }
          },
          "400": {
            "description": "A bad cursor or limit, or `environment` is not your key's environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}": {
      "get": {
        "summary": "Get a campaign",
        "description": "The campaign with its recipient counts per state and per outcome, and `credits`: the credits charged on its calls. Campaigns of other projects return 404. Requires the `campaigns:read` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "getCampaign",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignDetail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such campaign in your project, or it is of the other environment of your key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/recipients": {
      "get": {
        "summary": "List a campaign's recipients",
        "description": "The campaign's recipients, newest first, as a cursor page. Filter with `outcome`. Requires the `campaigns:read` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "listCampaignRecipients",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "outcome",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "answered",
                "voicemail",
                "no_answer",
                "busy",
                "failed",
                "skipped",
                "cancelled"
              ]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of recipients",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignRecipientPage"
                }
              }
            }
          },
          "400": {
            "description": "A bad outcome, cursor or limit",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such campaign in your project, or it is of the other environment of your key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/pause": {
      "post": {
        "summary": "Pause a campaign",
        "description": "A running campaign stops sending new calls; calls already live go on to their end. Resume it later to go on where it stopped. Requires the `campaigns:write` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "pauseCampaign",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign after the change",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignDetail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such campaign in your project, or it is of the other environment of your key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The campaign's status does not allow this change (CAMPAIGN_INVALID_STATE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/resume": {
      "post": {
        "summary": "Resume a campaign",
        "description": "A paused campaign starts sending calls again. Requires the `campaigns:write` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "resumeCampaign",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign after the change",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignDetail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such campaign in your project, or it is of the other environment of your key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The campaign's status does not allow this change (CAMPAIGN_INVALID_STATE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/campaigns/{campaign_id}/stop": {
      "post": {
        "summary": "Stop a campaign",
        "description": "Stops a scheduled, running or paused campaign for good: no new call starts, and every recipient without an outcome gets `cancelled` (one `campaign.recipient_completed` each, then `campaign.completed` with status `stopped`). Calls already live go on to their end. A stopped campaign cannot be resumed. Requires the `campaigns:write` scope. Needs campaigns to be enabled on the environment (503 until then); not available in production yet.",
        "operationId": "stopCampaign",
        "tags": ["Campaigns"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "campaign_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The campaign after the change",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CampaignDetail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the campaigns:write scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such campaign in your project, or it is of the other environment of your key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The campaign's status does not allow this change (CAMPAIGN_INVALID_STATE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Campaigns are not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webrtc/config": {
      "post": {
        "summary": "Open a Web Calling session",
        "description": "Opens a browser calling session for the Wave Web Calling SDK and returns its SIP credentials. The SDK calls this for you. Two kinds of session:\n\n- **Agent session** — send an `identity` (a name you choose for the agent, for example `agent-1001`). The browser registers as that identity, so a queue login or a callflow `<Dial>` with the same name rings it. Wave creates the identity's SIP user on first use and gives it a new password for every session. Opening a new session for an identity ends the older one (the newest session wins).\n- **Caller session** — send no `identity`, for example for a website visitor who calls your business. The session can only call out. Wave gives it a temporary SIP user and deletes that user when the session ends.\n\n`identity` rules: 1–64 characters from `A–Z`, `a–z`, `0–9`, `.`, `_` and `-`. Identities that start with `p_` (portal members) or `c_` (caller sessions) are reserved. An identity needs at least one non-digit, and the words `anonymous`, `unknown`, `restricted`, `private` and `unavailable` (any case) are refused. An identity that already names a SIP user Wave did not create (for example your desk phone) is refused with `409 IDENTITY_CONFLICT`. Sandbox keys ignore `identity` and always open a caller session. The request `Origin` must be in the project's allowed origins. Requires the `webrtc:write` scope.",
        "operationId": "createWebrtcSession",
        "tags": ["Web Calling"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "identity": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9._-]{1,64}$",
                    "description": "The web-calling identity for an agent session. Omit it for a caller session.",
                    "example": "agent-1001"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session was opened",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WebrtcSession"
                }
              }
            }
          },
          "400": {
            "description": "The identity is badly formed, uses a reserved `p_` / `c_` prefix, is only digits, or is a caller-ID word (INVALID_IDENTITY)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The Origin is not allowed (ORIGIN_NOT_ALLOWED), or the key cannot use Web Calling",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The identity names a SIP user Wave did not create (IDENTITY_CONFLICT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "The media relay is misconfigured (TURN_UNAVAILABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine could not provision the session (WEBRTC_PROVISIONING_FAILED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webrtc/call/hold": {
      "post": {
        "summary": "Hold the session's own call",
        "description": "Puts the live call of a Web Calling session on hold. The far party hears silence and the call stays connected. The calling SDK calls this for you (`holdCall()` / `resumeCall()`).\n\nSend the session token `wcs` in the body — no API key and no `Authorization` header. Wave finds the session's own live call from the session; a session can never hold another call. The token is not rotated. A `200` means the voice engine accepted the command. No webhook is sent.\n\nOnly an agent or caller session that has its own SIP user can use it; otherwise the API answers `409 CALL_NOT_ACTIVE`. Ships dark behind in-call control (`503 CALL_CONTROL_DISABLED` until it is enabled on the environment).",
        "operationId": "holdWebrtcCall",
        "tags": ["Web Calling"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wcs": {
                    "type": "string",
                    "description": "The current Web Calling session token (`wcs_…`)."
                  }
                },
                "required": ["wcs"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The voice engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": {
                      "type": "string",
                      "enum": ["hold"]
                    },
                    "session_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  },
                  "required": ["action", "session_id", "request_id"]
                }
              }
            }
          },
          "400": {
            "description": "The body has no valid session token (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The session token is unknown, expired, revoked or already replaced (WCS_NOT_FOUND, WCS_EXPIRED, WCS_REVOKED, WCS_REUSE_DETECTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The session has no live call (CALL_NOT_ACTIVE), or the call is not answered yet (CALL_NOT_ANSWERED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment (CALL_CONTROL_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine refused or failed (CALL_CONTROL_FAILED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control is not enabled (CALL_CONTROL_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/webrtc/call/unhold": {
      "post": {
        "summary": "Resume the session's held call",
        "description": "Takes the session's held call off hold; the audio comes back both ways. The calling SDK calls this for you (`holdCall()` / `resumeCall()`).\n\nSend the session token `wcs` in the body — no API key and no `Authorization` header. Wave finds the session's own live call from the session; a session can never hold another call. The token is not rotated. A `200` means the voice engine accepted the command. No webhook is sent.\n\nOnly an agent or caller session that has its own SIP user can use it; otherwise the API answers `409 CALL_NOT_ACTIVE`. Ships dark behind in-call control (`503 CALL_CONTROL_DISABLED` until it is enabled on the environment).",
        "operationId": "unholdWebrtcCall",
        "tags": ["Web Calling"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "wcs": {
                    "type": "string",
                    "description": "The current Web Calling session token (`wcs_…`)."
                  }
                },
                "required": ["wcs"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The voice engine accepted the command",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "action": {
                      "type": "string",
                      "enum": ["unhold"]
                    },
                    "session_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "request_id": {
                      "type": "string"
                    }
                  },
                  "required": ["action", "session_id", "request_id"]
                }
              }
            }
          },
          "400": {
            "description": "The body has no valid session token (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The session token is unknown, expired, revoked or already replaced (WCS_NOT_FOUND, WCS_EXPIRED, WCS_REVOKED, WCS_REUSE_DETECTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The session has no live call (CALL_NOT_ACTIVE), or the call is not answered yet (CALL_NOT_ANSWERED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "501": {
            "description": "In-call actions are not supported on this environment (CALL_CONTROL_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The voice engine refused or failed (CALL_CONTROL_FAILED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "In-call control is not enabled (CALL_CONTROL_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/usage": {
      "get": {
        "summary": "Get usage",
        "description": "Returns the usage of one project for a period: total calls, answered calls, missed calls, call minutes, and the credits charged. Requires the `usage:read` scope.\n\n**Counts.** `total_calls` counts every call that matches the filters. `calls_answered` counts calls that connected (a finished answered call is still an answered call). `calls_missed` counts calls nobody picked up. Failed, cancelled and timed-out calls count only in `total_calls`, so answered plus missed can be lower than the total.\n\n**Period.** `from` and `to` are inclusive and filter on the time the call was created. With neither, the period is all time and `period` shows `null`. `from` must not be later than `to`.\n\n**Queue.** `queue_id` matches calls that carry a queue id. Only callback calls carry one; web-calling and inbound calls never match.\n\n**Credits.** `credits` is the sum of the credits Wave charged on the calls, exact to 4 decimals (the portal rounds up to whole credits). Each production call is charged at its call class on the rate card; sandbox calls, beta calls and calls that nobody answered are not charged and add `0`. See Billing.\n\n**Grouping.** Add `group_by` to also get a `groups` list with the same metrics per group. `day` and `hour` use the Saudi calendar (Asia/Riyadh, UTC+03:00): each `key` is the start of the day or hour with a `+03:00` offset, oldest first, and a day or hour with no calls is not listed. They need both `from` and `to`; the range can be at most 31 days for `hour` and 366 days for `day`. `status` groups by the raw call status and needs no range. `queue` lists the queues that have calls in the period (one group per queue id; calls without a queue are not listed) and needs no range; use it to fill a queue picker. `api_key` gives one group per API key (the `key` is the key id); calls that no key placed, such as inbound calls, are not a group, and it needs no range. The totals in `data` always cover the whole period.\n\n**Environments.** A sandbox key gets the usage of sandbox calls only, and a production key of production calls only. Send `environment` with a key only as the key's own value.",
        "operationId": "getUsage",
        "tags": ["Usage"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start of the period (ISO 8601 date-time), inclusive. Needed with `group_by=day` or `hour`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-01T00:00:00.000Z"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End of the period (ISO 8601 date-time), inclusive. Needed with `group_by=day` or `hour`.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-09-30T23:59:59.999Z"
          },
          {
            "name": "queue_id",
            "in": "query",
            "required": false,
            "description": "Only calls from this queue. Only callback calls carry a queue id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "api_key_id",
            "in": "query",
            "required": false,
            "description": "Only calls that this API key placed (a UUID). A revoked key of the project works too.",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "group_by",
            "in": "query",
            "required": false,
            "description": "Also return `groups`: `day` or `hour` (Asia/Riyadh buckets), `status` (raw call status), `queue` (the queues that have calls) or `api_key` (one group per API key; calls that no key placed, such as inbound calls, are not a group).",
            "schema": {
              "type": "string",
              "enum": ["day", "hour", "status", "queue", "api_key"]
            }
          },
          {
            "name": "environment",
            "in": "query",
            "required": false,
            "description": "`sandbox` or `production`. An API key reads only its own key environment: leave this out, or send the key's own value. Another value returns `400 VALIDATION_ERROR`.",
            "schema": {
              "type": "string",
              "enum": ["sandbox", "production"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Usage for the period",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query: a bad date, `from` later than `to`, an unknown `group_by`, `group_by=day|hour` without `from` and `to`, a range that is too long, or `environment` is not your key's environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `usage:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/audit-logs": {
      "get": {
        "summary": "List audit logs",
        "description": "Returns the audit log of your project, newest first: API keys made and changed, webhooks, numbers, Go-Live steps and other changes. An API key gets the entries of its own project only; the organization-level entries (members, billing, sign-ins) are shown only in the portal, to a member whose organization role is owner, admin or auditor. Read-only. Requires the `audit:read` scope.\n\n**Who has the scope.** Keys made on the Keys page by an owner, an admin or an auditor get `audit:read` by default. A developer cannot give a key `audit:read`. The keys that Wave makes for you (at sign-up, at project create and at Go-Live) do not get it. In the portal, a member can reveal a key only when their role may grant every scope the key holds.\n\n**Who made the change.** `actor` is `user` (a member of your organization; `user_id` is set), `system` (Wave did it, for example at Go-Live) or `wave_operator` (a Wave operator did it). For a `wave_operator` entry the operator's identity and IP address are not shown.\n\n**Filters.** `from` and `to` are inclusive and filter on the time of the change; `from` must not be later than `to`. `action`, `resource` and `resource_id` are exact matches.\n\n**Pages.** Send `limit` (1–100, default 20). The answer has `next_cursor`: pass it back as `cursor` for the next page; it is `null` on the last page.\n\n**Environments.** Audit entries have no environment: a sandbox key and a production key of the same project get the same entries.",
        "operationId": "listAuditLogs",
        "tags": ["Audit logs"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "Start of the period (ISO 8601 date-time), inclusive.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-01T00:00:00.000Z"
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "End of the period (ISO 8601 date-time), inclusive.",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "example": "2026-10-31T23:59:59.999Z"
          },
          {
            "name": "action",
            "in": "query",
            "required": false,
            "description": "Only entries with this action (exact match).",
            "schema": {
              "type": "string",
              "maxLength": 64
            },
            "example": "api_key.scopes_set"
          },
          {
            "name": "resource",
            "in": "query",
            "required": false,
            "description": "Only entries about this kind of resource (exact match).",
            "schema": {
              "type": "string",
              "maxLength": 64
            },
            "example": "api_key"
          },
          {
            "name": "resource_id",
            "in": "query",
            "required": false,
            "description": "Only entries about this resource id (exact match).",
            "schema": {
              "type": "string",
              "maxLength": 128
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Entries per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of the audit log",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditLogPage"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query: a bad date, `from` later than `to`, a `limit` outside 1–100, a value that is too long, or a bad `cursor`",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `audit:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callbacks": {
      "get": {
        "summary": "List callbacks",
        "description": "Returns your organization's callbacks, newest first, with masked customer numbers. Paged with `page` and `page_size`; the answer has `total_count`. Filters can be combined. `from` and `to` are inclusive and filter on the time the callback was created; **with neither, the last 7 days are returned**. `from` must not be later than `to`. Requires the `calls:read` scope.\n\n**Environments.** A sandbox key (`sk_sandbox_`) lists, reads and acts on sandbox rows only; a production key (`sk_live_`) on production rows only. A row of the other environment returns `404`, as if it did not exist.",
        "operationId": "listCallbacks",
        "tags": ["Callbacks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "One call status.",
            "schema": {
              "type": "string",
              "enum": [
                "initiated",
                "ringing",
                "answered",
                "ended",
                "missed",
                "failed",
                "cancelled",
                "timeout"
              ]
            }
          },
          {
            "name": "queue_id",
            "in": "query",
            "required": false,
            "description": "Only callbacks placed for this queue.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "ISO 8601 date-time, inclusive. Default: 7 days before now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "ISO 8601 date-time, inclusive. Default: now.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, from 1.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Callbacks per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          },
          {
            "name": "environment",
            "in": "query",
            "required": false,
            "description": "`sandbox` or `production`. An API key reads only its own key environment: leave this out, or send the key's own value. Another value returns `400 VALIDATION_ERROR`.",
            "schema": {
              "type": "string",
              "enum": ["sandbox", "production"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of callbacks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallbackList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters, `from` is later than `to`, or `environment` is not your key's environment (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `calls:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callbacks/{callback_id}": {
      "get": {
        "summary": "Get a callback",
        "description": "Returns one callback by the `callback_id` that `POST /v1/callback` returned. A callback of another organization, or an id that is not a UUID, returns `404`. Requires the `calls:read` scope.",
        "operationId": "getCallback",
        "tags": ["Callbacks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "callback_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The callback",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Callback"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `calls:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such callback, or it is of the other environment of your key (CALLBACK_NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Cancel a callback",
        "description": "Cancels a callback that has not been answered yet (status `initiated` or `ringing`). The status becomes `cancelled` and a `call.cancelled` webhook is sent. Requires the `calls:write` scope.",
        "operationId": "cancelCallback",
        "tags": ["Callbacks"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "callback_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The callback is cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallbackCancelled"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `calls:write` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such callback, or it is of the other environment of your key (CALLBACK_NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The callback is past `ringing` and can no longer be cancelled (CALLBACK_NOT_CANCELLABLE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/calls/{call_id}/recording": {
      "get": {
        "summary": "Get a call recording link",
        "description": "Returns a time-limited download link for the recording of one call in your project. Fetch it from your server and store the file in your own system before `expires_at`. Production keys only. Requires the `recordings:read` scope. A recording is available for 90 days after the call; after that this route returns 410 `RECORDING_EXPIRED`.",
        "operationId": "getCallRecording",
        "tags": ["Calls"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "call_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The download link",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallRecordingLink"
                }
              }
            }
          },
          "400": {
            "description": "A sandbox key: recordings are not available in sandbox mode (SANDBOX_KEY_NOT_ALLOWED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `recordings:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such call in your project, the call has no recording, or the call is of the other environment of your key (RECORDING_NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "The recording is older than 90 days and is no longer available (RECORDING_EXPIRED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "The recording link cannot be made right now (RECORDING_SERVICE_UNAVAILABLE); try again later",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages": {
      "post": {
        "summary": "Send a message",
        "description": "Sends one message (text, media or template) to `to` on `channel`. The answer is `202`: the provider accepted the message; delivery updates arrive later as `message.*` webhooks. A template send is a commercial message: it is refused (`403` `RECIPIENT_OPTED_OUT`) when the number opted out (see `/v1/consents`), and `422` `QUIET_HOURS_ACTIVE` inside the quiet-hours window (KSA time) where one is set. A text or media reply is not checked. Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "sendMessage",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "enum": ["whatsapp", "sms", "webchat", "email"]
                  },
                  "to": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "content": {
                    "anyOf": [
                      {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": ["text"]
                          },
                          "body": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 4096
                          }
                        },
                        "required": ["kind", "body"],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": ["media"]
                          },
                          "mediaType": {
                            "type": "string",
                            "enum": ["image", "document", "audio", "video"]
                          },
                          "url": {
                            "type": "string",
                            "format": "uri",
                            "pattern": "^https\\:\\/\\/"
                          },
                          "caption": {
                            "type": "string",
                            "maxLength": 1024
                          },
                          "filename": {
                            "type": "string",
                            "maxLength": 255
                          },
                          "contentType": {
                            "type": "string",
                            "maxLength": 255
                          },
                          "sizeBytes": {
                            "type": "integer",
                            "exclusiveMinimum": true,
                            "minimum": 0
                          }
                        },
                        "required": ["kind", "mediaType", "url"],
                        "additionalProperties": false
                      },
                      {
                        "type": "object",
                        "properties": {
                          "kind": {
                            "type": "string",
                            "enum": ["template"]
                          },
                          "name": {
                            "type": "string",
                            "minLength": 1,
                            "maxLength": 512
                          },
                          "language": {
                            "type": "string",
                            "minLength": 2,
                            "maxLength": 35
                          },
                          "variables": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          }
                        },
                        "required": ["kind", "name", "language"],
                        "additionalProperties": false
                      }
                    ]
                  },
                  "conversationId": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  }
                },
                "required": ["channel", "to", "content"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The provider accepted the message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageAccepted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope, or the recipient opted out of commercial messages (RECIPIENT_OPTED_OUT)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED), or a template send falls inside quiet hours (QUIET_HOURS_ACTIVE)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED), or the channel is not set up (CHANNEL_NOT_CONFIGURED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List messages",
        "description": "Returns the project's messages, inbound and outbound in one list, newest first. Cursor-paged: send `cursor` and `limit`; the answer has `next_cursor` (`null` on the last page). Requires the `messages:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listMessages",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Messages per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters or cursor (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/media": {
      "post": {
        "summary": "Upload a media file",
        "description": "Uploads one file (base64) and returns a `url` to use in a media message (`POST /v1/messages`). Upload first, then send. Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "uploadMessageMedia",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "channel": {
                    "type": "string",
                    "enum": ["whatsapp", "sms", "webchat", "email"],
                    "default": "whatsapp"
                  },
                  "base64": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 10000000
                  },
                  "fileName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  },
                  "contentType": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 255
                  }
                },
                "required": ["base64", "fileName", "contentType"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The file is uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadedMedia"
                }
              }
            }
          },
          "400": {
            "description": "Validation error, for example a file that is too large (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/templates": {
      "get": {
        "summary": "List message templates",
        "description": "Returns the WhatsApp templates and their approval status. Requires the `messages:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listMessageTemplates",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "The messaging channel. Default: `whatsapp`.",
            "schema": {
              "type": "string",
              "enum": ["whatsapp", "sms", "webchat", "email"],
              "default": "whatsapp"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The templates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageTemplateList"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "summary": "Create a message template",
        "description": "Submits a WhatsApp template for provider approval. The answer shows the template with status `pending`. Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "createMessageTemplate",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "templateId": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  },
                  "language": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 35
                  },
                  "category": {
                    "type": "string",
                    "enum": ["MARKETING", "UTILITY", "AUTHENTICATION"]
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  },
                  "variables": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "otpButton": {
                    "type": "boolean"
                  },
                  "header": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 60
                  },
                  "footer": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 60
                  },
                  "buttons": {
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["QUICK_REPLY"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            }
                          },
                          "required": ["type", "text"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["URL"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          },
                          "required": ["type", "text", "url"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["PHONE_NUMBER"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            },
                            "phoneNumber": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 20
                            }
                          },
                          "required": ["type", "text", "phoneNumber"],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "maxItems": 3
                  }
                },
                "required": ["name", "language", "category"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The template is submitted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageTemplate"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/messages/templates/{name}": {
      "get": {
        "summary": "Get a message template",
        "description": "Returns one template by name and language, with its body, header, footer and buttons. Requires the `messages:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "getMessageTemplate",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "The messaging channel. Default: `whatsapp`.",
            "schema": {
              "type": "string",
              "enum": ["whatsapp", "sms", "webchat", "email"],
              "default": "whatsapp"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": true,
            "description": "The template language code (a template name can exist in more than one language).",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 35
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The template",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageTemplateDetail"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No template with this name and language (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Update a message template",
        "description": "Replaces the content of an existing template (found by name and language) and submits it again for approval. Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "updateMessageTemplate",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "The messaging channel. Default: `whatsapp`.",
            "schema": {
              "type": "string",
              "enum": ["whatsapp", "sms", "webchat", "email"],
              "default": "whatsapp"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": true,
            "description": "The template language code (a template name can exist in more than one language).",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 35
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "templateId": {
                    "type": "string",
                    "maxLength": 128
                  },
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  },
                  "language": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 35
                  },
                  "category": {
                    "type": "string",
                    "enum": ["MARKETING", "UTILITY", "AUTHENTICATION"]
                  },
                  "body": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1024
                  },
                  "variables": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "otpButton": {
                    "type": "boolean"
                  },
                  "header": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 60
                  },
                  "footer": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 60
                  },
                  "buttons": {
                    "type": "array",
                    "items": {
                      "anyOf": [
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["QUICK_REPLY"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            }
                          },
                          "required": ["type", "text"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["URL"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            },
                            "url": {
                              "type": "string",
                              "format": "uri"
                            }
                          },
                          "required": ["type", "text", "url"],
                          "additionalProperties": false
                        },
                        {
                          "type": "object",
                          "properties": {
                            "type": {
                              "type": "string",
                              "enum": ["PHONE_NUMBER"]
                            },
                            "text": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 25
                            },
                            "phoneNumber": {
                              "type": "string",
                              "minLength": 1,
                              "maxLength": 20
                            }
                          },
                          "required": ["type", "text", "phoneNumber"],
                          "additionalProperties": false
                        }
                      ]
                    },
                    "maxItems": 3
                  }
                },
                "required": ["name", "language", "category"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The template is updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessageTemplate"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No template with this name and language (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a message template",
        "description": "Permanently deletes one template (name and language). Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "deleteMessageTemplate",
        "tags": ["Messaging"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "channel",
            "in": "query",
            "required": false,
            "description": "The messaging channel. Default: `whatsapp`.",
            "schema": {
              "type": "string",
              "enum": ["whatsapp", "sms", "webchat", "email"],
              "default": "whatsapp"
            }
          },
          {
            "name": "language",
            "in": "query",
            "required": true,
            "description": "The template language code (a template name can exist in more than one language).",
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 35
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The template is deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deleted"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "The channel does not support this action (CHANNEL_VERB_UNSUPPORTED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "The messaging provider failed; you can retry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/broadcasts": {
      "post": {
        "summary": "Create a broadcast",
        "description": "Sends one approved WhatsApp template to a saved contact group (`contactGroupId`) or to a list of your contacts (`contactIds`); send exactly one of the two. Without `scheduledAt`, or with a time in the past, the send starts now; with a future `scheduledAt`, the broadcast stays `pending` until then. A contact group has a recipient limit. Recipients whose number opted out (see `/v1/consents`) are skipped and counted in `result_summary.skipped`. Inside the quiet-hours window (KSA time, where one is set) each recipient fails with the reason `QUIET_HOURS_ACTIVE`. The answer is `202` with the broadcast; follow its `status` with `GET /v1/broadcasts/{id}`. Requires the `broadcasts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "createBroadcast",
        "tags": ["Broadcasts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contactGroupId": {
                    "type": "string",
                    "format": "uuid"
                  },
                  "contactIds": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "minItems": 1,
                    "maxItems": 1000
                  },
                  "templateName": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 512
                  },
                  "templateLanguage": {
                    "type": "string",
                    "minLength": 2,
                    "maxLength": 35
                  },
                  "templateVariables": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "string"
                    }
                  },
                  "scheduledAt": {
                    "type": "string",
                    "format": "date-time"
                  }
                },
                "required": ["templateName", "templateLanguage"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "The broadcast is accepted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Broadcast"
                }
              }
            }
          },
          "400": {
            "description": "Validation error: a bad body, a contact group or contact that is not yours, or a group over the recipient limit (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `broadcasts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List broadcasts",
        "description": "Returns your organization's broadcasts, newest first. Requires the `broadcasts:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listBroadcasts",
        "tags": ["Broadcasts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The broadcasts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BroadcastList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `broadcasts:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/broadcasts/{id}": {
      "get": {
        "summary": "Get a broadcast",
        "description": "Returns one broadcast with its status and result summary. Requires the `broadcasts:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "getBroadcast",
        "tags": ["Broadcasts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The broadcast",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Broadcast"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `broadcasts:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such broadcast (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Cancel a broadcast",
        "description": "Cancels a broadcast that is still `pending` (not sent yet, for example a scheduled one). Requires the `broadcasts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "cancelBroadcast",
        "tags": ["Broadcasts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The broadcast is cancelled",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BroadcastCancelled"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `broadcasts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The broadcast is not pending, or is not yours (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contact-groups": {
      "post": {
        "summary": "Create a contact group",
        "description": "Creates an empty contact group (a saved recipient list for broadcasts). Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "createContactGroup",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  }
                },
                "required": ["name"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The group is created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupSummary"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List contact groups",
        "description": "Returns your organization's contact groups, oldest first, with their member counts. Requires the `contacts:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listContactGroups",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The groups",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contact-groups/{id}": {
      "get": {
        "summary": "Get a contact group",
        "description": "Returns one contact group with its members. Requires the `contacts:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "getContactGroup",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The group and its members",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroup"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:read` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such contact group (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Rename a contact group",
        "description": "Changes the name of a contact group. Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "renameContactGroup",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 120
                  }
                },
                "required": ["name"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The group is renamed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupRenamed"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such contact group (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a contact group",
        "description": "Deletes a contact group. The contacts stay. Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "deleteContactGroup",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The group is deleted",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Deleted"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such contact group (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contact-groups/{id}/members": {
      "post": {
        "summary": "Add contacts to a group",
        "description": "Adds contacts (name and phone) to a group. A phone number that is already a contact of your organization reuses that contact; a contact that is already in the group is not added again. The answer gives how many were added out of how many were sent. Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "addContactGroupMembers",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contacts": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "maxLength": 120
                        },
                        "phone": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 128
                        }
                      },
                      "required": ["phone"],
                      "additionalProperties": false
                    },
                    "minItems": 1,
                    "maxItems": 1000
                  }
                },
                "required": ["contacts"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The contacts are added",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupMembersAdded"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such contact group (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contact-groups/{id}/members/{contactId}": {
      "delete": {
        "summary": "Remove a contact from a group",
        "description": "Removes one contact from a group. The contact stays. The answer is `200` also when the contact was not in the group. Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "removeContactGroupMember",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "contactId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The contact is removed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactGroupMemberRemoved"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope, or WhatsApp is not enabled for your organization (INSUFFICIENT_PERMISSIONS)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contacts": {
      "get": {
        "summary": "List contacts",
        "description": "Returns your organization's contacts, sorted by name, with their marketing opt-out flag. Requires the `contacts:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listContacts",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The contacts",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/contacts/{id}": {
      "patch": {
        "summary": "Set a contact's marketing opt-out",
        "description": "Sets or clears the marketing opt-out of one contact. The change is also recorded in the consent ledger (`/v1/consents`, source `contact`) for the contact's phone; broadcasts and template sends to an opted-out number are refused. Requires the `contacts:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "updateContactMarketingOptOut",
        "tags": ["Contacts"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "marketingOptedOut": {
                    "type": "boolean"
                  }
                },
                "required": ["marketingOptedOut"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The contact is updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ContactOptOut"
                }
              }
            }
          },
          "400": {
            "description": "Validation error (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `contacts:write` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such contact (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/consents": {
      "get": {
        "summary": "List consent records",
        "description": "Returns your organization's consent records, the most recently changed first. Filter with `status`. Cursor-paged: send `cursor` and `limit`; the answer has `next_cursor` (`null` on the last page). The ledger is per organization: one row covers every project and every messaging channel. A number with no row can receive commercial messages (templates and broadcasts). Requires the `messages:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "listConsents",
        "tags": ["Consents"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only records with this status.",
            "schema": {
              "type": "string",
              "enum": ["opted_out", "opted_in"]
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "The `next_cursor` of the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Records per page.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "One page of consent records",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentList"
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters or cursor (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/consents/{phone}": {
      "get": {
        "summary": "Get a number's consent",
        "description": "Returns the recorded consent of one number. The ledger is per organization: one row covers every project and every messaging channel. A number with no row can receive commercial messages (templates and broadcasts). Requires the `messages:read` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "getConsent",
        "tags": ["Consents"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The phone number, in any accepted form (`+9665…`, `9665…` or `05…`). URL-encode the `+`.",
              "example": "+966501234567"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The consent record",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consent"
                }
              }
            }
          },
          "400": {
            "description": "Not a phone number, or an invalid body (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:read` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No consent is recorded for this number (NOT_FOUND)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Record a number's consent",
        "description": "Records an opt-out or an opt-in for one number, with its evidence. An opt-in must carry `evidence` (where you collected it). Commercial messages (templates and broadcasts) to an opted-out number are refused. Every change is audited. An end user's own STOP / START reply on WhatsApp also changes the record. An end user's STOP is locked: an opt-in over it is refused (`409` `CONSENT_LOCKED_BY_END_USER`); only the end user's START lifts it, and an opt-out over it leaves the record unchanged. Requires the `messages:write` scope. Messaging is enabled per environment: where it is not enabled, every messaging, broadcast and contact route answers `503` with `MESSAGES_DISABLED`.",
        "operationId": "putConsent",
        "tags": ["Consents"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "phone",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "The phone number, in any accepted form (`+9665…`, `9665…` or `05…`). URL-encode the `+`.",
              "example": "+966501234567"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": ["opted_out", "opted_in"]
                  },
                  "evidence": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 1000
                  }
                },
                "required": ["status"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The consent is recorded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consent"
                }
              }
            }
          },
          "400": {
            "description": "Not a phone number, or an invalid body (VALIDATION_ERROR)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not have the `messages:write` scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The end user opted out with STOP; only their START can opt back in (CONSENT_LOCKED_BY_END_USER)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Messaging is not enabled on this environment (MESSAGES_DISABLED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/virtual-numbers": {
      "post": {
        "summary": "Allocate a virtual number to an end-user",
        "description": "Assigns a Saudi number to one of your end-users, identified by your `external_user_id`. Idempotent on that id. Requires the `virtual_numbers:write` scope and a production key.",
        "operationId": "allocateVirtualNumber",
        "tags": ["Virtual numbers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "external_user_id": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 128
                  },
                  "display_name": {
                    "type": "string",
                    "maxLength": 120
                  },
                  "type": {
                    "type": "string",
                    "enum": [
                      "mobile",
                      "landline",
                      "tollfree",
                      "unified",
                      "shortcode"
                    ]
                  },
                  "prefix": {
                    "type": "string",
                    "maxLength": 8
                  },
                  "instructions": {
                    "type": "object",
                    "properties": {
                      "text": {
                        "type": "string",
                        "maxLength": 1000,
                        "nullable": true
                      },
                      "audio_url": {
                        "type": "string",
                        "format": "uri",
                        "pattern": "^https\\:\\/\\/",
                        "maxLength": 1024,
                        "nullable": true
                      },
                      "language": {
                        "type": "string",
                        "maxLength": 8
                      },
                      "forward_to": {
                        "type": "string",
                        "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$",
                        "nullable": true
                      }
                    },
                    "additionalProperties": false
                  }
                },
                "required": ["external_user_id"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent retry — existing allocation returned",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualNumberEnvelope"
                }
              }
            }
          },
          "201": {
            "description": "Number allocated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualNumberEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Scope missing or permission denied",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List virtual-number allocations",
        "operationId": "listVirtualNumbers",
        "tags": ["Virtual numbers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "external_user_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 50,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 0,
              "minimum": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of allocations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualNumberList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/virtual-numbers/{id}": {
      "get": {
        "summary": "Get one allocation",
        "operationId": "getVirtualNumber",
        "tags": ["Virtual numbers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The allocation",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualNumberEnvelope"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Release a virtual number",
        "operationId": "releaseVirtualNumber",
        "tags": ["Virtual numbers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Released",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "example": "released"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/virtual-numbers/{id}/instructions": {
      "put": {
        "summary": "Update a user's instructions",
        "operationId": "updateVirtualNumberInstructions",
        "tags": ["Virtual numbers"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 1000,
                    "nullable": true
                  },
                  "audio_url": {
                    "type": "string",
                    "format": "uri",
                    "pattern": "^https\\:\\/\\/",
                    "maxLength": 1024,
                    "nullable": true
                  },
                  "language": {
                    "type": "string",
                    "maxLength": 8
                  },
                  "forward_to": {
                    "type": "string",
                    "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$",
                    "nullable": true
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VirtualNumberEnvelope"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voice-auth/challenges": {
      "post": {
        "summary": "Create a voice-authentication challenge",
        "description": "Places an outbound call asking the person to approve (press 1) / decline (press 2), or to key the shown digits in number_match mode. Requires the `voice_auth:write` scope. A sandbox key works too: the call comes from the shared Wave number, counts toward the project's sandbox minutes and is not billed. Fails closed — only `approved`/`declined` grant.",
        "operationId": "createVoiceAuthChallenge",
        "tags": ["Voice Authentication"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Repeat-safe key; a retry returns the same challenge without a second call."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone_number": {
                    "type": "string",
                    "description": "E.164 (+9665…) — the number Wave dials."
                  },
                  "locale": {
                    "type": "string",
                    "enum": ["ar", "en"],
                    "default": "ar"
                  },
                  "context": {
                    "type": "object",
                    "description": "Non-secret descriptor injected into the prompt.",
                    "properties": {
                      "action": {
                        "type": "string"
                      },
                      "app_name": {
                        "type": "string"
                      },
                      "reference": {
                        "type": "string"
                      }
                    },
                    "additionalProperties": false
                  },
                  "assurance": {
                    "type": "string",
                    "enum": ["standard", "number_match"],
                    "default": "standard"
                  },
                  "ttl_seconds": {
                    "type": "integer",
                    "minimum": 30,
                    "maximum": 180,
                    "default": 90
                  },
                  "retry_on_no_answer": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 2,
                    "default": 0
                  },
                  "callback_url": {
                    "type": "string",
                    "format": "uri"
                  },
                  "idempotency_key": {
                    "type": "string"
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  },
                  "brand_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "An approved caller brand of your organization to speak instead of \"Wave\". Absent → the project's default brand → \"Wave\"."
                  }
                },
                "required": ["phone_number"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Challenge created; call placed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "challenge_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string",
                      "example": "initiated"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "match_digits": {
                      "type": "string",
                      "description": "number_match only — display these to your user."
                    },
                    "brand_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true,
                      "description": "The caller brand the call speaks (null = \"Wave\")."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Sandbox key, missing scope, or blocklisted number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "422": {
            "description": "brand_id is not an approved caller brand of your organization (VOICE_AUTH_BRAND_NOT_APPROVED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Per-number or per-originator limit exceeded, or the organization is over a call velocity limit (CALL_VELOCITY_EXCEEDED; see the Retry-After header)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voice authentication not enabled for this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voice-auth/challenges/{id}": {
      "get": {
        "summary": "Get a voice-authentication challenge",
        "description": "Poll the challenge state/outcome. Requires the `voice_auth:read` scope. Tenant-isolated.",
        "operationId": "getVoiceAuthChallenge",
        "tags": ["Voice Authentication"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state + outcome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "challenge_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "attempts": {
                      "type": "integer"
                    },
                    "amd_result": {
                      "type": "string",
                      "nullable": true
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "decided_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "metadata": {
                      "type": "object",
                      "additionalProperties": true
                    },
                    "brand_id": {
                      "type": "string",
                      "format": "uuid",
                      "nullable": true,
                      "description": "The caller brand the call speaks (null = \"Wave\")."
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such challenge for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voice-auth/brands": {
      "get": {
        "summary": "List your caller brands",
        "description": "Every caller brand of your organization, newest first, with its review status, the reject reason, and whether it is the default of the key's project. Brands are requested and reviewed in the developer portal. Requires the `voice_auth:read` scope. A sandbox key works too.",
        "operationId": "listVoiceAuthBrands",
        "tags": ["Voice Authentication"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The `next_cursor` of the previous page."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of caller brands",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "brand_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name_en": {
                            "type": "string"
                          },
                          "name_ar": {
                            "type": "string"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "pending_tenant",
                              "pending_wave",
                              "approved",
                              "rejected",
                              "retired"
                            ]
                          },
                          "rejection_reason": {
                            "type": "string",
                            "nullable": true
                          },
                          "is_default": {
                            "type": "boolean"
                          },
                          "created_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "decided_at": {
                            "type": "string",
                            "format": "date-time",
                            "nullable": true
                          }
                        }
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Sandbox key, or an invalid cursor",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing the voice_auth:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voice authentication not enabled for this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify": {
      "post": {
        "summary": "Create a verification",
        "description": "Sends a verification code to a phone number over WhatsApp. Requires the `verify:write` scope and a production key. Fails closed — only a correct, in-time, in-attempt-budget code verifies.",
        "operationId": "createVerification",
        "tags": ["Verify"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Repeat-safe key; a retry returns the same verification without a second code minted or second message sent."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "phone_number": {
                    "type": "string",
                    "description": "E.164 (+9665…) — the number Wave sends the code to."
                  },
                  "channel": {
                    "type": "string",
                    "enum": ["whatsapp"],
                    "default": "whatsapp"
                  },
                  "locale": {
                    "type": "string",
                    "enum": ["ar", "en"],
                    "default": "ar"
                  },
                  "ttl_seconds": {
                    "type": "integer",
                    "minimum": 60,
                    "maximum": 900,
                    "default": 300
                  },
                  "metadata": {
                    "type": "object",
                    "additionalProperties": true
                  }
                },
                "required": ["phone_number"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Verification created; code sent",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string",
                      "example": "initiated"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Sandbox key, missing scope, or blocklisted number",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Per-number or per-originator limit exceeded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Verify not enabled for this account",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify/check": {
      "post": {
        "summary": "Check a verification code",
        "description": "Validates a code submitted by the user. Requires the `verify:write` scope. Returns `verified: true` only on an exact, in-time, in-attempt-budget match; wrong codes increment the attempt counter.",
        "operationId": "checkVerification",
        "tags": ["Verify"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "verification_id": {
                    "type": "string",
                    "description": "From the create response."
                  },
                  "code": {
                    "type": "string",
                    "description": "The 6-digit code the user entered."
                  }
                },
                "required": ["verification_id", "code"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Code checked; verdict returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "verified": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or expired verification",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such verification for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/verify/{id}": {
      "get": {
        "summary": "Get a verification status",
        "description": "Poll the verification state/outcome. Requires the `verify:read` scope. Tenant-isolated.",
        "operationId": "getVerification",
        "tags": ["Verify"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state + outcome",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "verification_id": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "attempts": {
                      "type": "integer"
                    },
                    "channel": {
                      "type": "string"
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "decided_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    },
                    "metadata": {
                      "type": "object",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such verification for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voicemails": {
      "get": {
        "summary": "List voicemails",
        "description": "Returns the project's voicemail box, newest first, with cursor pagination. Requires the `voicemail:read` scope. Filter by `number` (a per-number box view) and `listened` (new vs heard).",
        "operationId": "listVoicemails",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "default": 20,
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "number",
            "in": "query",
            "required": false,
            "description": "Filter to one Wave number's box — E.164 (+9665…).",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "listened",
            "in": "query",
            "required": false,
            "description": "`true` → only heard messages; `false` → only new.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of voicemails",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VoicemailList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voicemails/numbers": {
      "get": {
        "summary": "List the project's numbers with their voicemail switch",
        "description": "Returns the project's numbers, oldest assigned first, each with its voicemail switch state and greeting. Use the `id` with PUT /v1/numbers/{id}/voicemail. Requires the `voicemail:read` scope. A sandbox key gets an empty list.",
        "operationId": "listVoicemailNumbers",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The project's numbers",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["data"],
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "number": {
                            "type": "string",
                            "example": "+966590007001"
                          },
                          "voicemail_enabled": {
                            "type": "boolean"
                          },
                          "greeting_ref": {
                            "type": "string",
                            "nullable": true
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Missing the voicemail:read scope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voicemails/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid"
          }
        }
      ],
      "get": {
        "summary": "Get a voicemail",
        "description": "One voicemail message. Requires the `voicemail:read` scope. Tenant-isolated; soft-deleted messages are excluded.",
        "operationId": "getVoicemail",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The voicemail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Voicemail"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such voicemail for your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Delete a voicemail",
        "description": "Soft-deletes the message and clears its recording pointer (the storage lifecycle reaps the object). Requires the `voicemail:write` scope. Idempotent — a second delete returns 404.",
        "operationId": "deleteVoicemail",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "deleted": {
                      "type": "boolean",
                      "example": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such voicemail for your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voicemails/{id}/recording-url": {
      "get": {
        "summary": "Get a voicemail playback URL",
        "description": "Returns a short-lived presigned URL for the voicemail audio (valid ~60 minutes). Requires the `voicemail:read` scope and a production key. The audio is available for 90 days after the voicemail; after that this route returns 410 `RECORDING_EXPIRED`.",
        "operationId": "getVoicemailRecordingUrl",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A time-limited playback URL",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "voicemail_id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "url": {
                      "type": "string",
                      "format": "uri"
                    },
                    "expires_in_seconds": {
                      "type": "integer",
                      "example": 3600
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Sandbox key not allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No recording available for this voicemail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "410": {
            "description": "The recording is older than 90 days and is no longer available (RECORDING_EXPIRED)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled, or recording storage unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/voicemails/{id}/listened": {
      "post": {
        "summary": "Mark a voicemail listened",
        "description": "Stamps `listened_at` the first time only (stable across repeats). Requires the `voicemail:write` scope. Idempotent.",
        "operationId": "markVoicemailListened",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Marked listened",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "listened_at": {
                      "type": "string",
                      "format": "date-time",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such voicemail for your project",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/numbers/{id}/voicemail": {
      "put": {
        "summary": "Arm voicemail on a number",
        "description": "Turns voicemail on/off for a Wave number and optionally sets a custom greeting. `greeting_ref` must be a prompt your org uploaded via POST /v1/callflows/audio; `null` clears it (→ the default greeting); omit it to leave it unchanged. Requires the `voicemail:write` scope.",
        "operationId": "armNumberVoicemail",
        "tags": ["Voicemail"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "The phone-number id."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["voicemail_enabled"],
                "properties": {
                  "voicemail_enabled": {
                    "type": "boolean"
                  },
                  "greeting_ref": {
                    "type": "string",
                    "nullable": true,
                    "description": "A Wave-hosted greeting URL from POST /v1/callflows/audio; null clears to the default."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "number": {
                      "type": "string",
                      "example": "+966590007001"
                    },
                    "voicemail_enabled": {
                      "type": "boolean"
                    },
                    "greeting_ref": {
                      "type": "string",
                      "nullable": true
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error or invalid greeting_ref",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such number for your organization",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Voicemail not enabled for this environment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/queues/agents/login": {
      "post": {
        "summary": "Sign an agent into a queue",
        "description": "Requires the `queues:write` scope and a production key. Sandbox keys cannot manage queues.",
        "operationId": "queueAgentLogin",
        "tags": ["Queues"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  },
                  "queue": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": ["agent", "queue"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent logged in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueAgent"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key and queues:write scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Queue control failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Queue service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/queues/agents/logout": {
      "post": {
        "summary": "Sign an agent out of all queues",
        "operationId": "queueAgentLogout",
        "tags": ["Queues"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agent": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 64,
                    "pattern": "^[A-Za-z0-9_-]+$"
                  }
                },
                "required": ["agent"],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Agent logged out",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueAgent"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/queues/members": {
      "get": {
        "summary": "List live queue members",
        "operationId": "listQueueMembers",
        "tags": ["Queues"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "queue",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A live snapshot of the queue",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QueueMembers"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Queue service unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/health": {
      "get": {
        "summary": "Health check",
        "operationId": "health",
        "tags": ["System"],
        "security": [],
        "responses": {
          "200": {
            "description": "Service is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "service": {
                      "type": "string",
                      "example": "wave-api"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/callflows": {
      "post": {
        "summary": "Create an IVR menu",
        "description": "Requires the `callflows:write` scope. Sandbox keys may author + test; a real inbound call needs a production key + a bound number.",
        "operationId": "createCallflow",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["name", "definition"],
                "properties": {
                  "name": {
                    "type": "string",
                    "maxLength": 100,
                    "pattern": "^[A-Za-z0-9 _-]+$"
                  },
                  "definition": {
                    "$ref": "#/components/schemas/CallflowDefinition"
                  },
                  "activate": {
                    "type": "boolean",
                    "default": false
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Menu created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Callflow"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "List IVR menus",
        "description": "Requires the `callflows:read` scope. One row per menu (its active or latest version).",
        "operationId": "listCallflows",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "The org's menus",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CallflowList"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callflows/{name}": {
      "parameters": [
        {
          "name": "name",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "The menu name (unique per org)."
        }
      ],
      "get": {
        "summary": "Get an IVR menu",
        "description": "The active (or latest) version plus full version history. Pass `?version=N` to read that version instead (a saved draft or an old version). Requires `callflows:read`.",
        "operationId": "getCallflow",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "version",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1
            },
            "description": "Read this version. Omit it for the active version (else the latest)."
          }
        ],
        "responses": {
          "200": {
            "description": "The menu",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Callflow"
                }
              }
            }
          },
          "400": {
            "description": "version is not a positive integer",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found (no such flow, or no such version)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Edit a menu (append a version)",
        "description": "Menus are immutable/append-only — this adds the next version. Send `base_version` (the version you edited) to avoid lost updates: if another version was saved after it, the call returns 409 `CALLFLOW_VERSION_CONFLICT` and writes nothing. Without `base_version` the call always appends. Requires `callflows:write`.",
        "operationId": "updateCallflow",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["definition"],
                "properties": {
                  "definition": {
                    "$ref": "#/components/schemas/CallflowDefinition"
                  },
                  "activate": {
                    "type": "boolean",
                    "default": false
                  },
                  "base_version": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Optional. The version this edit started from; 409 if a later version exists."
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "New version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Callflow"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "CALLFLOW_VERSION_CONFLICT — a version was saved after base_version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Retire a menu",
        "description": "Soft-retire: stops serving + unbinds numbers, keeps history. Requires `callflows:write`.",
        "operationId": "retireCallflow",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Retired",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "retired": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callflows/{name}/activate": {
      "parameters": [
        {
          "name": "name",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "The menu name (unique per org)."
        }
      ],
      "post": {
        "summary": "Activate a version (rollback)",
        "description": "Makes version N live — rollback is activating an older version. Requires `callflows:write`.",
        "operationId": "activateCallflowVersion",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["version"],
                "properties": {
                  "version": {
                    "type": "integer",
                    "minimum": 1
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Now-active version",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Callflow"
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callflows/{name}/bind-number": {
      "parameters": [
        {
          "name": "name",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          },
          "description": "The menu name (unique per org)."
        }
      ],
      "post": {
        "summary": "Bind a number to a menu",
        "description": "Point a Wave number at the menu's active version. Requires `callflows:write`.",
        "operationId": "bindCallflowNumber",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["phone_number_id"],
                "properties": {
                  "phone_number_id": {
                    "type": "string",
                    "format": "uuid"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Bound",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "bound": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/callflows/audio": {
      "post": {
        "summary": "Upload a prompt audio file",
        "description": "Base64 WAV → a Wave-hosted `audio_ref` for a `play`. Requires `callflows:write`. Returns 503 until enabled for your account.",
        "operationId": "uploadCallflowAudio",
        "tags": ["Callflows"],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["base64", "content_type"],
                "properties": {
                  "base64": {
                    "type": "string"
                  },
                  "content_type": {
                    "type": "string",
                    "enum": ["audio/wav", "audio/x-wav", "audio/wave"]
                  },
                  "file_name": {
                    "type": "string",
                    "maxLength": 255
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "audio_ref": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Validation error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing or invalid API key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Production key / callflows scope required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Prompt-audio upload not enabled yet",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "sk_sandbox_* | sk_live_*",
        "description": "Your API key from the Wave dashboard. Sandbox keys start `sk_sandbox_`; production keys start `sk_live_`. Send as `Authorization: Bearer <key>`. Some endpoints require a production key and specific scopes."
      }
    },
    "schemas": {
      "CallbackRequest": {
        "type": "object",
        "properties": {
          "to": {
            "type": "string",
            "pattern": "^(\\+966|0)(1[1-9]\\d{7}|5\\d{8}|800\\d{7}|9200\\d{6})$"
          },
          "from_queue": {
            "type": "string"
          },
          "caller_id_name": {
            "type": "string",
            "maxLength": 64
          },
          "caller_id_number": {
            "type": "string"
          },
          "webhook_url": {
            "type": "string",
            "format": "uri",
            "pattern": "^https\\:\\/\\/"
          },
          "metadata": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          }
        },
        "required": ["to"],
        "additionalProperties": false
      },
      "CallbackAccepted": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "example": "call_abc123"
          },
          "status": {
            "type": "string",
            "enum": ["initiated"],
            "example": "initiated"
          },
          "sandbox": {
            "type": "boolean",
            "example": true
          },
          "provider_call_id": {
            "type": "string",
            "nullable": true,
            "description": "The telephony backend's own call id, named vendor-neutrally. Present on the sandbox response."
          },
          "vitalpbx_channel_id": {
            "type": "string",
            "nullable": true,
            "deprecated": true,
            "description": "Deprecated — use `provider_call_id` (same value). Kept on the sandbox response for backward compatibility; retired with the upcoming column rename."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CallListItem": {
        "type": "object",
        "description": "One call in the log. Customer numbers are masked (`to_masked`; for an inbound call `from` is the masked caller).",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "type": {
            "type": "string",
            "enum": ["callback", "web_calling", "inbound"]
          },
          "status": {
            "type": "string",
            "enum": [
              "initiated",
              "ringing",
              "answered",
              "ended",
              "missed",
              "failed",
              "cancelled",
              "timeout"
            ]
          },
          "from": {
            "type": "string"
          },
          "to_masked": {
            "type": "string",
            "example": "+966 50 XXX 0000"
          },
          "duration_seconds": {
            "type": "integer",
            "nullable": true
          },
          "sandbox_variant": {
            "type": "string",
            "nullable": true
          },
          "environment": {
            "type": "string",
            "enum": ["sandbox", "production"],
            "description": "The environment of the key that placed the call. Inbound calls are `production`."
          },
          "queue_id": {
            "type": "string",
            "nullable": true,
            "description": "The queue the call came from; `null` when it had none."
          },
          "disposition": {
            "type": "string",
            "nullable": true,
            "description": "Reserved. Always `null` for now."
          },
          "campaign_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The campaign that placed the call; `null` when not a campaign call."
          },
          "machine_detection_result": {
            "type": "string",
            "nullable": true,
            "enum": ["human", "machine", "notsure"],
            "description": "The machine-detection verdict; `null` when detection did not run."
          },
          "price_sar": {
            "type": "string",
            "nullable": true,
            "example": "0.37",
            "description": "The SAR price of a call charged before credits (VAT included), 2 decimals. `null` for a call charged in credits (see `credits`) and for a call with no charge."
          },
          "call_class": {
            "type": "string",
            "nullable": true,
            "example": "OUT_KSA",
            "description": "The call class that Wave set when the call was made, for example `OUT_KSA` (one outbound leg), `CLICK_TO_CALL_2LEG` (two legs) or `IN_011_APP` (incoming, answered in Wave). It sets the credits per minute. `null` when not known."
          },
          "credits": {
            "type": "number",
            "nullable": true,
            "example": 10,
            "description": "The credits Wave charged for the call, exact (up to 4 decimals). Each answered production call is charged at its call class's credits per started minute, at least one minute, and never for longer than your maximum call length. `null` when the call has no charge: a sandbox call, a beta call or an unanswered call."
          },
          "beta_feature": {
            "type": "string",
            "nullable": true,
            "description": "The beta feature of a beta call (never charged); `null` otherwise."
          },
          "recording_available": {
            "type": "boolean",
            "description": "`true` when the call has a recording and the call ended 90 days ago or less. Get the link with `GET /v1/calls/{call_id}/recording`."
          },
          "recording_available_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The end of the 90-day period in which you can get the recording. In the past when the period has ended. `null` when the call has no recording."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "answered_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "ended_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CallList": {
        "type": "object",
        "description": "Cursor mode.",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CallListItem"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "CallListPage": {
        "type": "object",
        "description": "Page mode.",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CallListItem"
            }
          },
          "total_count": {
            "type": "integer",
            "description": "Every call that matches the filters, over all pages."
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          }
        }
      },
      "CallControlAccepted": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "description": "The in-call action the engine accepted, e.g. `hangup`."
          },
          "leg": {
            "type": "string",
            "enum": ["customer", "agent"],
            "description": "The leg the action was sent to."
          },
          "status": {
            "type": "string",
            "description": "The call's status when the action was sent (`initiated`, `ringing` or `answered`)."
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": ["call_id", "action", "leg", "status", "request_id"]
      },
      "CallTransferAccepted": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "transfer_id": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "enum": ["transfer"]
          },
          "status": {
            "type": "string",
            "enum": ["requested"]
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": ["call_id", "transfer_id", "action", "status", "request_id"]
      },
      "CallTransferList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "transfer_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "target": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": ["number", "user", "queue"]
                    },
                    "value": {
                      "type": "string"
                    }
                  },
                  "required": ["type", "value"]
                },
                "status": {
                  "type": "string",
                  "enum": [
                    "requested",
                    "dialing",
                    "answered",
                    "no_answer",
                    "busy",
                    "failed",
                    "cancelled",
                    "enqueued",
                    "expired"
                  ]
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "completed_at": {
                  "type": ["string", "null"],
                  "format": "date-time"
                }
              },
              "required": [
                "transfer_id",
                "target",
                "status",
                "created_at",
                "completed_at"
              ]
            }
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": ["data", "total_count"]
      },
      "ConferenceJoined": {
        "type": "object",
        "properties": {
          "conference": {
            "type": "object",
            "properties": {
              "conference_id": {
                "type": "string",
                "format": "uuid"
              },
              "room": {
                "type": "string",
                "description": "Your label for the room."
              },
              "status": {
                "type": "string",
                "enum": ["active", "ended"]
              },
              "member_count": {
                "type": "integer",
                "description": "The calls in the room now."
              }
            },
            "required": ["conference_id", "room", "status", "member_count"]
          },
          "member": {
            "type": "object",
            "properties": {
              "call_id": {
                "type": "string",
                "format": "uuid"
              },
              "leg": {
                "type": "string",
                "enum": ["customer", "agent"]
              }
            },
            "required": ["call_id", "leg"]
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": ["conference", "member", "request_id"]
      },
      "Conference": {
        "type": "object",
        "properties": {
          "conference_id": {
            "type": "string",
            "format": "uuid"
          },
          "room": {
            "type": "string",
            "description": "Your label for the room."
          },
          "status": {
            "type": "string",
            "enum": ["active", "ended"]
          },
          "ended_reason": {
            "type": ["string", "null"],
            "enum": ["stopped", "empty", "destroyed", null],
            "description": "`stopped` (you ended it), `empty` (the last member left), `destroyed` (the voice engine ended it)."
          },
          "member_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "ended_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "call_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "leg": {
                  "type": "string",
                  "enum": ["customer", "agent"]
                },
                "joined_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "left_at": {
                  "type": ["string", "null"],
                  "format": "date-time"
                },
                "left_reason": {
                  "type": ["string", "null"],
                  "enum": ["engine_event", "call_ended", "room_ended", null]
                }
              },
              "required": [
                "call_id",
                "leg",
                "joined_at",
                "left_at",
                "left_reason"
              ]
            }
          }
        },
        "required": [
          "conference_id",
          "room",
          "status",
          "ended_reason",
          "member_count",
          "created_at",
          "ended_at",
          "members"
        ]
      },
      "ConferenceEnded": {
        "type": "object",
        "properties": {
          "conference_id": {
            "type": "string",
            "format": "uuid"
          },
          "room": {
            "type": "string",
            "description": "Your label for the room."
          },
          "status": {
            "type": "string",
            "enum": ["ended"]
          },
          "ended_reason": {
            "type": "string",
            "enum": ["stopped"]
          },
          "request_id": {
            "type": "string"
          }
        },
        "required": [
          "conference_id",
          "room",
          "status",
          "ended_reason",
          "request_id"
        ]
      },
      "Campaign": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["scheduled", "running", "paused", "stopped", "completed"]
          },
          "callflow_name": {
            "type": "string"
          },
          "caller_id": {
            "type": "string"
          },
          "start_at": {
            "type": "string",
            "format": "date-time"
          },
          "calling_window": {
            "type": "object",
            "nullable": true,
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              }
            }
          },
          "max_attempts": {
            "type": "integer"
          },
          "retry_after_minutes": {
            "type": "integer"
          },
          "max_concurrent": {
            "type": "integer"
          },
          "voicemail_message": {
            "type": "object",
            "nullable": true,
            "properties": {
              "type": {
                "type": "string",
                "enum": ["play", "say"]
              },
              "url": {
                "type": "string"
              },
              "text": {
                "type": "string"
              },
              "language": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "sandbox": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "CampaignCreated": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["scheduled", "running", "paused", "stopped", "completed"]
          },
          "callflow_name": {
            "type": "string"
          },
          "caller_id": {
            "type": "string"
          },
          "start_at": {
            "type": "string",
            "format": "date-time"
          },
          "calling_window": {
            "type": "object",
            "nullable": true,
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              }
            }
          },
          "max_attempts": {
            "type": "integer"
          },
          "retry_after_minutes": {
            "type": "integer"
          },
          "max_concurrent": {
            "type": "integer"
          },
          "voicemail_message": {
            "type": "object",
            "nullable": true,
            "properties": {
              "type": {
                "type": "string",
                "enum": ["play", "say"]
              },
              "url": {
                "type": "string"
              },
              "text": {
                "type": "string"
              },
              "language": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "sandbox": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "recipients_accepted": {
            "type": "integer"
          },
          "duplicates_removed": {
            "type": "integer"
          }
        }
      },
      "CampaignDetail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["scheduled", "running", "paused", "stopped", "completed"]
          },
          "callflow_name": {
            "type": "string"
          },
          "caller_id": {
            "type": "string"
          },
          "start_at": {
            "type": "string",
            "format": "date-time"
          },
          "calling_window": {
            "type": "object",
            "nullable": true,
            "properties": {
              "start": {
                "type": "string"
              },
              "end": {
                "type": "string"
              }
            }
          },
          "max_attempts": {
            "type": "integer"
          },
          "retry_after_minutes": {
            "type": "integer"
          },
          "max_concurrent": {
            "type": "integer"
          },
          "voicemail_message": {
            "type": "object",
            "nullable": true,
            "properties": {
              "type": {
                "type": "string",
                "enum": ["play", "say"]
              },
              "url": {
                "type": "string"
              },
              "text": {
                "type": "string"
              },
              "language": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "sandbox": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "started_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "completed_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "counts": {
            "type": "object",
            "properties": {
              "total": {
                "type": "integer"
              },
              "by_state": {
                "type": "object",
                "properties": {
                  "pending": {
                    "type": "integer"
                  },
                  "waiting": {
                    "type": "integer"
                  },
                  "dialling": {
                    "type": "integer"
                  },
                  "done": {
                    "type": "integer"
                  }
                }
              },
              "by_outcome": {
                "type": "object",
                "properties": {
                  "answered": {
                    "type": "integer"
                  },
                  "voicemail": {
                    "type": "integer"
                  },
                  "no_answer": {
                    "type": "integer"
                  },
                  "busy": {
                    "type": "integer"
                  },
                  "failed": {
                    "type": "integer"
                  },
                  "skipped": {
                    "type": "integer"
                  },
                  "cancelled": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          "credits": {
            "type": "number",
            "description": "The credits charged on the campaign's calls (exact, up to 4 decimals); 0 for a sandbox campaign and for calls not charged (campaign calls are in public beta, so they are not charged while Campaigns is in beta)."
          }
        }
      },
      "CampaignPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Campaign"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "CampaignRecipient": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "phone": {
            "type": "string"
          },
          "reference": {
            "type": "string",
            "nullable": true
          },
          "state": {
            "type": "string",
            "enum": ["pending", "waiting", "dialling", "done"]
          },
          "outcome": {
            "type": "string",
            "nullable": true,
            "enum": [
              "answered",
              "voicemail",
              "no_answer",
              "busy",
              "failed",
              "skipped",
              "cancelled"
            ]
          },
          "attempts": {
            "type": "integer"
          },
          "next_attempt_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "last_call_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "machine_detection_result": {
            "type": "string",
            "nullable": true,
            "enum": ["human", "machine", "notsure"]
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CampaignRecipientPage": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CampaignRecipient"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "WebrtcSession": {
        "type": "object",
        "properties": {
          "wcs": {
            "type": "string",
            "description": "The session token. Refresh it with `POST /v1/webrtc/config/refresh` before it expires."
          },
          "session_id": {
            "type": "string",
            "format": "uuid"
          },
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "expires_in_seconds": {
            "type": "integer"
          },
          "wss_url": {
            "type": "string",
            "description": "The SIP-over-WebSocket URL."
          },
          "sip_user": {
            "type": "string",
            "description": "The SIP user to register as (the identity, for an agent session)."
          },
          "sip_password": {
            "type": "string",
            "description": "The SIP password for this session. Returned once; never stored in plain text."
          },
          "sip_domain": {
            "type": "string"
          },
          "ice_servers": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "session_type": {
            "type": "string",
            "enum": ["agent", "caller"],
            "description": "`agent` — registered as a web-calling identity, can receive calls. `caller` — can only call out."
          },
          "identity": {
            "type": "string",
            "description": "The identity of an agent session. Absent for a caller session."
          }
        },
        "required": [
          "wcs",
          "session_id",
          "call_id",
          "expires_at",
          "expires_in_seconds",
          "wss_url",
          "sip_user",
          "sip_password",
          "sip_domain",
          "ice_servers",
          "session_type"
        ]
      },
      "UsageResponse": {
        "type": "object",
        "required": ["data", "period"],
        "properties": {
          "data": {
            "type": "object",
            "required": [
              "total_calls",
              "calls_answered",
              "calls_missed",
              "total_minutes",
              "credits"
            ],
            "properties": {
              "total_calls": {
                "type": "integer",
                "description": "Every call that matches the filters.",
                "example": 120
              },
              "calls_answered": {
                "type": "integer",
                "description": "Calls that connected (have an answer time).",
                "example": 84
              },
              "calls_missed": {
                "type": "integer",
                "description": "Calls nobody picked up.",
                "example": 21
              },
              "total_minutes": {
                "type": "number",
                "description": "Call minutes (seconds ÷ 60), two decimals.",
                "example": 312.5
              },
              "credits": {
                "type": "number",
                "description": "The credits charged on the calls (exact, up to 4 decimals). Counts the production calls that Wave charged; `0` when none was charged (sandbox, beta and unanswered calls are not charged).",
                "example": 412.5
              }
            }
          },
          "period": {
            "type": "object",
            "description": "The period the numbers cover. `null` means no bound.",
            "properties": {
              "from": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              },
              "to": {
                "type": "string",
                "format": "date-time",
                "nullable": true
              }
            }
          },
          "groups": {
            "type": "array",
            "description": "Only present when `group_by` was sent.",
            "items": {
              "type": "object",
              "required": [
                "key",
                "total_calls",
                "calls_answered",
                "calls_missed",
                "total_minutes",
                "credits"
              ],
              "properties": {
                "key": {
                  "type": "string",
                  "description": "For `day` and `hour`: the start of the Riyadh day or hour, with a `+03:00` offset. For `status`: the raw call status. For `queue`: the queue id. For `api_key`: the key id.",
                  "example": "2026-09-01T00:00:00+03:00"
                },
                "total_calls": {
                  "type": "integer",
                  "description": "Every call that matches the filters.",
                  "example": 120
                },
                "calls_answered": {
                  "type": "integer",
                  "description": "Calls that connected (have an answer time).",
                  "example": 84
                },
                "calls_missed": {
                  "type": "integer",
                  "description": "Calls nobody picked up.",
                  "example": 21
                },
                "total_minutes": {
                  "type": "number",
                  "description": "Call minutes (seconds ÷ 60), two decimals.",
                  "example": 312.5
                },
                "credits": {
                  "type": "number",
                  "description": "The credits charged on the calls (exact, up to 4 decimals). Counts the production calls that Wave charged; `0` when none was charged (sandbox, beta and unanswered calls are not charged).",
                  "example": 412.5
                }
              }
            }
          }
        }
      },
      "AuditLogEntry": {
        "type": "object",
        "required": [
          "id",
          "action",
          "resource",
          "resource_id",
          "project_id",
          "user_id",
          "actor",
          "details",
          "ip_address",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "action": {
            "type": "string",
            "description": "What changed.",
            "example": "api_key.scopes_set"
          },
          "resource": {
            "type": "string",
            "description": "The kind of resource that changed.",
            "example": "api_key"
          },
          "resource_id": {
            "type": "string",
            "nullable": true,
            "description": "The id of the resource that changed."
          },
          "project_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The project of the change. `null` for an organization-level entry."
          },
          "user_id": {
            "type": "string",
            "format": "uuid",
            "nullable": true,
            "description": "The member who made the change. `null` for `system` and `wave_operator`."
          },
          "actor": {
            "type": "string",
            "enum": ["user", "system", "wave_operator"],
            "description": "`user` (a member), `system` (Wave) or `wave_operator` (a Wave operator, identity not shown)."
          },
          "details": {
            "type": "object",
            "nullable": true,
            "additionalProperties": true,
            "description": "More data about the change. The shape depends on `action`."
          },
          "ip_address": {
            "type": "string",
            "nullable": true,
            "description": "The IP address the change came from, if known. Always `null` for `wave_operator`."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AuditLogPage": {
        "type": "object",
        "required": ["data", "next_cursor", "limit"],
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AuditLogEntry"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true,
            "description": "Pass as `cursor` for the next page. `null` on the last page."
          },
          "limit": {
            "type": "integer",
            "example": 20
          }
        }
      },
      "Callback": {
        "type": "object",
        "properties": {
          "callback_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": [
              "initiated",
              "ringing",
              "answered",
              "ended",
              "missed",
              "failed",
              "cancelled",
              "timeout"
            ]
          },
          "customer_number_masked": {
            "type": "string",
            "description": "The customer number, masked."
          },
          "queue_id": {
            "type": ["string", "null"]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "answered_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "ended_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "duration_seconds": {
            "type": ["integer", "null"]
          },
          "disposition": {
            "type": ["string", "null"],
            "description": "Not filled yet (always `null`); use `status`."
          }
        }
      },
      "CallbackList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Callback"
            }
          },
          "total_count": {
            "type": "integer",
            "description": "Every callback that matches the filters, over all pages."
          },
          "page": {
            "type": "integer"
          },
          "page_size": {
            "type": "integer"
          }
        }
      },
      "CallbackCancelled": {
        "type": "object",
        "properties": {
          "callback_id": {
            "type": "string",
            "format": "uuid"
          },
          "status": {
            "type": "string",
            "enum": ["cancelled"]
          }
        }
      },
      "CallRecordingLink": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "A signed download link. Do not share it."
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessageAccepted": {
        "type": "object",
        "properties": {
          "message_id": {
            "type": "string",
            "format": "uuid"
          },
          "provider_message_id": {
            "type": ["string", "null"]
          },
          "status": {
            "type": "string",
            "enum": ["queued", "sent"]
          },
          "channel": {
            "type": "string",
            "enum": ["whatsapp", "sms", "webchat", "email"]
          },
          "sandbox": {
            "type": "boolean"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "channel": {
            "type": "string",
            "enum": ["whatsapp", "sms", "webchat", "email"]
          },
          "direction": {
            "type": "string",
            "enum": ["inbound", "outbound"]
          },
          "conversation_id": {
            "type": ["string", "null"]
          },
          "from": {
            "type": ["string", "null"]
          },
          "to": {
            "type": ["string", "null"]
          },
          "content": {
            "type": "object",
            "description": "The message content as sent or received."
          },
          "provider_message_id": {
            "type": ["string", "null"]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "sent",
              "delivered",
              "read",
              "failed",
              "received"
            ]
          },
          "error_reason": {
            "type": ["string", "null"]
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "occurred_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessageList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "next_cursor": {
            "type": ["string", "null"]
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "UploadedMedia": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "contentType": {
            "type": "string"
          },
          "sizeBytes": {
            "type": "integer"
          }
        }
      },
      "MessageTemplate": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["approved", "pending", "rejected"]
          },
          "category": {
            "type": "string"
          },
          "providerId": {
            "type": "string"
          }
        }
      },
      "MessageTemplateList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MessageTemplate"
            }
          }
        }
      },
      "MessageTemplateDetail": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "language": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["approved", "pending", "rejected"]
          },
          "category": {
            "type": "string"
          },
          "providerId": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "header": {
            "type": "string"
          },
          "footer": {
            "type": "string"
          },
          "buttons": {
            "type": "array",
            "items": {
              "type": "object"
            }
          },
          "otpButton": {
            "type": "boolean"
          }
        }
      },
      "Deleted": {
        "type": "object",
        "properties": {
          "deleted": {
            "type": "boolean",
            "enum": [true]
          }
        }
      },
      "Broadcast": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "contact_group_id": {
            "type": ["string", "null"],
            "format": "uuid"
          },
          "contact_ids": {
            "type": ["array", "null"],
            "items": {
              "type": "string",
              "format": "uuid"
            }
          },
          "template_name": {
            "type": "string"
          },
          "template_language": {
            "type": "string"
          },
          "template_variables": {
            "type": ["object", "array", "null"]
          },
          "scheduled_at": {
            "type": ["string", "null"],
            "format": "date-time"
          },
          "status": {
            "type": "string",
            "enum": ["pending", "processing", "sent", "failed", "cancelled"]
          },
          "result_summary": {
            "type": ["object", "null"],
            "description": "Send counts, once the broadcast has run."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "BroadcastList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Broadcast"
            }
          }
        }
      },
      "BroadcastCancelled": {
        "type": "object",
        "properties": {
          "cancelled": {
            "type": "boolean",
            "enum": [true]
          }
        }
      },
      "ContactGroupSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "member_count": {
            "type": "integer"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ContactGroupList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ContactGroupSummary"
            }
          }
        }
      },
      "ContactGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "contact_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "name": {
                  "type": "string"
                },
                "phone": {
                  "type": "string"
                },
                "marketing_opted_out": {
                  "type": "boolean"
                },
                "added_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "ContactGroupRenamed": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          }
        }
      },
      "ContactGroupMembersAdded": {
        "type": "object",
        "properties": {
          "added": {
            "type": "integer",
            "description": "Contacts newly added."
          },
          "submitted": {
            "type": "integer",
            "description": "Contacts in the request."
          }
        }
      },
      "ContactGroupMemberRemoved": {
        "type": "object",
        "properties": {
          "removed": {
            "type": "boolean",
            "enum": [true]
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "marketing_opted_out": {
            "type": "boolean"
          }
        }
      },
      "ContactList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Contact"
            }
          }
        }
      },
      "ContactOptOut": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "marketing_opted_out": {
            "type": "boolean"
          }
        }
      },
      "Consent": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "phone": {
            "type": "string",
            "description": "The number in E.164.",
            "example": "+966501234567"
          },
          "status": {
            "type": "string",
            "enum": ["opted_out", "opted_in"]
          },
          "source": {
            "type": "string",
            "enum": ["keyword", "api", "contact"],
            "description": "`keyword` = the end user's STOP / START reply; `api` = this API; `contact` = the contact opt-out toggle."
          },
          "evidence": {
            "type": "string",
            "nullable": true
          },
          "changed_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "ConsentList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Consent"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "CallAccepted": {
        "type": "object",
        "properties": {
          "call_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["initiated"],
            "example": "initiated"
          },
          "direction": {
            "type": "string",
            "example": "outbound"
          },
          "to": {
            "type": "string",
            "description": "Masked destination."
          },
          "from": {
            "type": "string"
          },
          "sandbox": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VirtualNumber": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "e164": {
            "type": "string",
            "example": "+966590007001"
          },
          "status": {
            "type": "string",
            "example": "assigned"
          },
          "external_user_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string",
            "nullable": true
          },
          "contact_id": {
            "type": "string",
            "format": "uuid"
          },
          "instructions": {
            "type": "object",
            "nullable": true,
            "properties": {
              "text": {
                "type": "string",
                "nullable": true
              },
              "audio_url": {
                "type": "string",
                "nullable": true
              },
              "language": {
                "type": "string",
                "nullable": true
              },
              "forward_to": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "assigned_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VirtualNumberEnvelope": {
        "type": "object",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/VirtualNumber"
          }
        }
      },
      "VirtualNumberList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/VirtualNumber"
            }
          },
          "meta": {
            "type": "object",
            "properties": {
              "limit": {
                "type": "integer"
              },
              "offset": {
                "type": "integer"
              }
            }
          }
        }
      },
      "QueueAgent": {
        "type": "object",
        "properties": {
          "agent": {
            "type": "string"
          },
          "queue": {
            "type": "string",
            "nullable": true
          },
          "status": {
            "type": "string",
            "example": "logged_in"
          }
        }
      },
      "Voicemail": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "call_id": {
            "type": "string",
            "format": "uuid"
          },
          "number": {
            "type": "string",
            "example": "+966590007001",
            "description": "The Wave number that received the call (the box)."
          },
          "from": {
            "type": "string",
            "example": "+966500000000",
            "description": "The caller who left the message — E.164."
          },
          "duration_seconds": {
            "type": "integer",
            "nullable": true
          },
          "recording_available": {
            "type": "boolean",
            "description": "`true` when the message has audio and it was left 90 days ago or less."
          },
          "recording_available_until": {
            "type": "string",
            "format": "date-time",
            "nullable": true,
            "description": "The end of the 90-day period in which you can get the audio. In the past when the period has ended. `null` when the message has no audio."
          },
          "transcription_status": {
            "type": "string",
            "enum": ["pending", "unavailable", "completed", "failed"]
          },
          "transcription_text": {
            "type": "string",
            "nullable": true
          },
          "listened_at": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "VoicemailList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Voicemail"
            }
          },
          "next_cursor": {
            "type": "string",
            "nullable": true
          },
          "limit": {
            "type": "integer"
          }
        }
      },
      "QueueMembers": {
        "type": "object",
        "properties": {
          "queue": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "position": {
                  "type": "integer"
                },
                "channel_uuid": {
                  "type": "string",
                  "format": "uuid"
                },
                "src_number": {
                  "type": "string"
                },
                "state": {
                  "type": "string",
                  "example": "waiting"
                },
                "wait_seconds": {
                  "type": "integer"
                },
                "agent": {
                  "type": "string",
                  "nullable": true
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Wave's standard bilingual error envelope.",
        "required": [
          "error_code",
          "message",
          "message_ar",
          "request_id",
          "docs_url"
        ],
        "properties": {
          "error_code": {
            "type": "string",
            "enum": [
              "INVALID_API_KEY",
              "EXPIRED_API_KEY",
              "REVOKED_API_KEY",
              "SANDBOX_KEY_NOT_ALLOWED",
              "INSUFFICIENT_PERMISSIONS",
              "API_KEY_REVEAL_UNAVAILABLE",
              "RATE_LIMIT_EXCEEDED",
              "RECAPTCHA_FAILED",
              "PUBLIC_DEMO_DISABLED",
              "PUBLIC_DEMO_LIMIT_REACHED",
              "SANDBOX_EXPIRED",
              "OTP_INVALID",
              "OTP_EXPIRED",
              "OTP_TOO_MANY_ATTEMPTS",
              "OTP_RESEND_TOO_SOON",
              "OTP_SEND_FAILED",
              "INVALID_PHONE_NUMBER",
              "CALLBACK_NOT_FOUND",
              "CALLBACK_ALREADY_CANCELLED",
              "CALLBACK_NOT_CANCELLABLE",
              "CALL_NOT_FOUND",
              "CALL_FAILED",
              "INSUFFICIENT_CREDITS",
              "CALL_NOT_CONTROLLABLE",
              "CALL_NOT_ACTIVE",
              "CALL_NOT_ANSWERED",
              "AGENT_LEG_NOT_CONNECTED",
              "CALL_CONTROL_FAILED",
              "CALL_CONTROL_UNSUPPORTED",
              "CALL_CONTROL_DISABLED",
              "INVALID_PLAY_URL",
              "TRANSFER_IN_PROGRESS",
              "TRANSFER_TARGET_INVALID",
              "TRANSFER_LIMIT_REACHED",
              "CALL_VELOCITY_EXCEEDED",
              "CALLING_SUSPENDED",
              "CONFERENCE_FULL",
              "CALL_ALREADY_IN_CONFERENCE",
              "CONFERENCE_NOT_FOUND",
              "CONFERENCE_ENDED",
              "CAMPAIGNS_DISABLED",
              "CAMPAIGN_NOT_FOUND",
              "CAMPAIGN_INVALID_STATE",
              "CAMPAIGN_LIMIT_REACHED",
              "CAMPAIGN_NEEDS_IVR",
              "QUEUE_CONTROL_FAILED",
              "QUEUE_SERVICE_UNAVAILABLE",
              "RECORDING_NOT_FOUND",
              "RECORDING_URL_EXPIRED",
              "RECORDING_EXPIRED",
              "RECORDING_SERVICE_UNAVAILABLE",
              "CALLFLOW_AUDIO_SERVICE_UNAVAILABLE",
              "CALLFLOW_VERSION_CONFLICT",
              "VOICE_AUTH_DISABLED",
              "VOICE_AUTH_NOT_FOUND",
              "VOICE_AUTH_ASSURANCE_UNSUPPORTED",
              "VOICE_AUTH_RATE_LIMITED",
              "VOICE_AUTH_BLOCKED",
              "VOICE_AUTH_BRAND_NOT_APPROVED",
              "VOICE_AUTH_BRAND_NOT_FOUND",
              "VOICE_AUTH_BRAND_INVALID_STATE",
              "VOICE_AUTH_BRAND_DUPLICATE",
              "VERIFY_DISABLED",
              "VERIFY_NOT_FOUND",
              "VERIFY_INVALID_CODE",
              "VERIFY_MAX_ATTEMPTS",
              "VERIFY_EXPIRED",
              "VERIFY_RATE_LIMITED",
              "VERIFY_SEND_FAILED",
              "VERIFY_BLOCKED",
              "VOICEMAIL_DISABLED",
              "VOICEMAIL_NOT_FOUND",
              "VOICEMAIL_RECORDING_NOT_FOUND",
              "VOICEMAIL_SERVICE_UNAVAILABLE",
              "VOICEMAIL_GREETING_INVALID",
              "DLQ_REPLAY_DISABLED",
              "DLQ_REPLAY_BROKER_UNAVAILABLE",
              "MESSAGES_DISABLED",
              "IVR_DISABLED",
              "QUEUES_DISABLED",
              "GRAPH_IVR_DISABLED",
              "CONNECT_NUMBER_DISABLED",
              "SANDBOX_INVALID_QUEUE",
              "SANDBOX_QUEUE_UNAVAILABLE",
              "SANDBOX_SIMULATED_SERVER_ERROR",
              "SANDBOX_DESTINATION_NOT_ALLOWED",
              "SANDBOX_MINUTES_EXCEEDED",
              "SANDBOX_CALLS_PAUSED",
              "WIDGET_ORIGIN_NOT_ALLOWED",
              "WIDGET_NOT_AVAILABLE",
              "PROJECT_NOT_FOUND",
              "WEBHOOK_URL_INVALID",
              "WEBHOOK_UNREACHABLE",
              "WEBHOOK_LIMIT_EXCEEDED",
              "WEBHOOK_URL_DUPLICATE",
              "WEBHOOK_NOT_FOUND",
              "WEBHOOK_VERIFICATION_FAILED",
              "SIGNUP_EMAIL_TAKEN",
              "SIGNUP_VALIDATION_FAILED",
              "VITALPBX_PROVISIONING_FAILED",
              "SIGNUP_FAILED",
              "API_KEY_NOT_FOUND",
              "API_KEY_REVEAL_FORBIDDEN",
              "PRODUCTION_ACCESS_ALREADY_REQUESTED",
              "PRODUCTION_TIER_REQUIRED",
              "PRODUCTION_REQUEST_EXISTS",
              "PRODUCTION_REQUEST_NOT_FOUND",
              "PRODUCTION_REQUEST_INVALID_STATE",
              "VALIDATION_ERROR",
              "INTERNAL_ERROR",
              "NOT_FOUND",
              "PAYLOAD_TOO_LARGE",
              "IDEMPOTENCY_KEY_CONFLICT",
              "INVALID_CREDENTIALS",
              "SESSION_REQUIRED",
              "INVALID_ACCESS_TOKEN",
              "EXPIRED_ACCESS_TOKEN",
              "INVALID_REFRESH_TOKEN",
              "EXPIRED_REFRESH_TOKEN",
              "REFRESH_REUSE_DETECTED",
              "REFRESH_ROTATION_RACE",
              "SESSION_IDLE_TIMEOUT",
              "WEB_CALLING_DISABLED",
              "ORIGIN_NOT_ALLOWED",
              "WEBRTC_CONCURRENCY_LIMIT",
              "WCS_NOT_FOUND",
              "WCS_EXPIRED",
              "WCS_REVOKED",
              "WCS_REUSE_DETECTED",
              "WCS_NOT_ALLOWED_AS_BEARER",
              "WEBRTC_PROVISIONING_FAILED",
              "TURN_UNAVAILABLE",
              "INVALID_IDENTITY",
              "IDENTITY_CONFLICT",
              "PROFILE_VALIDATION_FAILED",
              "PASSWORD_VALIDATION_FAILED",
              "INVALID_CURRENT_PASSWORD",
              "PASSWORD_SSO_ONLY",
              "SETUP_ALREADY_COMPLETE",
              "INVALID_NATIONAL_ID",
              "NAFATH_INITIATE_FAILED",
              "NAFATH_NOT_VERIFIED",
              "NAFATH_REJECTED",
              "NAFATH_EXPIRED",
              "NAFATH_ALREADY_REGISTERED",
              "NAFATH_INVALID_WEBHOOK",
              "NAFATH_ALREADY_VERIFIED",
              "NAFATH_REQUIRED",
              "ADMIN_UNAUTHORIZED",
              "ADMIN_INVALID_CREDENTIALS",
              "ADMIN_ROLE_FORBIDDEN",
              "ORG_TELEPHONY_NOT_CONFIGURED",
              "WALLET_ALREADY_ZERO",
              "WALLET_BALANCE_CHANGED",
              "ADMIN_ORG_OWNER_EMAIL_TAKEN",
              "ADMIN_USER_NOT_FOUND",
              "INSUFFICIENT_ROLE",
              "LAST_OWNER",
              "INVALID_SCOPE",
              "NUMBER_NOT_AVAILABLE",
              "NUMBER_NOT_FOUND",
              "NUMBER_ALREADY_ASSIGNED",
              "NUMBER_PROVIDER_ERROR",
              "PORTING_INVALID_STATE",
              "PORTING_NOT_FOUND",
              "OWN_DID_NUMBER_REQUIRED",
              "OWN_DID_NUMBER_NOT_AUTHORIZED",
              "OWN_DID_NUMBER_UNAVAILABLE",
              "NUMBER_POOL_INVALID_NUMBER",
              "NUMBER_POOL_SHARED_NUMBER",
              "NUMBER_POOL_DUPLICATE",
              "NUMBER_POOL_NUMBER_HELD",
              "NUMBER_POOL_NUMBER_FREE",
              "NUMBER_POOL_PLAN_MISMATCH",
              "NUMBER_POOL_NOT_FOUND",
              "SPEND_CAP_EXCEEDED",
              "RATE_PLAN_NOT_FOUND",
              "PAYMENT_FAILED",
              "DUPLICATE_USAGE_EVENT",
              "INVOICE_NOT_FOUND",
              "PAYMENT_NOT_FOUND",
              "PAYMENT_AMOUNT_MISMATCH",
              "RECHARGE_PLAN_NOT_FOUND",
              "CALL_CLASS_NOT_FOUND",
              "NUMBER_SUSPENDED",
              "NUMBER_PLAN_NOT_FOUND",
              "NO_OPEN_NUMBER_PAYMENT",
              "NUMBER_PLANS_OFF",
              "INSUFFICIENT_PROJECT_BALANCE",
              "INSUFFICIENT_POOL_BALANCE",
              "PROJECT_NOT_FOUND_FOR_ALLOCATION",
              "ENGINE_UNAUTHORIZED",
              "CALLFLOW_TENANT_NOT_FOUND",
              "CLI_NOT_OWNED",
              "WEBHOOK_UNAUTHORIZED",
              "CHANNEL_NOT_CONFIGURED",
              "WEBHOOK_PAYLOAD_INVALID",
              "RECIPIENT_OPTED_OUT",
              "QUIET_HOURS_ACTIVE",
              "CONSENT_LOCKED_BY_END_USER",
              "CONTACT_GROUP_NAME_TAKEN",
              "INVITE_NOT_FOUND",
              "INVITE_NOT_PENDING",
              "INVITE_EXPIRED",
              "INVITE_ROLE_INVALID",
              "INVITE_ALREADY_MEMBER",
              "INVITE_EMAIL_OTHER_ORG",
              "INVITE_ACCOUNT_DETAILS_REQUIRED"
            ]
          },
          "message": {
            "type": "string",
            "description": "English message."
          },
          "message_ar": {
            "type": "string",
            "description": "Arabic message."
          },
          "request_id": {
            "type": "string"
          },
          "docs_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "IvrAction": {
        "type": "object",
        "description": "A terminal prompt/branch action — exactly one of say, play, dial, enqueue, or hangup.",
        "oneOf": [
          {
            "type": "object",
            "required": ["say"],
            "properties": {
              "say": {
                "type": "object",
                "required": ["text"],
                "properties": {
                  "text": {
                    "type": "string",
                    "maxLength": 1000
                  },
                  "language": {
                    "type": "string"
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": ["play"],
            "properties": {
              "play": {
                "type": "object",
                "required": ["audio_ref"],
                "properties": {
                  "audio_ref": {
                    "type": "string",
                    "description": "A Wave-hosted audio URL from POST /v1/callflows/audio."
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": ["dial"],
            "properties": {
              "dial": {
                "type": "object",
                "required": ["number"],
                "properties": {
                  "number": {
                    "type": "string",
                    "description": "A KSA phone number (toll-fraud guard)."
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": ["enqueue"],
            "properties": {
              "enqueue": {
                "type": "object",
                "required": ["queue"],
                "properties": {
                  "queue": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9_-]{1,64}$"
                  },
                  "strategy": {
                    "type": "string",
                    "enum": ["ring-all", "round-robin"]
                  }
                }
              }
            }
          },
          {
            "type": "object",
            "required": ["hangup"],
            "properties": {
              "hangup": {
                "type": "boolean",
                "enum": [true]
              }
            }
          }
        ]
      },
      "IvrMenuDefinition": {
        "type": "object",
        "required": ["prompt", "branches"],
        "properties": {
          "prompt": {
            "type": "object",
            "description": "The greeting — exactly one of say or play.",
            "properties": {
              "say": {
                "type": "object",
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "language": {
                    "type": "string"
                  }
                }
              },
              "play": {
                "type": "object",
                "properties": {
                  "audio_ref": {
                    "type": "string"
                  }
                }
              }
            }
          },
          "gather": {
            "type": "object",
            "properties": {
              "num_digits": {
                "type": "integer",
                "minimum": 1,
                "maximum": 10,
                "default": 1
              },
              "timeout_seconds": {
                "type": "integer",
                "minimum": 1,
                "maximum": 60,
                "default": 8
              }
            }
          },
          "branches": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "items": {
              "type": "object",
              "required": ["digit", "action"],
              "properties": {
                "digit": {
                  "type": "string",
                  "pattern": "^[0-9*#]$"
                },
                "action": {
                  "$ref": "#/components/schemas/IvrAction"
                },
                "input": {
                  "type": "object",
                  "description": "Custom fields merged into the call.input webhook (≤20; reserved: call_id, digits, node, limit_reached).",
                  "additionalProperties": true
                }
              }
            }
          },
          "no_input": {
            "type": "object",
            "properties": {
              "action": {
                "$ref": "#/components/schemas/IvrAction"
              },
              "input": {
                "type": "object",
                "additionalProperties": true
              }
            }
          }
        }
      },
      "CallflowDefinition": {
        "description": "A single-level menu (no `kind`) or a multi-level graph (`kind: graph`).",
        "oneOf": [
          {
            "$ref": "#/components/schemas/IvrMenuDefinition"
          },
          {
            "$ref": "#/components/schemas/IvrGraphDefinition"
          }
        ]
      },
      "IvrGraphDefinition": {
        "type": "object",
        "description": "A multi-level menu: named nodes joined by `next` links, starting at `start`. Limits: ≤50 nodes; every node reachable from `start` (or `on_limit`); every loop passes through a menu node; 20 menu turns per call, then `on_limit` (which must not reach a menu) or hang up. dial targets must be KSA numbers; audio refs must be prompts your org uploaded.",
        "required": ["kind", "start", "nodes"],
        "properties": {
          "kind": {
            "type": "string",
            "enum": ["graph"]
          },
          "start": {
            "type": "string",
            "pattern": "^[a-z0-9]{1,12}$"
          },
          "on_limit": {
            "type": "string",
            "pattern": "^[a-z0-9]{1,12}$",
            "description": "Node the call goes to after 20 menu turns."
          },
          "nodes": {
            "type": "object",
            "maxProperties": 50,
            "propertyNames": {
              "pattern": "^[a-z0-9]{1,12}$"
            },
            "additionalProperties": {
              "$ref": "#/components/schemas/IvrGraphNode"
            }
          }
        }
      },
      "IvrGraphNode": {
        "type": "object",
        "description": "One graph node. Every node may carry `ui: {x, y, label?}` (builder layout and display name; stored and returned unchanged, never run).",
        "required": ["type"],
        "properties": {
          "type": {
            "type": "string",
            "enum": ["menu", "say", "play", "goto", "dial", "enqueue", "hangup"]
          },
          "next": {
            "type": "string",
            "description": "say / play / goto: the node to go to next."
          },
          "prompt": {
            "type": "object",
            "description": "menu: the prompt — exactly one of say or play."
          },
          "num_digits": {
            "type": "integer",
            "enum": [1],
            "default": 1
          },
          "timeout_seconds": {
            "type": "integer",
            "minimum": 1,
            "maximum": 60,
            "default": 8
          },
          "options": {
            "type": "array",
            "minItems": 1,
            "maxItems": 12,
            "description": "menu: one item per key; each digit unique.",
            "items": {
              "type": "object",
              "required": ["digit", "next"],
              "properties": {
                "digit": {
                  "type": "string",
                  "pattern": "^[0-9*#]$"
                },
                "next": {
                  "type": "string"
                },
                "input": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "no_input": {
            "type": "object",
            "description": "menu: where to go on no key (default: replay the menu).",
            "properties": {
              "next": {
                "type": "string"
              }
            }
          },
          "invalid": {
            "type": "object",
            "description": "menu: where to go on a key that is not an option (default: replay the menu).",
            "properties": {
              "next": {
                "type": "string"
              }
            }
          },
          "text": {
            "type": "string",
            "maxLength": 1000,
            "description": "say"
          },
          "language": {
            "type": "string",
            "description": "say"
          },
          "audio_ref": {
            "type": "string",
            "description": "play"
          },
          "target": {
            "type": "string",
            "description": "dial: a KSA number"
          },
          "queue": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{1,64}$",
            "description": "enqueue"
          },
          "strategy": {
            "type": "string",
            "enum": ["ring-all", "round-robin"]
          },
          "moh": {
            "type": "string",
            "description": "enqueue: hold music, an uploaded audio_ref"
          },
          "ui": {
            "type": "object",
            "required": ["x", "y"],
            "properties": {
              "x": {
                "type": "number"
              },
              "y": {
                "type": "number"
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 40,
                "description": "Display name in any language (trimmed, 1–40 characters, no control characters or bidi overrides). Never used on a call; the node id stays the routing key."
              }
            }
          }
        }
      },
      "Callflow": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": ["menu", "graph"]
          },
          "version": {
            "type": "integer"
          },
          "is_active": {
            "type": "boolean"
          },
          "definition": {
            "type": "object",
            "description": "The definition as written: kind=menu → IvrMenuDefinition; kind=graph → IvrGraphDefinition (with ui). Can be sent back to PUT unchanged. A flow set up outside this API reads back best-effort (each option shows its main action only)."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "versions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "version": {
                  "type": "integer"
                },
                "is_active": {
                  "type": "boolean"
                },
                "created_at": {
                  "type": "string",
                  "format": "date-time"
                }
              }
            }
          }
        }
      },
      "CallflowSummary": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": ["menu", "graph"]
          },
          "version": {
            "type": "integer"
          },
          "is_active": {
            "type": "boolean"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "CallflowList": {
        "type": "object",
        "properties": {
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/CallflowSummary"
            }
          }
        }
      }
    }
  }
}
