--- name: storage-voicemail-archive title: "Storage Voicemail Archive" description: "Storage Voicemail Archive — record voicemails to Telnyx Cloud Storage with search." language: python framework: flask telnyx_products: [Cloud Storage, Voice, Call Recording] channel: [voice] --- # Storage Voicemail Archive Storage Voicemail Archive — record voicemails to Telnyx Cloud Storage with search. ## Telnyx Cloud Storage (S3-Compatible) Telnyx Cloud Storage is S3-compatible, so this app uploads recordings with `boto3` instead of a REST call. The client points at the region endpoint `https://{region}.telnyxcloudstorage.com` and uses your Telnyx API key as **both** the access key and the secret key. See the [Cloud Storage quick start](https://developers.telnyx.com/docs/cloud-storage/quick-start). ```python s3 = boto3.client( "s3", endpoint_url=f"https://{REGION}.telnyxcloudstorage.com", aws_access_key_id=TELNYX_API_KEY, aws_secret_access_key=TELNYX_API_KEY, region_name=REGION, config=Config(signature_version="s3v4"), ) s3.put_object(Bucket=STORAGE_BUCKET, Key=filename, Body=audio, ContentType="audio/mpeg") ``` The region comes from `TELNYX_STORAGE_REGION` (default `us-central-1`). Available regions: `us-central-1`, `us-east-1`, `us-west-1`, `eu-central-1`. ## Telnyx Webhook Events This app handles these webhook events ([Call Control docs](https://developers.telnyx.com/docs/api/v2/call-control)) ([Messaging docs](https://developers.telnyx.com/docs/api/v2/messaging)): - `call.answered` — Call connected — app begins interaction - `call.hangup` — Call ended — app cleans up session, triggers post-call processing - `call.initiated` — New inbound or outbound call detected - `call.recording.saved` — Call recording saved — URL available for download/processing - `call.speak.ended` — TTS playback finished — app transitions to next action (gather, transfer, etc.) - `message.received` — Inbound SMS/MMS received ## External Service Integrations - **Email / SMTP** — Email notifications and alerts ## Architecture ``` Inbound Phone Call │ ▼ ┌──────────────────┐ │ Call Control │ └────────┬─────────┘ │ ├──► Cloud Storage ├──► Call Recording │ ▼ Email ``` ## Environment Variables Copy `.env.example` to `.env` and fill in: | Variable | Type | Example | Required | Description | Where to get it | |----------|------|---------|----------|-------------|-----------------| | `TELNYX_API_KEY` | `string` | `KEY0123456789ABCDEF` | **yes** | Telnyx API v2 key — used for Call Control and as both the S3 access and secret key for Cloud Storage | [Portal](https://portal.telnyx.com/api-keys) | | `TELNYX_PUBLIC_KEY` | `string` | `your_public_key` | **yes** | Telnyx public key for webhook signature verification | [Portal](https://portal.telnyx.com/api-keys) | | `STORAGE_BUCKET` | `string` | `my-bucket` | no | Telnyx Cloud Storage bucket name | [Portal](https://portal.telnyx.com/storage) | | `TELNYX_STORAGE_REGION` | `string` | `us-central-1` | no | Cloud Storage region endpoint (`us-central-1`, `us-east-1`, `us-west-1`, `eu-central-1`); defaults to `us-central-1` | [Cloud Storage docs](https://developers.telnyx.com/docs/cloud-storage/quick-start) | | `VOICEMAIL_NUMBER` | `string` | `your_value` | **yes** | Voicemail number | — | | `PORT` | `integer` | `5000` | no | HTTP server port | — | ## Setup ```bash git clone https://github.com/team-telnyx/telnyx-code-examples.git cd telnyx-code-examples/storage-voicemail-archive-python cp .env.example .env # ← fill in your credentials pip install -r requirements.txt python app.py # starts on http://localhost:5000 ``` ### Webhook Configuration 1. Expose your local server: ```bash ngrok http 5000 ``` 2. Copy the HTTPS URL and configure in [Telnyx Portal](https://portal.telnyx.com): - **Call Control Application** → Webhook URL → `https://.ngrok.io/webhooks/voice` ## API Reference ### `GET /voicemails` Returns voicemails ```bash curl http://localhost:5000/voicemails ``` **Response:** ```json { "items": [ { "id": "item-001", "status": "active", "created_at": "2026-07-15T14:30:00Z" } ] } ``` ### `GET /voicemails/search` Returns search ```bash curl http://localhost:5000/voicemails/search ``` **Response:** ```json { "items": [ { "id": "item-001", "status": "active", "created_at": "2026-07-15T14:30:00Z" } ] } ``` ### `GET /health` Returns health ```bash curl http://localhost:5000/health ``` **Response:** ```json { "status": "ok", "uptime_seconds": 3842, "active_sessions": 2, "version": "1.0.0" } ``` ## Webhook Endpoints ### `POST /webhooks/voice` Receives [Telnyx Call Control](https://developers.telnyx.com/docs/voice/call-control) webhook events. **Events handled:** `call.answered`, `call.hangup`, `call.initiated`, `call.recording.saved`, `call.speak.ended` **Example payload:** ```json { "data": { "event_type": "call.initiated", "id": "0ccc7b54-4df3-4bca-a65a-3da1ecc777f0", "occurred_at": "2026-07-15T14:30:00.000Z", "payload": { "call_control_id": "v3:uMi2qMWHT-mLFGkEm4t9tA", "connection_id": "1494404757140276705", "call_leg_id": "428c31b6-7af4-4bcb-b7f5-5013ef9657c1", "call_session_id": "428c31b6-abcd-1234-5678-5013ef9657c1", "client_state": null, "from": "+12125551234", "to": "+13105559876", "direction": "incoming", "state": "ringing" }, "record_type": "event" }, "meta": { "attempt": 1, "delivered_to": "https://your-server.example.com/webhooks/voice" } } ``` ## Troubleshooting | Issue | Cause | Fix | |-------|-------|-----| | `401 Unauthorized` | Invalid or missing API key | Verify `TELNYX_API_KEY` in `.env` matches your key in the [Portal](https://portal.telnyx.com/api-keys) | | Webhook not received | Local server not publicly reachable | Expose it with a tunnel (e.g. ngrok) and set the webhook URL in the [Telnyx Portal](https://portal.telnyx.com) | | `422 Unprocessable Entity` | Missing or malformed request fields | Check the request body against the API Reference above | ## Related Examples - [AI After Hours Emergency Triage (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-after-hours-emergency-triage-python/README.md) - [AI Assistant Knowledge Base (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-assistant-knowledge-base-python/README.md) - [AI Assistant Multi Tool (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-assistant-multi-tool-python/README.md) - [AI Assistant Phone Setup (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-assistant-phone-setup-python/README.md) - [AI Audiobook Narrator (Python)](https://raw.githubusercontent.com/team-telnyx/telnyx-code-examples/main/ai-audiobook-narrator-python/README.md) ## Resources - [Call Control Guide](https://developers.telnyx.com/docs/voice/call-control) - [Cloud Storage Quick Start (S3-compatible)](https://developers.telnyx.com/docs/cloud-storage/quick-start) - [Telnyx Developer Docs](https://developers.telnyx.com) - [Telnyx Portal](https://portal.telnyx.com) ## Why Telnyx Telnyx is an **AI Communications Infrastructure** platform — voice, messaging, SIP, AI, and IoT on one private, global network.