Quickstart: Phone

Have your own voice agent call your phone, in about a minute. You write the prompt and give us your number. We dial from a Pakistani number.

Portal
API

Create an agent

Open upliftai.org/app/calling and click Create an Agent.

Pick your industry and use case

Choose the closest match on both screens. We tailor the agent’s setup from here.

The industry picker with Retail & E-commerce selected

The use case picker with Lead Qualification selected

Describe the call

Name the agent and write the goal: what the call is for, the facts to pitch, and what the agent must not do. Click Check Goal Clarity, then Create agent.

The agent form with a heater lead qualification goal, Check Goal Clarity and Create agent highlighted

We write the Urdu prompt and pick the voice and models for you. It takes a minute or two.

Call your phone

Click the phone button next to Test in Browser, enter your number, and click Call Now. Your phone rings in a few seconds.

Clicking the phone button, typing a number, then clicking Call Now

You need an API key. Make one on the API keys page, then:

export UPLIFT_API_KEY=your-key

Already made an assistant in Quickstart: Web? Export its id as ASSISTANT_ID and skip to step 2.

Create the assistant

Create an assistant with a prompt and a voice:

curl -X POST https://api.upliftai.org/v1/realtime-assistants \
  -H "Authorization: Bearer $UPLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sukoon Heaters lead qualification",
    "config": {
      "agent": {
        "instructions": "آپ سکون ہیٹرز کی جانب سے کال کر رہے ہیں۔ ہمارے نئے الیکٹرک ہیٹر کے بارے میں بتائیں: قیمت 10,000 روپے، مکمل بجلی پر چلتا ہے اس لیے سردیوں میں گیس کی کمی سے فرق نہیں پڑتا، اور بیٹری بیک اپ کی وجہ سے لوڈ شیڈنگ میں بھی چلتا رہتا ہے۔ پوچھیں کہ کیا وہ ہمارے ہیٹنگ ایکسپرٹ سے بات کرنا چاہیں گے جو انہیں صحیح سائز بتائیں گے۔ سیل بند کرنے یا پیمنٹ لینے کی کوشش نہ کریں۔ صرف نستعلیق اردو میں جواب دیں۔",
        "initialGreeting": true
      },
      "stt": { "default": { "provider": "soniox", "model": "stt-rt-v4", "language": "ur" } },
      "tts": { "default": { "provider": "upliftai", "voiceId": "helpdesk-agent" } },
      "llm": { "default": { "provider": "google", "model": "gemini-2.5-flash" } }
    }
  }'

What’s in there:

instructions is the prompt. This one says: you’re calling for Sukoon Heaters about their new electric heater. It costs 10,000 rupees, runs fully on electricity so winter gas shortages don’t matter, and a battery backup keeps it on through load shedding. Ask if they’d like to talk to a heating expert who’ll work out the right size. Don’t try to close the sale or take payment. The last line asks for Nastaliq Urdu, which is what our voices read best. So speak Urdu to it.
initialGreeting: true makes the agent open the call. Pick up and it greets you within a couple of seconds. Say hello first and it answers you.
stt, llm and tts pick the models. Soniox hears Urdu, Gemini 2.5 Flash is the fastest we run, and helpdesk-agent is a warm customer-service voice. Swap in any voice from the voices gallery.

Copy realtimeAssistantId from the response:

export ASSISTANT_ID=your-assistant-id

Call your phone

Dispatch a call with your own number. +923001234567 and 03001234567 both work.

curl -X POST https://api.upliftai.org/v1/realtime-assistants/$ASSISTANT_ID/call \
  -H "Authorization: Bearer $UPLIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toNumber": "+923001234567" }'

Response

{
  "callId": "7c3f9a02-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "externalRef": "AD_xxxxxxxxxxxx",
  "status": "dispatched"
}

Your phone rings in a few seconds. Pick up, and the agent takes it from there. dispatched only means we accepted the call and started dialing, not that it rang or anyone answered.

Read what happened

The callId is the call’s session id. Export it, then get the session’s status to see how it went:

export CALL_ID=your-call-id
curl https://api.upliftai.org/v1/realtime-assistants/sessions/$CALL_ID \
  -H "Authorization: Bearer $UPLIFT_API_KEY"

A 40-second call you picked up, trimmed

{
  "sessionId": "7c3f9a02-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "channel": "telephony",
  "direction": "outbound",
  "state": "completed",
  "connected": true,
  "toNumber": "+923001234567",
  "fromNumber": "04232460612",
  "createdAt": "2026-08-16T18:55:22.677Z",
  "ringingAt": "2026-08-16T18:55:30.758Z",
  "connectedAt": "2026-08-16T18:55:36.927Z",
  "answeredAt": "2026-08-16T18:55:37.641Z",
  "endedAt": "2026-08-16T18:56:17.411Z",
  "durationSec": 40
}

The transcript and the recording are on the session detail, a few seconds after you hang up.

If your phone doesn’t ring

Out of credits comes back as a 402, and nothing is dialed. Every account starts with 10 free minutes — see Pricing.
One call at a time is the default. Dial your number again while the first call is still up and you get a 409 number_busy. A dial to another number gets a 429. Wait for the first to end.
No answer, busy, or unreachable shows up on the session status as failureReason. Phone call states lists them all.

What next

Personalize the call. Pass each customer’s details on the dial — see Per-call instructions.
Call a whole list. A campaign dials everyone, retries, and hands back results per person.
Write a better prompt. Voice prompting covers what works on a call. Or build from a brief and we write the Urdu prompt for you.
Get results pushed to you. Webhooks send the transcript and grade as each call finishes.

Getting started

Concepts

Assistants

Tools

Personalization

Calling

Campaigns

Webhooks

Testing

API Reference

If your phone doesn’t ring

What next

​If your phone doesn’t ring

​What next

If your phone doesn’t ring

What next