Copy page

Resources

Troubleshooting

This page covers the most common issues and their resolutions. For each problem, we list the likely causes in order of frequency and the steps to fix them.

Agent Not Answering Calls

The phone rings but the agent does not pick up.

Check in order:

1. Number assignment — the phone number must have an agent_id assigned.

   Code
   curl https://api.neuratel.ai/v1/numbers \
     -H "Authorization: Bearer nk_live_your_api_key"

   If agent_id is null, assign the agent:

   Code
   curl -X POST https://api.neuratel.ai/v1/numbers/num_abc123/assign \
     -H "Authorization: Bearer nk_live_your_api_key" \
     -H "Content-Type: application/json" \
     -d '{"agent_id": "agent_xyz789"}'

2. Agent status — the agent must be active. Check is_active in the agent response:

   Code
   curl https://api.neuratel.ai/v1/agents/agent_xyz789 \
     -H "Authorization: Bearer nk_live_your_api_key"

3. Account balance — if your credit balance is zero, calls are not answered. Check:

   Code
   curl https://api.neuratel.ai/v1/billing/balance \
     -H "Authorization: Bearer nk_live_your_api_key"

4. Trunk status — the number's trunk must show ready. If it shows provisioning, wait a few minutes. If it shows error, contact [email protected].

Poor Transcription Quality

The agent misunderstands the caller frequently.

Solutions:

1. Check the language setting — ensure the transcriber language matches the caller's language. If callers speak multiple languages, use a multilingual model.

   Code
   {
     "transcriber": {
       "provider": "deepgram",
       "model": "nova-3",
       "language": "en-US"
     }
   }

2. Try a different STT model — switch between Deepgram models. nova-3 offers the best accuracy for most use cases.

3. Check audio quality — background noise, speakerphone, or poor cell signal degrade transcription. Consider suggesting callers use a headset in the agent's greeting.

4. Review caller demographics — accented speech may perform better with specific language variants (e.g. en-GB vs en-US).

Voice Sounds Unnatural

The agent's speech sounds robotic, too fast, or not matching expectations.

Solutions:

1. Adjust voice parameters — fine-tune stability and similarity_boost on ElevenLabs voices:

   Code
   {
     "voice": {
       "provider": "elevenlabs",
       "voice_id": "21m00Tcm4TlvDq8ikWAM",
       "stability": 0.5,
       "similarity_boost": 0.75
     }
   }

   Lower stability = more expressive, higher stability = more consistent.

2. Try a different voice — each provider offers multiple voices. Cartesia voices are optimized for low-latency, ElevenLabs for expressiveness.

3. Shorten agent responses — long monologues sound more robotic. Instruct the agent in the system prompt: "Keep responses to 1-2 sentences."

4. Switch TTS provider — if one provider's voices do not work for your use case:

   • Cartesia — ~40ms TTFA latency, natural and fast
   • ElevenLabs — most expressive, widest voice selection
   • Phantom Speech — Neuratel's proprietary, optimized for conversations

Webhook Not Receiving Events

Your server is not getting webhook deliveries.

Check in order:

1. Webhook is active — confirm is_active: true:

   Code
   curl https://api.neuratel.ai/v1/webhooks \
     -H "Authorization: Bearer nk_live_your_api_key"

2. URL is accessible — your endpoint must be publicly reachable from the internet. Test with a curl from an external machine.

3. HTTPS required — Neuratel only delivers to https:// URLs. HTTP endpoints are rejected.

4. Firewall rules — ensure your server accepts inbound POST requests on the webhook port.

5. Check delivery logs — view failed deliveries and error messages:

   Code
   curl "https://api.neuratel.ai/v1/webhooks/wh_abc123/logs?success_only=false" \
     -H "Authorization: Bearer nk_live_your_api_key"

6. Send a test — trigger a test delivery to isolate the issue:

   Code
   curl -X POST https://api.neuratel.ai/v1/webhooks/wh_abc123/test \
     -H "Authorization: Bearer nk_live_your_api_key"

7. Check event subscriptions — confirm you are subscribed to the event types you expect.

High Latency (Slow Agent Responses)

The agent takes too long to respond after the caller finishes speaking.

Solutions:

1. Switch to faster providers:

   • TTS: Cartesia (~37ms) or Phantom Speech for lowest latency
   • STT: Deepgram nova-3 for fastest transcription, or Soniox for native multilingual with semantic EOU
   • LLM: Phantom Brain (~178ms TTFT) or Groq for fastest inference

2. Reduce system prompt length — very long system prompts increase LLM processing time. Keep it focused and concise.

3. Lower temperature — lower temperature values (0.1-0.3) produce faster, more deterministic responses.

4. Optimize MCP tool servers — if the agent calls external tools, ensure those servers respond within 2 seconds. Slow tools block the response pipeline.

5. Check your provider's rate limits — if using BYOK, your provider account may be throttling requests.

Call Drops Unexpectedly

Calls end before the conversation is complete.

Check:

1. Silence timeout — if neither party speaks for the configured duration, the call ends. Increase conversation.silence_timeout_seconds:

   Code
   {
     "conversation": {
       "silence_timeout_seconds": 30
     }
   }

2. Max duration — check conversation.max_duration_seconds. Increase if calls are legitimately long.

3. VAD sensitivity — if the VAD is too aggressive, it may interpret background noise as silence. Adjust the VAD threshold.

4. Account balance — if your balance hits zero mid-call, the call ends. Read your live balance via Usage Visibility; contact your account team for any operational change.

Campaign Not Starting

You click "Start" but the campaign stays in draft status.

Check:

1. Account balance — campaigns require an active credit balance. If you suspect this is the cause, check has_credits via GET /v1/billing/balance and contact your account team if it's false.

2. Contact list — the campaign must have at least one contact. Verify the CSV uploaded successfully:

   Code
   curl https://api.neuratel.ai/v1/campaigns/camp_def456 \
     -H "Authorization: Bearer nk_live_your_api_key"

   Check total_contacts is greater than 0.

3. CSV format — the CSV must have a phone_number column with E.164 formatted numbers (+12125550101). Common errors:

   • Missing + prefix
   • Spaces or dashes in numbers
   • Column named Phone instead of phone_number

4. Agent status — the campaign's agent must be active.

5. Caller ID — the campaign must have a valid caller_id number assigned.

Signature Verification Failing

Your webhook handler rejects legitimate Neuratel deliveries.

Check:

1. Using raw body — compute the HMAC over the raw request body (bytes), not the parsed JSON object. Parsing and re-serializing JSON changes whitespace and key ordering.

2. Correct secret — verify you are using the webhook signing secret from creation, not your API key.

3. Encoding — both the body and secret must be UTF-8.

4. Secret rotated — if you rotated the secret, update your handler with the new value. The old secret is invalidated immediately.

Knowledge Base Not Returning Results

The agent does not reference uploaded documents during calls.

Check:

1. Document status — verify documents are indexed (not still processing):

   Code
   curl https://api.neuratel.ai/v1/knowledge-base \
     -H "Authorization: Bearer nk_live_your_api_key"

   Documents should show status: "indexed".

2. Agent linked to knowledge base — the agent must have the knowledge base ID configured.

3. Query relevance — the caller's question must be semantically similar to content in the documents. Try rephrasing the system prompt to guide the agent to search the knowledge base for specific topics.

Still Stuck?

• Check status: status.neuratel.ai
• Email support: [email protected] — include the request_id from any error responses
• Slack: Enterprise clients have a dedicated support channel

Next Steps

• Error Codes — understand specific API error codes
• FAQ — common questions answered
• Production Checklist — prevent issues before going live