FAQ & troubleshooting

FAQ & troubleshooting

Quick answers to common questions. If something here doesn't resolve your issue, use the Feedback button at the bottom‑right of any dashboard page to report a bug or send feedback (see below).

Getting started

How do I get an API key?

In the dashboard go to Developers → API keys → Create key and copy the secret (shown once). It's organization‑scoped — see Authentication.

Do I need a phone number to try an agent?

No. Use Test call on the agent page (browser voice), or the web‑call API. Phone numbers are only needed for PSTN calls.

Is there an SDK?

Yes — official SDKs for web & React, React Native, and Node & Python backends; Rust or any other language can use the plain REST API. They handle the audio pipeline (mic, echo/noise, jitter buffering, barge-in, reconnect) so you only build UI. The API itself stays plain REST + JSON, so any HTTP client also works; for a zero-code option, embed the widget.

What are the valid model / voice identifiers?

Fetch GET /api/catalog — it lists every provider, model, and voice you can use. See Catalog & providers.

Can I text‑chat with an agent instead of calling it?

Yes. Every agent also works as a text chat agent — same prompt, knowledge, and tools, replying in text. It powers the chat mode of the public widget, and you can drive it programmatically with POST /api/v1/chat. See Chat API.

How does prepaid billing work?

If your workspace is prepaid, it runs on purchased credits (1 credit = ₹1, converted to your currency) and calls are blocked once the balance reaches zero. Top up under Billing → Buy credits. Postpaid workspaces run a balance that's invoiced monthly instead. See Usage & billing.

Reporting a bug or giving feedback

How do I report a bug or suggest something?

Every dashboard page has a Feedback button pinned to the bottom‑right corner. Click it, choose Bug or Feedback, describe what happened (for a bug: what you did, what you expected, and what happened instead), and optionally attach up to 3 screenshots or videos (images and videos only, 25 MB each). Click Send report — that's it; the report goes straight to the Telenow team with the page URL and your browser details automatically.

Something broke and I saw a "Report this bug" prompt.

When an unexpected error occurs, Telenow shows a toast (or a full‑page fallback) with a Report this bug action. Clicking it opens the same Feedback form pre‑filled with the error details, which are attached to your report — so the quickest way to get a crash fixed is to click it and add a sentence about what you were doing.

Authentication

API key vs. user JWT — which do I use?

Use an API key for server‑to‑server integrations (no org header needed). Use a user JWT to act as a signed‑in user (pass X-Org-Id). See Authentication.

I get 401 with code: token_expired.

Your access token expired — call POST /api/auth/refresh with the refresh token to get a new pair. token_invalid means re‑login.

I get 403 Forbidden on an org route.

Either the authenticated user isn't a member of that organization, your role lacks permission, or a usage quota was hit. Check X-Org-Id and the member's role.

Calls & audio

A web call connects but there's no audio.

Audio frames must be base64‑encoded μ‑law, 8 kHz, mono, sent as media events, and you must send start first. See the Web‑call protocol. If you'd rather not implement the codec, use the widget.

Outbound calls aren't connecting.

Confirm the number is assigned to the agent, any required compliance is approved, and (for BYOC) your carrier credentials are valid. Check the call's status in call history.

Recording URLs are signed and short‑lived. Request a fresh one with GET /api/orgs/{orgId}/recordings/{id}/signed-url and use it immediately — don't store the URL.

Calls hang open when the caller goes silent.

Turn on Hang up on silence in the agent builder: the agent ends the call after a number of seconds of continuous caller silence (set it to 0/leave it off to keep the legacy behaviour, where the watchdog only re‑prompts). You can also set a short goodbye line spoken just before it hangs up; if you leave that blank a built‑in line is used. See Building agents.

Webhooks

My endpoint isn't receiving events.

Check that: the endpoint is enabled, its events includes the event (or "*"), and its agent_id matches the call's agent (or is null for org‑wide). Inspect attempts at GET /api/orgs/{orgId}/webhooks/{id}/deliveries. See Webhook management.

Signature verification fails.

Verify the HMAC over the raw request body (not a re‑serialized object), using the endpoint's signing secret, and compare to the hex after sha256= in X-VoiceAI-Signature. Full examples in Receive & verify webhooks.

I'm getting duplicate events.

Retries reuse the X-VoiceAI-Delivery id — de‑duplicate on it. Acknowledge with a 2xx quickly so Telenow doesn't retry a slow handler.

Widget & embedding

The widget won't start on my site.

If you set Allowed origins, your site's origin must be in the list (an empty list allows any). Confirm the data-slug matches your published agent. See Embed the widget.

Can I fully customize the widget UI?

Yes — start sessions from your backend and drive the WebSocket yourself. See Programmatic web calls.

Limits

I'm getting 429 Too Many Requests.

You hit a rate limit. Back off for the retryAfter seconds in the response. Limits: 1000 req / 15 min per IP on /api; public widget session‑init is 10 / 60 s per slug + IP. See Overview.

Calls are rejected with a quota error.

Your organization reached a monthly or concurrency limit. Review Usage & billing or raise limits via PUT /api/orgs/{orgId}/usage/limits.