nopaque - Python SDK for Nopaque

Official Python client for the Nopaque API.

Install

pip install nopaque

Quick start

from nopaque import Nopaque
from nopaque.models.mapping import MappingJobConfig

client = Nopaque(api_key="nop_live_...")   # or set NOPAQUE_API_KEY

# Create a mapping job and wait for it to complete
job = client.mapping.create(
    name="Main IVR",
    phone_number="+441234567890",
    config=MappingJobConfig(mapping_mode="dtmf"),
)
client.mapping.start(job.id)
final = client.mapping.wait_for_complete(job.id)
print(final.status)

# List audio files with automatic pagination
for audio in client.audio.list():
    print(audio.id, audio.file_name)

client.close()

Async

import asyncio
from nopaque import AsyncNopaque

async def main():
    async with AsyncNopaque() as client:
        job = await client.mapping.get("map_abc123")
        print(job.status)

asyncio.run(main())

Digital testing (beta)

Run automated chat-channel conversations against a bot and get a pass/fail verdict. Access is limited to beta workspaces during the beta period.

sector and mission are required — the API returns a 400 without them.

run = client.digital_testing.create(
    target_ref="acme/billing-bot",
    target={"transport": "web-widget", "url": "https://example.com/support"},
    sector="utilities",
    mission="check the outstanding balance",
    kind="freeform",
    acceptance="The bot states the outstanding balance.",
)

finished = client.digital_testing.wait_for_run(run.id)
# `completed` with outcome "fail" is a RESULT, not an error.
print(finished.status, finished.outcome, finished.pass_rate)

Reusable configs live under client.digital_test_configs (create, list, get, update, delete, launch), and client.digital_compliance lists compliance audits and fetches a per-target report.

Survey tests

A survey test runs the other way round from a call test: your survey platform starts the conversation, and a nopaque respondent answers it. Starting a test claims one of your workspace's survey numbers; you then send your survey to it.

run = client.surveys.start(
    config_id="d41eaa86-34ae-4b7c-b5cc-debf7c254b44",
    sender="+447921721840",   # the number your survey platform sends FROM
    window_secs=600,          # the survey must arrive within this window
)
print("Send the survey to", run.agent_e164)

# ... trigger your survey platform, aimed at run.agent_e164 ...

result = client.surveys.wait_for_result(run.run_id)   # until the transcript is final
print(result.outcome, result.answers_given)
for turn in result.turns:
    print(turn.at, turn.from_, turn.text)

start raises ConflictError when the workspace has no free survey number for that sender. wait_for_result returns a failed capture rather than raising it; check result.capture.status. Saved respondents live under client.surveys.configs (create, list, get, update, delete), and past results under client.surveys.results (list, list_page, get).

Voices

List the operator-enabled voices a mission test may use, and which one is the default.

voices = client.testing.list_voices()
for voice in voices.voices:
    print(voice.voice_id, voice.name)
print("default:", voices.default_voice_id)

Features

• Full coverage of the Nopaque REST API via API-key auth
• Typed Pydantic v2 models for every request and response
• Paired sync (Nopaque) and async (AsyncNopaque) clients
• Automatic pagination for list endpoints
• Polling helpers for long-running jobs (wait_for_complete)
• One-call audio upload/download wrapping the presigned-URL flow
• Method-aware retry with exponential jitter and Retry-After honor
• Typed exception hierarchy (NotFoundError, RateLimitError, etc.)

Documentation

Full reference: https://nopaque.co.uk/docs/sdks

Authentication

Pass your API key to the client:

Nopaque(api_key="nop_live_...")

Or set the environment variable:

export NOPAQUE_API_KEY=nop_live_...

API keys are workspace-scoped and subject to per-minute rate limits based on your subscription tier. Free tier cannot use API keys.

Requirements

• Python 3.9+
• httpx >= 0.27, pydantic >= 2.6

License

MIT