Update to Sinch Build for Codex

{
  "description": "Build voice apps with the Sinch Voice API v1. Use for phone calls, text-to-speech (TTS), IVR menus, DTMF input, conference calling, call recording, call forwarding, answering machine detection (AMD), SIP routing, WebSocket audio streaming, and SVAML call control. Not for Voice API v2 (public preview); use the sinch-voice-api-v2 skill for that.",
  "included_files": [
    {
      "relative_path": "references/callbacks.md",
      "size_in_bytes": 10611
    },
    {
      "relative_path": "references/examples/dotnet.md",
      "size_in_bytes": 5868
    },
    {
      "relative_path": "references/examples/java.md",
      "size_in_bytes": 5587
    },
    {
      "relative_path": "references/examples/nodejs.md",
      "size_in_bytes": 5090
    },
    {
      "relative_path": "references/examples/python.md",
      "size_in_bytes": 4255
    },
    {
      "relative_path": "references/shared-policy.md",
      "size_in_bytes": 14835
    },
    {
      "relative_path": "references/svaml.md",
      "size_in_bytes": 14510
    },
    {
      "relative_path": "scripts/common/voice_client.cjs",
      "size_in_bytes": 4643
    },
    {
      "relative_path": "scripts/get_call_info.cjs",
      "size_in_bytes": 1983
    },
    {
      "relative_path": "scripts/list_numbers.cjs",
      "size_in_bytes": 1310
    },
    {
      "relative_path": "scripts/make_conference_call.cjs",
      "size_in_bytes": 2641
    },
    {
      "relative_path": "scripts/make_tts_call.cjs",
      "size_in_bytes": 2605
    }
  ],
  "name": "sinch-voice-api",
  "skill_md_contents": "---\nname: sinch-voice-api\ndescription: Build voice apps with the Sinch Voice API v1. Use for phone calls, text-to-speech (TTS), IVR menus, DTMF input, conference calling, call recording, call forwarding, answering machine detection (AMD), SIP routing, WebSocket audio streaming, and SVAML call control. Not for Voice API v2 (public preview); use the sinch-voice-api-v2 skill for that.\nmetadata:\n  author: Sinch\n  version: 1.3.0\n  category: Voice\n  tags: voice, calls, tts, ivr, dtmf, conference, recording, svaml, sip, amd, webrtc\n  uses:\n    - sinch-authentication\n    - sinch-sdks\n---\n\n# Sinch Voice API\n\n## Overview\n\nThe Sinch Voice API lets you make, receive, and control voice calls programmatically via REST. It uses **SVAML** (Sinch Voice Application Markup Language) to define call flows through callback events.\n\n> **Version scope: Voice API v1 only.** This skill covers the `/calling/v1` API, its SVAML dialect, and its ICE/ACE/PIE/DiCE callbacks. Sinch also offers **Voice API 2.0**, currently in public preview, with a different API surface. If the user asks for Voice 2.0, v2 endpoints, or the preview API, do not adapt the v1 guidance below. Load the `sinch-voice-api-v2` skill instead.\n\n## Agent Instructions\n\n> **Policy gate `sinch-shared-policy@5` (`sha256:4864cf0fa8d6`):** The policy digest below is binding as written. Before implementation or live execution, read [the full shared Sinch policy](references/shared-policy.md) once per conversation — skip it if this exact ID/version/fingerprint is already loaded; read it if the version is newer or the fingerprint differs. This skill's canonical operation routes live in its Agent Instructions and Links sections.\n\n<!-- sinch-policy-digest: start (generated; edit docs/SINCH_SHARED_POLICY.md and run scripts/sync_sinch_skill_references.py) -->\n**Sinch policy digest (binding):**\n\n1. Load the shared policy once per conversation; skip duplicate copies bearing the same ID/version/fingerprint.\n2. Infer product, language, region, and environment from the request and workspace; ask one combined question only for true blockers. Prefer the official Sinch SDK unless the request or workspace decides otherwise or no official SDK covers the language or operation.\n3. Code-generation approval is not execution approval. Classify every operation (read-only / reversible / billable / destructive) and obtain explicit approval before billable or destructive calls.\n4. Tier B facts — endpoint paths, methods, field names, enums, limits, webhook payloads, signature algorithms, SDK signatures — require fetching the exact canonical document in the current session before use.\n5. Bundled scripts, references, and examples are Tier C: illustrations, never schema authority. Never promote example values to production defaults.\n6. If a route is unresolved or a canonical fetch fails, climb the resolution ladder in order — re-search already-fetched documents (raw, not summarized), consult https://developers.sinch.com/llms.txt, follow first-party links, retry once — before failing closed. Never pattern-guess a documentation URL; never substitute memory, search snippets, or bundled files.\n7. Keep an evidence ledger mapping each fetched source to the fields and claims it authorized.\n8. Bound all polling and retries (backoff, jitter, hard cap); check state before retrying billable or destructive operations; report a timeout as unknown, not failed.\n9. Report verification levels separately (lint → unit → mock contract → sandbox → live → end-to-end); an HTTP 2xx does not prove delivery. State the levels not performed.\n10. Load only the smallest skill set that owns the behavior; if a required skill is unavailable, name it and stop rather than improvising its instructions.\n<!-- sinch-policy-digest: end -->\n\nBefore generating code, infer these from the request, prior turns, and workspace. Ask one combined question only for items that remain unresolved and block implementation:\n\n1. **Approach** — do not ask. Default to the official Sinch SDK for the resolved language; use direct API calls (curl, `fetch`, `requests`) only when the request or an existing dependency already chooses them, or no official SDK covers the language or operation. State the chosen approach.\n2. **Language** — for SDK: Node.js, Python, Java, or .NET. For direct API: any language, or curl.\n\nWhen using the **SDK**, refer to the `sinch-sdks` skill for installation and client initialization, then to the bundled examples and SDK reference linked in Links.\n\nWhen using **direct API calls**, refer to the Voice API Reference linked in Links for request/response schemas.\n\n**Security**: See the Security section below for url fetching policy, handling inbound callback content, and credential handling.\n\n## Source of Truth — what to load, and what is authoritative\n\nThis skill has three kinds of content with UNEQUAL reliability. Follow this precedence:\n\n1. **Canonical docs at `developers.sinch.com` (AUTHORITATIVE).** The `.md` doc links in\n   this skill are the single source of truth for exact request/response schemas, field\n   names and nesting, enum values, signature/auth schemes, and limits. Before writing\n   code that constructs a payload, verifies a signature, or parses a callback/response,\n   fetch the specific linked doc and confirm the exact shape there. Fetching first-party\n   `developers.sinch.com` URLs is permitted by the Security/URL policy. Never invent, guess, or pattern-extrapolate a documentation URL — only fetch doc URLs written verbatim in this skill or reached by following a link on a page you already fetched; a trusted domain does not make a guessed path real.\n2. **Bundled `references/*.md` (NAVIGATIONAL SUMMARIES — not authoritative).** They orient\n   you and point at the right canonical doc; they may lag, omit fields, or simplify\n   nesting. Use them to decide what to build and which doc to open. Do NOT transcribe a\n   field name, nesting, encoding, or enum from a reference or from the SKILL.md overview\n   into shipped code without confirming it in the tier-1 doc. If a detail appears only in\n   a summary, treat it as unverified and say so.\n3. **Bundled `scripts/**` (EXECUTION TOOLS — not a schema reference).** Runnable helpers\n   for DOING a task when you don't need to write application code (e.g. create a webhook,\n   send a test message, list resources). Run them to perform the action. Do NOT copy their\n   payload literals or logic into a new codebase as if they were the spec. When authoring\n   code, ignore the scripts and work from tier 1.\n\nQuick rule: **doing a one-off task → run a script. Writing code → load the doc.** Never cite\nan exact field, header, enum, or encoding you only saw in a summary or a script.\n\n## Getting Started\n\n### Agent Credentials handling\n\nStore credentials in environment variables — never hardcode application keys or secrets in commands or source code:\n\n```bash\n# .env — keep out of version control (add it to .gitignore) and restrict access: chmod 600 .env\nSINCH_APPLICATION_KEY=\"your-application-key\"\nSINCH_APPLICATION_SECRET=\"your-application-secret\"\n```\n\nLoad it into the current shell with `set -a; . ./.env; set +a`. Do not type real secret values at the shell prompt or pass them as command-line arguments — they end up in shell history and process listings.\n\n### Authentication\n\nEnsure that authentication headers are properly set when making API calls. The Voice API uses **Application Key + Application Secret** (not project-level OAuth2):\n\n```bash\n-u \"$SINCH_APPLICATION_KEY:$SINCH_APPLICATION_SECRET\"\n```\n\nSee the `sinch-authentication` skill for full setup.\n\n- **Basic Auth**: `Authorization: Basic base64(APPLICATION_KEY:APPLICATION_SECRET)` *(Summary only — confirm exact names/encoding/enums against the authoritative [Authentication Guide](https://developers.sinch.com/docs/voice/api-reference/authentication.md) doc before implementing.)*\n- **Signed Requests** (production): HMAC-SHA256 signing. See [Authentication Guide](https://developers.sinch.com/docs/voice/api-reference/authentication.md).\n\n### Base URLs\n\n| Region | Base URL |\n|--------|----------|\n| Global (default) | `https://calling.api.sinch.com` |\n| North America | `https://calling-use1.api.sinch.com` |\n| Europe | `https://calling-euc1.api.sinch.com` |\n| Southeast Asia 1 | `https://calling-apse1.api.sinch.com` |\n| Southeast Asia 2 | `https://calling-apse2.api.sinch.com` |\n| South America | `https://calling-sae1.api.sinch.com` |\n\nConfiguration endpoints (numbers, callbacks) use: `https://callingapi.sinch.com`\n\n### SDK Installation\n\nSee `sinch-sdks` for installation and client initialization across all languages.\n\n### First API Call: TTS Callout\n\n```bash\ncurl -X POST \\\n  \"https://calling.api.sinch.com/calling/v1/callouts\" \\\n  -u \"$SINCH_APPLICATION_KEY:$SINCH_APPLICATION_SECRET\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"method\": \"ttsCallout\",\n    \"ttsCallout\": {\n      \"destination\": { \"type\": \"number\", \"endpoint\": \"+14045005000\" },\n      \"cli\": \"+14045001000\",\n      \"locale\": \"en-US\",\n      \"text\": \"Hello! This is a test call from Sinch.\"\n    }\n  }'\n```\n\n**Node.js SDK:**\n\n```javascript\nimport { SinchClient } from \"@sinch/sdk-core\";\n\nconst sinch = new SinchClient({\n  applicationKey: \"{APPLICATION_KEY}\",\n  applicationSecret: \"{APPLICATION_SECRET}\",\n});\n\nconst response = await sinch.voice.callouts.tts({\n  ttsCalloutRequestBody: {\n    destination: { type: \"number\", endpoint: \"+14045005000\" },\n    cli: \"+14045001000\",\n    locale: \"en-US\",\n    text: \"Hello! This is a test call from Sinch.\",\n  },\n});\nconsole.log(\"Call ID:\", response.callId);\n```\n\nFor more examples, see [Callouts Reference](https://developers.sinch.com/docs/voice/api-reference/voice/callouts/callouts.md) or [bundled examples](references/examples/).\n\n## Key Concepts\n\n### SVAML (Sinch Voice Application Markup Language)\n\nSVAML controls call flow. Every SVAML response has:\n\n- **instructions** (array): Multiple tasks — play audio, record, set cookies\n- **action** (object): Exactly ONE routing/control action\n\nFull reference: [SVAML Actions](https://developers.sinch.com/docs/voice/api-reference/svaml.md#actions) | [SVAML Instructions](https://developers.sinch.com/docs/voice/api-reference/svaml.md#instructions) | [Bundled SVAML Reference](references/svaml.md)\n\n### Actions (one per response)\n\n| Action | Description |\n|--------|-------------|\n| `hangup` | Terminate the call |\n| `continue` | Continue call setup (ACE response to proceed without rerouting) |\n| `connectPstn` | Connect to PSTN number. Supports `amd` for Answering Machine Detection |\n| `connectMxp` | Connect to Sinch SDK (in-app) endpoint |\n| `connectConf` | Connect to conference room by `conferenceId` |\n| `connectSip` | Connect to SIP endpoint |\n| `connectStream` | Connect to a WebSocket server for real-time audio streaming (**closed beta** — contact Sinch to enable) |\n| `runMenu` | IVR menu with DTMF collection (supports `enableVoice` for speech input) |\n| `park` | Park (hold) the call with looping prompt |\n\n*(Summary only — confirm exact names/encoding/enums against the authoritative [SVAML Actions](https://developers.sinch.com/docs/voice/api-reference/svaml.md#actions) doc before implementing.)*\n\n### Instructions (multiple per response)\n\n| Instruction | Description |\n|-------------|-------------|\n| `playFiles` | Play audio files, TTS via `#tts[]`, SSML via `#ssml[]` |\n| `say` | Synthesize and play text-to-speech |\n| `sendDtmf` | Send DTMF tones |\n| `setCookie` | Persist key-value state across callback events in the session |\n| `answer` | Answer the call (sends a SIP 200 OK to the INVITE, which starts billing). Required before playing prompts on unanswered calls |\n| `startRecording` | Begin recording. Supports `transcriptionOptions` for auto-transcription |\n| `stopRecording` | Stop an active recording |\n\n*(Summary only — confirm exact names/encoding/enums against the authoritative [SVAML Instructions](https://developers.sinch.com/docs/voice/api-reference/svaml.md#instructions) doc before implementing.)*\n\n### Callback Events\n\n| Event | Trigger | SVAML Response |\n|-------|---------|----------------|\n| **ICE** | Call received by Sinch platform | Yes |\n| **ACE** | Call answered by callee | Yes |\n| **DiCE** | Call disconnected | No (fire-and-forget, logging only) |\n| **PIE** | DTMF/voice input from `runMenu` | Yes |\n| **Notify** | Notification (e.g., recording finished) | No |\n\nSee [Callbacks Reference](https://developers.sinch.com/docs/voice/api-reference/voice/callbacks/ice.md) for event schemas, or [bundled callbacks reference](references/callbacks.md) for full field tables and JSON examples.\n\n### Callout Types\n\n| Method | Use Case |\n|--------|----------|\n| `ttsCallout` | Call and play synthesized speech. Supports `text` or advanced `prompts` (`#tts[]`, `#ssml[]`, `#href[]`) |\n| `conferenceCallout` | Call and connect to a conference room |\n| `customCallout` | Full SVAML control with inline ICE/ACE/PIE |\n\n*(Summary only — confirm exact names/encoding/enums against the authoritative [Callouts](https://developers.sinch.com/docs/voice/api-reference/voice/callouts/callouts.md) doc before implementing.)*\n\nCallout flags: `enableAce` (default `false`), `enableDice` (default `false`), `enablePie` (default `false`) control which callbacks fire.\n\n### REST Endpoints\n\nPaths starting with `/calling/v1/` use the **regional base URL** from the table above. Paths starting with `/v1/configuration/` use `https://callingapi.sinch.com`.\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| POST | `/calling/v1/callouts` | Place a callout (TTS, conference, or custom) |\n| PATCH | `/calling/v1/calls/id/{callId}` | Update in-progress call with SVAML (PSTN/SIP only) |\n| GET | `/calling/v1/calls/id/{callId}` | Get call info |\n| PATCH | `/calling/v1/calls/id/{callId}/leg/{callLeg}` | Manage a call leg (PlayFiles/Say only) |\n| GET | `/calling/v1/conferences/id/{conferenceId}` | Get conference info |\n| DELETE | `/calling/v1/conferences/id/{conferenceId}` | Kick all participants |\n| PATCH | `/calling/v1/conferences/id/{conferenceId}/{callId}` | Mute/unmute/hold participant |\n| DELETE | `/calling/v1/conferences/id/{conferenceId}/{callId}` | Kick specific participant |\n| GET | `/v1/configuration/numbers` | List numbers and capabilities |\n| POST | `/v1/configuration/numbers` | Assign numbers to an application |\n| DELETE | `/v1/configuration/numbers` | Un-assign a number |\n| GET/POST | `/v1/configuration/callbacks/applications/{applicationkey}` | Get/update callback URLs |\n\n## Common Patterns\n\n### IVR Menu (SVAML)\n\n```json\n{\n  \"instructions\": [\n    { \"name\": \"setCookie\", \"key\": \"step\", \"value\": \"ivr\" }\n  ],\n  \"action\": {\n    \"name\": \"runMenu\",\n    \"mainMenu\": \"main\",\n    \"menus\": [{\n      \"id\": \"main\",\n      \"mainPrompt\": \"#tts[Press 1 for sales or 2 for support.]\",\n      \"options\": [\n        { \"dtmf\": 1, \"action\": \"return(sales)\" },\n        { \"dtmf\": 2, \"action\": \"return(support)\" }\n      ]\n    }]\n  }\n}\n```\n\n### Conference with Recording\n\n```json\n{\n  \"instructions\": [\n    { \"name\": \"startRecording\", \"options\": { \"notificationEvents\": true } }\n  ],\n  \"action\": {\n    \"name\": \"connectConf\",\n    \"conferenceId\": \"myRoom\",\n    \"moh\": \"ring\"\n  }\n}\n```\n\n### PSTN Forward with AMD\n\n```json\n{\n  \"action\": {\n    \"name\": \"connectPstn\",\n    \"number\": \"+14045009000\",\n    \"cli\": \"+14045001000\",\n    \"maxDuration\": 3600,\n    \"amd\": { \"enabled\": true }\n  }\n}\n```\n\n## Gotchas and Best Practices\n\n1. **Callback URL must be publicly accessible.** Use ngrok for local dev. Configure in Dashboard under Voice app settings.\n2. **ONE action per SVAML response.** Multiple instructions are fine. Chain callbacks for sequential actions (ICE → ACE → PIE).\n3. **ACE not sent for in-app destinations.** ACE is not issued when destination type is `username`, only for PSTN/SIP. Setting `enableAce: true` has no effect for in-app destinations.\n4. **DiCE is fire-and-forget.** Informational only. No SVAML response expected. Use for logging/cleanup.\n5. **Regional endpoints matter.** Wrong region increases latency. Conference rooms have regional scope — force all participants to the same region for cross-region conferences.\n6. **Instruction ordering matters.** Array order = execution order. Place `answer` before `playFiles`; place `startRecording` before the connecting action.\n7. **Max call duration: 14400 seconds (4 hours).** Set `maxDuration` on `connectPstn`/`connectSip` for shorter limits.\n8. **Validate callback signatures in production.** HMAC-SHA256 signature in `Authorization` header. See [Callback Signing](https://developers.sinch.com/docs/voice/api-reference/authentication/callback-signed-request.md).\n9. **`setCookie` for state.** Carries key-value pairs across ICE, ACE, PIE, DiCE within a call session.\n10. **`connectMxp` does not support recording.** `startRecording`/`stopRecording` instructions are ignored with `connectMxp`.\n11. **`runMenu` defaults.** `barge`: `true` (input accepted during prompt). `timeoutMills`: `5000` ms.\n12. **AMD on `connectPstn`.** `amd: { enabled: true, async: true/false }` for answering machine detection.\n13. **`startRecording` transcription.** `transcriptionOptions: { enabled: true, locale: \"en-US\" }` for auto-transcription.\n14. **Conference DTMF options.** `conferenceDtmfOptions` on `conferenceCallout`/`connectConf` with modes: `ignore` (default), `forward`, `detect` (sends PIE). *(Summary only — confirm exact names/encoding/enums against the authoritative [SVAML Actions](https://developers.sinch.com/docs/voice/api-reference/svaml.md#actions) doc before implementing.)*\n15. **`cli` is required for TTS callouts to connect.** The API accepts a TTS callout without a `cli` parameter and returns a call ID, but the call will never reach the destination. The `cli` is the number displayed as the incoming caller — use your verified number or your Dashboard-assigned number, in E.164 format (e.g., `\"+14151112223333\"`). To test, register on the [Sinch Dashboard](https://dashboard.sinch.com) and use the free number assigned to your app. See [Assign your number](https://developers.sinch.com/docs/voice/getting-started.md#2-assign-your-number-and-get-your-credentials).\n\n## Security\n\n- **API key handling** — never expose `SINCH_APPLICATION_KEY`, and especially never expose `SINCH_APPLICATION_SECRET` in client-side code, logs, or committed source. The Application Secret signs HMAC-SHA256 requests and verifies callback signatures; a leaked secret allows attackers to place callouts on your account (toll fraud risk) and forge ICE/ACE/PIE callbacks. Load from environment variables or a secrets manager. Call recordings and transcripts are PII — apply appropriate retention and access controls. Rotate via the [Sinch Build Dashboard](https://dashboard.sinch.com/voice/apps) if leaked.\n- **URL policy (by purpose)** — Never send the Application Key/Secret to any host other than the credentialed API hosts below, and do not follow redirects with credentials attached.\n  - *Documentation (no credentials):* `developers.sinch.com`.\n  - *Credentialed API requests:* `https://calling.api.sinch.com` and the regional hosts `calling-use1`, `calling-euc1`, `calling-apse1`, `calling-apse2`, `calling-sae1` under `.api.sinch.com`, plus `https://callingapi.sinch.com` (configuration). The bundled scripts reject any other host.\n  - *Dashboard links for the user (never fetched with credentials):* `dashboard.sinch.com`.\n  - *Untrusted:* recording downloads and sender-supplied URLs in inbound callback payloads — do not fetch or follow them without explicit allowlisting.\n- **Callback handlers** — Always verify the HMAC-SHA256 callback signature in the `Authorization` header before trusting ICE/ACE/PIE/DiCE payloads. *(Summary only — confirm exact names/encoding/enums against the authoritative [Callback Signing](https://developers.sinch.com/docs/voice/api-reference/authentication/callback-signed-request.md) doc before implementing.)* Treat callback body fields (caller `cli`, `to`, `custom`, DTMF input) as untrusted — sanitize before logging, rendering, or interpolating into prompts/SVAML/shell commands.\n\n## Links\n\n- Bundled examples: [Node.js](references/examples/nodejs.md) | [Python](references/examples/python.md) | [Java](references/examples/java.md) | [.NET](references/examples/dotnet.md)\n- [Voice API Reference (Markdown)](https://developers.sinch.com/docs/voice/api-reference/voice.md)\n- [Voice API 2.0 docs (public preview; see the `sinch-voice-api-v2` skill)](https://developers.sinch.com/docs/voice-2.0)\n- [Voice API OpenAPI Spec (YAML)](https://developers.sinch.com/_bundle/docs/voice/api-reference/voice.yaml?download)\n- SVAML actions and instructions: see [references/svaml.md](references/svaml.md)\n- Callbacks (ICE, ACE, DiCE, PIE) and callback signing: see [references/callbacks.md](references/callbacks.md)\n- [Callouts](https://developers.sinch.com/docs/voice/api-reference/voice/callouts/callouts.md)\n- [Authentication](https://developers.sinch.com/docs/voice/api-reference/authentication.md)\n- [Node.js SDK Reference](https://developers.sinch.com/docs/voice/sdk/node/syntax-reference.md)\n- [Python SDK Reference](https://developers.sinch.com/docs/voice/sdk/py/syntax-reference.md)\n- [Java SDK Reference](https://developers.sinch.com/docs/voice/sdk/java/syntax-reference.md)\n- [.NET SDK Reference](https://developers.sinch.com/docs/voice/sdk/dotnet/syntax-reference.md)\n- [Voice Tutorials](https://developers.sinch.com/docs/voice/tutorials.md)\n- [LLMs.txt (full docs index)](https://developers.sinch.com/llms.txt)\n"
}