openapi: 3.1.0
info:
  title: Ayana Voice and SMS Messaging API
  version: 0.1.0
  description: |
    Trigger one outbound voice call or one text message at a time, and receive a structured outcome for
    each by signed webhook, pollable event feed and bulk export.

    Every route needs `Authorization: Bearer <key>`, answers JSON in UTF-8, and returns the error envelope
    on failure. Every response carries `X-Request-Id`. Timestamps are ISO 8601 in UTC, durations are whole
    seconds, money is `{amount: "0.50", currency: "NGN"}` with a decimal string.

    Keys are `key_test_<32 characters>` (sandbox, simulated backends) or `key_live_<32 characters>`.
    Ayana never retries a call or a message on its own: the client re-calls and links attempts by
    `retry_group`.

    Order of checks for a create request: authentication, scope, source address, rate limit, body
    validity, idempotency lookup, number format, suppression, sender registration, audio checks,
    concurrency limit. The first failure wins.

    Webhooks: each delivery is an HTTP POST of the Event JSON with `X-Signature-Timestamp` (Unix seconds)
    and `X-Signature`, the lowercase hexadecimal HMAC-SHA256 of `<timestamp>.<raw body>` with the endpoint
    secret. Reject anything older than 300 seconds. For 24 hours after a secret rotation each delivery
    also carries `X-Signature-Previous`, signed with the old secret. Success is any 2xx within 10 seconds;
    otherwise retries follow after 1, 5 and 30 minutes, then 2, 6 and 12 hours (seven attempts in all).
    Delivery is at least once: use the event `id` to remove duplicates.
servers:
  - url: /
    description: This Ayana site
security:
  - bearer: []
tags:
  - name: Voice
  - name: Audio presets
  - name: Text messages
  - name: Opt-outs
  - name: Webhooks
  - name: Events
  - name: Exports
paths:
  /v1/voice/calls:
    post:
      tags: [Voice]
      summary: Place one call to one number
      description: Requires `voice:write`. Returns 201 with status `queued` at once.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/SandboxScenarioVoice'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CallCreate' }
            example:
              to: '+2348031234567'
              audio: { type: text_to_speech, text: 'Your child is due for a vaccine on Friday.', language: ha, voice: female, label: ha-dose2-v1 }
              ivr: { capture: { valid_keys: ['1', '2'], timeout_seconds: 5, max_repeats: 1 } }
              reference: child-42
              retry_group: child-42-dose-2
      responses:
        '201': { description: Created, headers: { Idempotent-Replay: { $ref: '#/components/headers/IdempotentReplay' } }, content: { application/json: { schema: { $ref: '#/components/schemas/Call' } } } }
        default: { $ref: '#/components/responses/Error' }
    get:
      tags: [Voice]
      summary: List calls, newest first
      description: Requires `voice:read`.
      parameters:
        - { name: reference, in: query, schema: { type: string } }
        - { name: retry_group, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/CallStatus' } }
        - { name: outcome, in: query, schema: { $ref: '#/components/schemas/CallOutcome' } }
        - $ref: '#/components/parameters/CreatedFrom'
        - $ref: '#/components/parameters/CreatedTo'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/CallList' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/voice/calls/{call_id}:
    get:
      tags: [Voice]
      summary: Get one call
      description: Requires `voice:read`.
      parameters: [{ $ref: '#/components/parameters/CallId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Call' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/voice/calls/{call_id}/cancel:
    post:
      tags: [Voice]
      summary: Cancel a queued call
      description: Requires `voice:write`. Only while queued, else 409 `call_not_cancelable`.
      parameters: [{ $ref: '#/components/parameters/CallId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Call' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/voice/calls/{call_id}/recording:
    get:
      tags: [Voice]
      summary: Download the recording
      description: Requires `voice:read`. 404 unless `recorded` is true. Recording is off unless `record` was set.
      parameters: [{ $ref: '#/components/parameters/CallId' }]
      responses:
        '200': { description: Audio, content: { audio/wav: {} } }
        default: { $ref: '#/components/responses/Error' }
  /v1/voice/audio-presets:
    post:
      tags: [Audio presets]
      summary: Register an immutable audio preset
      description: Requires `voice:write`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [label, audio]
              properties:
                label: { type: string, maxLength: 64 }
                audio: { oneOf: [{ $ref: '#/components/schemas/AudioUrl' }, { $ref: '#/components/schemas/AudioTts' }] }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/AudioPreset' } } } }
        default: { $ref: '#/components/responses/Error' }
    get:
      tags: [Audio presets]
      summary: List presets
      description: Requires `voice:read`.
      parameters: [{ $ref: '#/components/parameters/Limit' }, { $ref: '#/components/parameters/Cursor' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/AudioPreset' } }, next_cursor: { type: [string, 'null'] } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/voice/audio-presets/{preset_id}:
    parameters: [{ name: preset_id, in: path, required: true, schema: { type: string } }]
    get:
      tags: [Audio presets]
      summary: Get a preset
      description: Requires `voice:read`.
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/AudioPreset' } } } }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Audio presets]
      summary: Delete a preset
      description: Requires `voice:write`. Earlier call records keep the label.
      responses:
        '204': { description: Deleted }
        default: { $ref: '#/components/responses/Error' }
  /v1/sms/messages:
    post:
      tags: [Text messages]
      summary: Send one transactional text message
      description: Requires `sms:write`. `encoding` and `segments` are returned at once, so cost is known before delivery.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
        - $ref: '#/components/parameters/SandboxScenarioSms'
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/MessageCreate' }
      responses:
        '201': { description: Created, headers: { Idempotent-Replay: { $ref: '#/components/headers/IdempotentReplay' } }, content: { application/json: { schema: { $ref: '#/components/schemas/Message' } } } }
        default: { $ref: '#/components/responses/Error' }
    get:
      tags: [Text messages]
      summary: List messages, newest first
      description: Requires `sms:read`.
      parameters:
        - { name: reference, in: query, schema: { type: string } }
        - { name: status, in: query, schema: { $ref: '#/components/schemas/MessageStatus' } }
        - { name: network, in: query, schema: { type: string } }
        - $ref: '#/components/parameters/CreatedFrom'
        - $ref: '#/components/parameters/CreatedTo'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/Message' } }, next_cursor: { type: [string, 'null'] } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/sms/messages/{message_id}:
    get:
      tags: [Text messages]
      summary: Get one message, including its delivery report
      description: Requires `sms:read`.
      parameters: [{ name: message_id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Message' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/optouts:
    post:
      tags: [Opt-outs]
      summary: Add a number to the opt-out list
      description: Requires `optouts:write`. Adding a number that exists merges its channels and returns the entry. A new entry emits `optout.recorded`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [number]
              properties:
                number: { type: string, pattern: '^\+[1-9][0-9]{7,14}$' }
                channels: { type: array, items: { $ref: '#/components/schemas/Channel' }, default: [voice, sms] }
                reason: { type: string, maxLength: 500 }
      responses:
        '201': { description: Created or merged, content: { application/json: { schema: { $ref: '#/components/schemas/Optout' } } } }
        default: { $ref: '#/components/responses/Error' }
    get:
      tags: [Opt-outs]
      summary: List opt-outs
      description: Requires `optouts:read`.
      parameters:
        - { name: number, in: query, schema: { type: string } }
        - { name: channel, in: query, schema: { $ref: '#/components/schemas/Channel' } }
        - $ref: '#/components/parameters/CreatedFrom'
        - $ref: '#/components/parameters/CreatedTo'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/Optout' } }, next_cursor: { type: [string, 'null'] } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/optouts/{optout_id}:
    parameters: [{ name: optout_id, in: path, required: true, schema: { type: string } }]
    get:
      tags: [Opt-outs]
      summary: Get an opt-out
      description: Requires `optouts:read`.
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Optout' } } } }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Opt-outs]
      summary: Remove an opt-out
      description: Requires `optouts:write`. Logged with the key that removed it.
      responses:
        '204': { description: Removed }
        default: { $ref: '#/components/responses/Error' }
  /v1/webhook-endpoints:
    post:
      tags: [Webhooks]
      summary: Register a webhook endpoint
      description: Requires `webhooks:write`. The secret is shown once.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEndpointCreate' }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/WebhookEndpointWithSecret' } } } }
        default: { $ref: '#/components/responses/Error' }
    get:
      tags: [Webhooks]
      summary: List endpoints (never returns secrets)
      description: Requires `webhooks:write`.
      parameters: [{ $ref: '#/components/parameters/Limit' }, { $ref: '#/components/parameters/Cursor' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: object, properties: { data: { type: array, items: { $ref: '#/components/schemas/WebhookEndpoint' } }, next_cursor: { type: [string, 'null'] } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/webhook-endpoints/{endpoint_id}:
    parameters: [{ $ref: '#/components/parameters/EndpointId' }]
    get:
      tags: [Webhooks]
      summary: Get an endpoint
      description: Requires `webhooks:write`.
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/WebhookEndpoint' } } } }
        default: { $ref: '#/components/responses/Error' }
    patch:
      tags: [Webhooks]
      summary: Change url, events, description or headers
      description: Requires `webhooks:write`.
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/WebhookEndpointCreate' }
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/WebhookEndpoint' } } } }
        default: { $ref: '#/components/responses/Error' }
    delete:
      tags: [Webhooks]
      summary: Delete an endpoint
      description: Requires `webhooks:write`.
      responses:
        '204': { description: Deleted }
        default: { $ref: '#/components/responses/Error' }
  /v1/webhook-endpoints/{endpoint_id}/rotate-secret:
    post:
      tags: [Webhooks]
      summary: Rotate the signing secret
      description: Requires `webhooks:write`. The new secret signs at once; for 24 hours deliveries also carry `X-Signature-Previous`.
      parameters: [{ $ref: '#/components/parameters/EndpointId' }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/WebhookEndpointWithSecret' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/webhook-endpoints/{endpoint_id}/test:
    post:
      tags: [Webhooks]
      summary: Send a webhook.test event to this endpoint only
      description: Requires `webhooks:write`.
      parameters: [{ $ref: '#/components/parameters/EndpointId' }]
      responses:
        '202': { description: Accepted, content: { application/json: { schema: { type: object, properties: { event_id: { type: string } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/events:
    get:
      tags: [Events]
      summary: Event feed, oldest first
      description: |
        Requires `events:read`. Returns events after the cursor. `next_cursor` is always a string: on an
        empty page it equals the cursor that was sent, so a poller can resume safely.
      parameters:
        - { name: types, in: query, description: Comma-separated event types, schema: { type: string } }
        - $ref: '#/components/parameters/CreatedFrom'
        - $ref: '#/components/parameters/CreatedTo'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Cursor'
      responses:
        '200': { description: OK, content: { application/json: { schema: { type: object, required: [data, next_cursor], properties: { data: { type: array, items: { $ref: '#/components/schemas/Event' } }, next_cursor: { type: string } } } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/events/{event_id}/replay:
    post:
      tags: [Events]
      summary: Re-send a stored event with the same id
      description: Requires `events:read`. Optional body `{endpoint_id}` limits the replay to one endpoint.
      parameters: [{ name: event_id, in: path, required: true, schema: { type: string } }]
      requestBody:
        content:
          application/json:
            schema: { type: object, properties: { endpoint_id: { type: string } } }
      responses:
        '202': { description: Accepted }
        default: { $ref: '#/components/responses/Error' }
  /v1/exports:
    post:
      tags: [Exports]
      summary: Start a bulk export
      description: Requires `exports:read`. A range above 92 days returns 400. `export.ready` is sent when the file can be downloaded.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [resource, created_from, created_to]
              properties:
                resource: { type: string, enum: [voice_calls, sms_messages] }
                created_from: { type: string, format: date-time }
                created_to: { type: string, format: date-time }
                format: { type: string, enum: [jsonl, csv], default: jsonl }
                reference: { type: string }
      responses:
        '202': { description: Accepted, content: { application/json: { schema: { $ref: '#/components/schemas/Export' } } } }
        default: { $ref: '#/components/responses/Error' }
  /v1/exports/{export_id}:
    get:
      tags: [Exports]
      summary: Get an export
      description: Requires `exports:read`. `download_url` is a signed link valid for 1 hour, usable without a key.
      parameters: [{ name: export_id, in: path, required: true, schema: { type: string } }]
      responses:
        '200': { description: OK, content: { application/json: { schema: { $ref: '#/components/schemas/Export' } } } }
        default: { $ref: '#/components/responses/Error' }
  /health:
    get:
      summary: Liveness
      security: []
      responses:
        '200': { description: OK }
components:
  securitySchemes:
    bearer: { type: http, scheme: bearer }
  headers:
    IdempotentReplay:
      description: Present and `true` when the response is a stored replay.
      schema: { type: string, enum: ['true'] }
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: Up to 64 characters. A repeat within 24 hours with the same body returns the original response; a different body returns 409.
      schema: { type: string, maxLength: 64 }
    SandboxScenarioVoice:
      name: X-Sandbox-Scenario
      in: header
      description: Test keys only; refused with 400 on live keys.
      schema:
        type: string
        enum: [completed, pressed_0, pressed_1, pressed_2, pressed_3, pressed_4, pressed_5, pressed_6, pressed_7, pressed_8, pressed_9, pressed_star, pressed_hash, completed_no_key, hung_up_early, no_answer, busy, rejected, unallocated_number, unreachable, network_error, failed_audio_unavailable, machine]
    SandboxScenarioSms:
      name: X-Sandbox-Scenario
      in: header
      description: Test keys only; refused with 400 on live keys.
      schema:
        type: string
        enum: [delivered, failed_invalid_number, failed_handset_unreachable, failed_blocked_by_network, failed_sender_id_rejected, failed_subscriber_barred, failed_carrier_error, expired]
    CallId: { name: call_id, in: path, required: true, schema: { type: string } }
    EndpointId: { name: endpoint_id, in: path, required: true, schema: { type: string } }
    Limit: { name: limit, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 50 } }
    Cursor: { name: cursor, in: query, description: Opaque, schema: { type: string } }
    CreatedFrom: { name: created_from, in: query, schema: { type: string, format: date-time } }
    CreatedTo: { name: created_to, in: query, schema: { type: string, format: date-time } }
  responses:
    Error:
      description: Error envelope
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message, param, request_id]
          properties:
            code:
              type: string
              enum: [invalid_request, unauthenticated, insufficient_balance, insufficient_scope, ip_not_allowed, not_found, idempotency_conflict, call_not_cancelable, invalid_number, sender_not_registered, number_suppressed, unsupported_characters, language_not_supported, rate_limited, concurrency_limit_exceeded, internal_error, service_unavailable]
            message: { type: string }
            param: { type: [string, 'null'] }
            request_id: { type: string }
      example: { error: { code: invalid_number, message: The number is not in international format., param: to, request_id: req_5f2c9a1b } }
    Money:
      type: object
      properties:
        amount: { type: string, example: '0.50' }
        currency: { type: string, enum: [NGN] }
    Channel: { type: string, enum: [voice, sms] }
    AudioUrl:
      type: object
      required: [type, url]
      properties:
        type: { const: url }
        url: { type: string, format: uri, description: https only }
        label: { type: string, maxLength: 64 }
    AudioPresetRef:
      type: object
      required: [type, preset_id]
      properties:
        type: { const: preset }
        preset_id: { type: string }
        label: { type: string, maxLength: 64 }
    AudioTts:
      type: object
      required: [type, text, language]
      properties:
        type: { const: text_to_speech }
        text: { type: string, maxLength: 2000 }
        language: { type: string, enum: [en, ha, yo] }
        voice: { type: string, enum: [female, male], default: female }
        label: { type: string, maxLength: 64 }
    Audio:
      oneOf: [{ $ref: '#/components/schemas/AudioUrl' }, { $ref: '#/components/schemas/AudioPresetRef' }, { $ref: '#/components/schemas/AudioTts' }]
    Capture:
      type: object
      required: [valid_keys]
      properties:
        valid_keys: { type: array, items: { type: string, enum: ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9', '*', '#'] } }
        timeout_seconds: { type: integer, minimum: 1, maximum: 30, default: 5 }
        max_repeats: { type: integer, minimum: 0, maximum: 5, default: 0 }
    Branch:
      type: object
      required: [key, audio]
      properties:
        key: { type: string, description: One of the valid_keys of the level above }
        audio: { $ref: '#/components/schemas/Audio' }
        capture: { $ref: '#/components/schemas/Capture' }
        branches: { type: array, items: { $ref: '#/components/schemas/Branch' } }
    Ivr:
      type: object
      description: A menu tree of up to three levels.
      properties:
        capture: { $ref: '#/components/schemas/Capture' }
        branches: { type: array, items: { $ref: '#/components/schemas/Branch' } }
    CallCreate:
      type: object
      required: [to, audio]
      properties:
        to: { type: string, pattern: '^\+[1-9][0-9]{7,14}$' }
        from: { type: string, description: Must be registered on the account; the account default when omitted }
        audio: { $ref: '#/components/schemas/Audio' }
        ivr: { $ref: '#/components/schemas/Ivr' }
        ring_timeout_seconds: { type: integer, minimum: 10, maximum: 60, default: 30 }
        max_duration_seconds: { type: integer, minimum: 10, maximum: 600, default: 120 }
        answering_machine_detection: { type: string, enum: ['off', report], default: 'off' }
        record: { type: boolean, default: false }
        reference: { type: string, maxLength: 100, description: Returned unchanged on every record and event }
        retry_group: { type: string, maxLength: 100, description: Links attempts; Ayana counts attempt_number within it }
        metadata: { type: object, maxProperties: 10, additionalProperties: { type: string } }
    CallStatus: { type: string, enum: [queued, in_progress, completed, failed, canceled] }
    CallOutcome: { type: string, enum: [completed, hung_up_early, no_answer, busy, rejected, unallocated_number, unreachable, network_error, failed, canceled] }
    Call:
      type: object
      properties:
        id: { type: string, example: call_8f3a2c71e0b4d5a6c7e8f901 }
        reference: { type: [string, 'null'] }
        retry_group: { type: [string, 'null'] }
        attempt_number: { type: integer }
        status: { $ref: '#/components/schemas/CallStatus' }
        outcome: { oneOf: [{ $ref: '#/components/schemas/CallOutcome' }, { type: 'null' }] }
        failure_reason: { type: [string, 'null'], enum: [audio_unavailable, audio_too_long, audio_format_unsupported, platform_error, null] }
        to: { type: string }
        from: { type: [string, 'null'] }
        audio: { type: object, description: The audio requested, plus label and clip_id of the audio that played }
        audio_length_seconds: { type: [integer, 'null'] }
        audio_played_seconds: { type: [integer, 'null'] }
        audio_path: { type: array, items: { type: string }, description: Audio labels played, in order }
        ivr: { oneOf: [{ $ref: '#/components/schemas/Ivr' }, { type: 'null' }] }
        keypress: { type: [string, 'null'], description: First valid key }
        keypress_at: { type: [string, 'null'], format: date-time }
        keypress_path: { type: array, items: { type: string } }
        ring_timeout_seconds: { type: integer }
        max_duration_seconds: { type: integer }
        answering_machine_detection: { type: string }
        answered_by: { type: [string, 'null'], enum: [human, machine, unknown, null] }
        record: { type: boolean }
        recorded: { type: boolean }
        ring_seconds: { type: [integer, 'null'] }
        duration_seconds: { type: [integer, 'null'], description: Answer to hangup; 0 when unanswered }
        billed_seconds: { type: [integer, 'null'] }
        network_cause_code: { type: [integer, 'null'], description: Raw Q.850 release cause }
        cost: { oneOf: [{ $ref: '#/components/schemas/Money' }, { type: 'null' }] }
        metadata: { type: object, additionalProperties: { type: string } }
        created_at: { type: string, format: date-time }
        dialed_at: { type: [string, 'null'], format: date-time }
        answered_at: { type: [string, 'null'], format: date-time }
        ended_at: { type: [string, 'null'], format: date-time }
    CallList:
      type: object
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Call' } }
        next_cursor: { type: [string, 'null'] }
    AudioPreset:
      type: object
      properties:
        id: { type: string }
        label: { type: string }
        audio: { type: object }
        created_at: { type: string, format: date-time }
    MessageCreate:
      type: object
      required: [to, from, body]
      properties:
        to: { type: string, pattern: '^\+[1-9][0-9]{7,14}$' }
        from: { type: string, description: Registered sender identifier (up to 11 characters) or registered number }
        body: { type: string, description: At most six segments }
        encoding: { type: string, enum: [auto, gsm7, ucs2], default: auto }
        validity_minutes: { type: integer, minimum: 5, maximum: 10080, default: 1440 }
        reference: { type: string, maxLength: 100 }
        metadata: { type: object, maxProperties: 10, additionalProperties: { type: string } }
    MessageStatus: { type: string, enum: [queued, sent, delivered, failed, expired] }
    Message:
      type: object
      properties:
        id: { type: string }
        reference: { type: [string, 'null'] }
        to: { type: string }
        from: { type: string }
        body: { type: string }
        encoding: { type: string, enum: [gsm7, ucs2] }
        segments: { type: integer, description: 'gsm7: 160 in one segment, 153 joined; ucs2: 70 and 67' }
        route: { type: string, enum: [transactional] }
        status: { $ref: '#/components/schemas/MessageStatus' }
        failure_reason:
          oneOf:
            - type: 'null'
            - type: object
              properties:
                category: { type: string, enum: [invalid_number, handset_unreachable, blocked_by_network, sender_id_rejected, subscriber_barred, message_expired, carrier_error, unknown] }
                code: { type: [string, 'null'], description: Raw carrier code, verbatim }
                description: { type: [string, 'null'] }
        network: { type: [string, 'null'], description: From the prefix until the carrier's receipt replaces it }
        billed: { type: boolean }
        cost: { oneOf: [{ $ref: '#/components/schemas/Money' }, { type: 'null' }] }
        validity_minutes: { type: integer }
        metadata: { type: object }
        created_at: { type: string, format: date-time }
        sent_at: { type: [string, 'null'], format: date-time }
        delivered_at: { type: [string, 'null'], format: date-time }
    Optout:
      type: object
      properties:
        id: { type: string }
        number: { type: string }
        channels: { type: array, items: { $ref: '#/components/schemas/Channel' } }
        source: { type: string, enum: [api, console, sms_reply] }
        reason: { type: [string, 'null'] }
        created_at: { type: string, format: date-time }
    WebhookEndpointCreate:
      type: object
      required: [url, events]
      properties:
        url: { type: string, format: uri, description: https only }
        events:
          type: array
          description: Event types, or ["*"] for all
          items: { type: string, enum: ['*', call.answered, call.completed, sms.delivered, sms.failed, optout.recorded, export.ready, webhook.test] }
        description: { type: string, maxLength: 500 }
        headers: { type: object, maxProperties: 3, additionalProperties: { type: string } }
    WebhookEndpoint:
      type: object
      properties:
        id: { type: string }
        url: { type: string }
        events: { type: array, items: { type: string } }
        description: { type: [string, 'null'] }
        headers: { type: object }
        created_at: { type: string, format: date-time }
    WebhookEndpointWithSecret:
      allOf:
        - $ref: '#/components/schemas/WebhookEndpoint'
        - type: object
          properties:
            secret: { type: string, description: 'whsec_ plus 32 random bytes in base64url. Shown once.' }
    Event:
      type: object
      required: [id, type, created_at, data]
      properties:
        id: { type: string, description: Stable across retries and replays; use it to remove duplicates }
        type: { type: string, enum: [call.answered, call.completed, sms.delivered, sms.failed, optout.recorded, export.ready, webhook.test] }
        created_at: { type: string, format: date-time }
        data: { type: object, description: 'The Call, Message, Optout or Export record; empty for webhook.test' }
    Export:
      type: object
      properties:
        id: { type: string }
        resource: { type: string, enum: [voice_calls, sms_messages] }
        format: { type: string, enum: [jsonl, csv] }
        status: { type: string, enum: [pending, processing, ready, failed] }
        created_from: { type: string, format: date-time }
        created_to: { type: string, format: date-time }
        reference: { type: [string, 'null'] }
        row_count: { type: [integer, 'null'] }
        download_url: { type: [string, 'null'], description: Signed, valid 1 hour, no key needed }
        expires_at: { type: [string, 'null'], format: date-time }
        created_at: { type: string, format: date-time }
        completed_at: { type: [string, 'null'], format: date-time }
