> ## Documentation Index > Fetch the complete documentation index at: https://docs.wave.sa/llms.txt > Use this file to discover all available pages before exploring further. # Create an IVR menu > Requires the `callflows:write` scope. Sandbox keys may author + test; a real inbound call needs a production key + a bound number. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/callflows 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/callflows: post: tags: - Callflows 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 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/IvrMenuDefinition' 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' security: - bearerAuth: [] components: schemas: 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). additionalProperties: true no_input: type: object properties: action: $ref: '#/components/schemas/IvrAction' input: type: object additionalProperties: true Callflow: type: object properties: name: type: string version: type: integer is_active: type: boolean definition: type: object description: The compiled internal menu (kind=menu). 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 Error: type: object description: Wave's standard bilingual error envelope. 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 - 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 - QUEUE_CONTROL_FAILED - QUEUE_SERVICE_UNAVAILABLE - RECORDING_NOT_FOUND - RECORDING_URL_EXPIRED - RECORDING_SERVICE_UNAVAILABLE - SANDBOX_INVALID_QUEUE - SANDBOX_QUEUE_UNAVAILABLE - SANDBOX_SIMULATED_SERVER_ERROR - SANDBOX_DESTINATION_NOT_ALLOWED - WIDGET_ORIGIN_NOT_ALLOWED - 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 - 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_ORG_OWNER_EMAIL_TAKEN - INSUFFICIENT_ROLE - LAST_OWNER - INVALID_SCOPE - NUMBER_NOT_AVAILABLE - NUMBER_NOT_FOUND - NUMBER_ALREADY_ASSIGNED - NUMBER_PROVIDER_ERROR - PORTING_INVALID_STATE - PORTING_NOT_FOUND - SPEND_CAP_EXCEEDED - RATE_PLAN_NOT_FOUND - PAYMENT_FAILED - DUPLICATE_USAGE_EVENT - INVOICE_NOT_FOUND - ENGINE_UNAUTHORIZED - CALLFLOW_TENANT_NOT_FOUND - WEBHOOK_UNAUTHORIZED - CHANNEL_NOT_CONFIGURED - WEBHOOK_PAYLOAD_INVALID - 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 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 `. Some endpoints require a production key and specific scopes. ````