For the complete documentation index, see llms.txt. This page is also available as Markdown.

Troubleshooting

Troubleshooting

Error 31202 — authentication failed

The access token was signed with the wrong credentials. Twilio Voice access tokens must be signed with an API Key SID (SK…) and its Secret, not your Account Auth Token. Re-create an API key (Getting Started › Create an API key) and set TWILIO_API_KEY / TWILIO_API_SECRET in your token function.

No audio / microphone not working

  • The browser must grant microphone permission. Check the Mic access status state (granted, denied, prompt) and prompt the user to allow the mic.

  • Calls require HTTPS. Make sure your app is served over https://.

  • See Audio Device Selection if the wrong microphone or speaker is being used.

Calls drop after ~1 hour / token expired

Access tokens have a limited lifetime (default 3600s). Listen for the Token Expiring event and run the Update token action (or refresh the token state for subaccounts) to keep the session alive. See Subaccounts › Refreshing Client Tokens.

Incoming calls don't ring

  • The device must be registered, and the token's incoming grant must be enabled.

  • Your Twilio number must route to the client identity that matches the Agent Identifier (see Receiving Calls).

  • If Auto Reject is enabled, calls are rejected while the user is on another call — the Auto Rejected Call event fires instead.

Outgoing caller ID is wrong

Set Caller Number on the Start Call action and make sure your Twilio voice function uses event.appCallerId (not context.CALLER_ID) when you use multiple numbers. See Getting Started.