How to build a Gulf Arabic voice agent with Vapi

An Arabic voice agent has to do two things most voice stacks cannot: understand a caller from Dubai or Riyadh speaking dialect over a phone line, and answer in a voice that sounds like it belongs in the Gulf. This guide shows how to wire both halves of a Vapi assistant to nutq, and what to watch for once it is taking real calls.

Why do Arabic voice agents usually fail?

The weak link is usually hearing, not the language model. Deepgram, the default transcriber on most voice platforms, has no dedicated Arabic model: nova-2 and nova-3 reject ar outright, and only its multilingual mode accepts it — which mistakes Gulf Arabic for other languages. An agent that cannot hear the caller cannot help them, however good its prompt is.

The other end fails more quietly: a broadcast-MSA voice answering a Gulf caller sounds like a government recording, not a conversation.

How do you connect the listening half?

Vapi opens a WebSocket and streams the call through it; nutq returns each turn as text when the caller pauses. Add this to the assistant:

"transcriber": {
  "provider": "custom-transcriber",
  "server": {
    "url": "wss://worker.nutq.dev/v1/transcribe/stream?key=$NUTQ_STREAM_KEY&language=auto",
    "timeoutSeconds": 30
  }
}

A WebSocket handshake carries no headers you control, so the key goes on the URL. Use a separate key here, so it can be revoked on its own if a log ever captures it. Check that your Vapi account accepts custom-transcriber before building on it; some accounts reject it at publish time.

With language=auto, the first turn long enough to judge sets the call's language, and short replies inherit it — a caller who just says «نعم» is not re-guessed on one word.

How do you connect the speaking half?

Vapi posts each line its model wants said and plays back the audio you return:

"voice": {
  "provider": "custom-voice",
  "server": {
    "url": "https://nutq.dev/v1/vapi/voice?voice=rashid",
    "headers": { "Authorization": "Bearer $NUTQ_API_KEY" },
    "timeoutSeconds": 45
  }
}

Settings ride on the URL because Vapi owns the request body. Whatever sample rate Vapi asks for — 8000, 16000, 22050 or 24000 Hz — comes back exactly, as mono 16-bit PCM.

How do you keep the conversation natural?

Three rules make the difference between a conversation and a hold queue:

1. Short replies. Each reply is synthesised in full before the caller hears any of it. Tell the model in its system prompt to answer in one or two sentences.
2. Let turns end naturally. A turn ends after about 700 ms of quiet. Pauses mid-sentence are normal and do not split a turn, and anything past 15 seconds is transcribed anyway rather than waiting for a pause that may not come.
3. Write the prompt in the register you want back. If the agent should sound Gulf, give it Gulf examples. The voice reads the text it is given; see Arabic text to speech with voice cloning for how to steer pronunciation.

What does a call cost?

Both are billed to the key in the configuration, and failed requests are not billed. New accounts start with $5 of free credit at sign-up.

What should you test before going live?

• Real callers on real phone lines — narrow-band audio behaves differently; see transcribing Arabic phone calls.
• Callers who switch between Arabic and English mid-call.
• Very short answers («إي», «لا», «تمام») and long complaints.
• Numbers, dates and product names read back to the caller.

You can use either half on its own: nutq for hearing with another voice, or the other way round. The full configuration, including every note above, is in the API reference.