Skip to content

docs(sip-telnyx): document Telnyx PCMA/PCMU codec mismatch causing audio corruption - #1219

Draft
Mehayla wants to merge 1 commit into
VapiAI:mainfrom
Mehayla:helpcenter-update/telnyx-sip-pcma-pcmu-codec
Draft

Mehayla wants to merge 1 commit into
VapiAI:mainfrom
Mehayla:helpcenter-update/telnyx-sip-pcma-pcmu-codec

Conversation

@Mehayla

@Mehayla Mehayla commented Sep 14, 2026

Copy link
Copy Markdown

Adds a "Known issues" section to fern/advanced/sip/sip-telnyx.mdx:

## Known issues

- **PCMA/PCMU codec mismatch can corrupt call audio.** Vapi's WebSocket media stream expects G.711 µ-law (PCMU). Some Telnyx trunks, most commonly those carrying European numbers, send inbound audio as G.711 A-law (PCMA) instead. When the codecs don't match, the resulting transcoding can muffle or clip the caller's audio, add clicking artifacts, and fragment speech-to-text transcripts.
  - In the Telnyx portal, check which codec your trunk is configured to send for the affected number (Voice / SIP Trunking / your trunk / codec or media settings).
  - If you can set the trunk's codec preference in Telnyx, set it to PCMU to avoid the transcoding hop entirely.
  - If your number must send PCMA (for example, a European DID where PCMA is the carrier default), contact Vapi support with your affected call IDs and SIP trunk/credential ID so they can confirm whether PCMA passthrough or codec auto-negotiation can be enabled on your media stream.
  <Warning>
    Audio quality symptoms caused by a codec mismatch (muffled or clipped audio, clicking, broken transcripts) look similar to a noisy line, but they don't have a network-loss or jitter cause. Confirm the trunk's codec before troubleshooting network quality.
  </Warning>

@Mehayla

Mehayla commented Sep 14, 2026

Copy link
Copy Markdown
Author

Why this gap, and why now

  • Classification: Incomplete content. fern/advanced/sip/sip-telnyx.mdx (Telnyx SIP integration) and the general sip-trunk.mdx page cover trunk setup end-to-end but never mention codec negotiation. sip-plivo.mdx is the only SIP page with a one-line "Codec Support: G.711 µ-law and A-law only" note, and even that doesn't explain what happens when a trunk's codec doesn't match Vapi's expected PCMU stream.
  • Evidence: In the last 7 days (2026-09-07 to 2026-09-14), at least 6 distinct Plain support tickets independently reported the same symptom on Telnyx SIP trunks: inbound audio muffled/clicking with fragmented STT, traced to Telnyx sending G.711 A-law (PCMA) while Vapi's WebSocket media stream expects G.711 µ-law (PCMU) — forcing a transcoding hop. Most of these were on European numbers, and at least one flagged it as production-blocking ("the restaurant cannot take bookings reliably within 48 hours").
  • Why 🌿 ✨ [Scheduled] Upgrade Fern CLI #1 this week vs. other candidates: SIP Trunks, Phone Numbers, Operation Completion Performance, Uptime & Availability, and Error Prevention & Recovery all rose sharply in share of this week's support/chat/community volume vs. the trailing 4-week baseline. Within SIP Trunks, most other tickets this week were one-off, carrier-specific incidents (a single GlobalNet Italia transfer failure, a single Redworks 403, a single Zadarma 407) — not generalizable content gaps. The PCMA/PCMU mismatch is the one pattern that recurred across multiple distinct customers and multiple distinct carriers/numbers, which is what makes it a documentation gap rather than a one-off support case.
  • What I did not do: No validated verbatim quote came back from the quote-verification tool for these ticket records, so this comment cites the recurring pattern ("N distinct tickets") rather than inventing or paraphrasing a customer quote.
  • Scope of the fix: Kept to a single, additive "Known issues" section on the existing Telnyx page, styled after the "Errors"/"Known Limitations" tables already used on sip-plivo.mdx. No other file or navigation change is needed since this is an edit to an existing, correctly-placed page (not a new page).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant