Skip to main content

Production Best Practices

Going from “it works on my machine” to “it works for all users, reliably” requires addressing security, reliability, performance, and monitoring. This guide covers the key areas.

Authentication

Use JWT in production

JWTs are time-limited, revocable, and don’t expose passwords. See Authenticating Your App.

Generate JWTs on your backend

Handle token refresh

One credential per user

Never share a Telephony Credential across multiple users. Each user must have their own JWT to ensure they receive their own incoming calls.

Connection Management

One client instance per tab

Clean up on page unload

By default (hangupOnBeforeUnload: true), the SDK hangs up active calls and sends BYE on beforeunload:
If your app keeps calls alive across page reloads (e.g., SPA navigation, soft reload), set hangupOnBeforeUnload: false to prevent the SDK from hanging up on unload. The SDK then flushes an intermediate call report on visibilitychange → hidden via keepalive so no call report data is lost:
When hangupOnBeforeUnload: false, the SDK flushes a final call report on visibilitychange → hidden (the last reliably observable event on desktop and mobile) using keepalive so the report is not lost when the page tears down. Available since SDK v2.27.4.

Handle reconnection gracefully

See Handle Reconnection for the full guide.

Audio Quality

Request microphone with constraints

If you need to control the microphone before making a call:

Monitor call quality

Enable call reports in production:
Set up quality alerts:

Recommend headphones for agents

Built-in speakers + microphone create echo. For call center agents, recommend USB headsets or enforce echo cancellation.

Network Configuration

Allowlist Telnyx domains

Ensure your firewall allows:

Don’t force relay unless necessary

Forcing relay adds 20-80ms latency per direction. Use it only when corporate policy requires all media to go through a relay. See Configure Network & Firewall for the full guide.

Error Handling

Always handle errors

Handle connection failures

Don’t show raw errors to users


Memory Management

Clean up call references

Remove event listeners


Monitoring & Observability

Enable call reports

Track key metrics

Log quality issues server-side


Deployment Checklist


See Also