> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upliftai.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Tabs>
  <Tab title="Portal">
    <Steps>
      <Step title="Create an agent">
        Open [upliftai.org/app/calling](https://upliftai.org/app/calling) and click **Create an Agent**.

        <Frame>
          <img src="https://mintcdn.com/upliftai/ui9MmnBHgCyjZxZD/images/voice-agents/quickstart/create-agent.png?fit=max&auto=format&n=ui9MmnBHgCyjZxZD&q=85&s=afcd03a204d42f4be02e183dbb81010b" alt="The calling home page with the Create an Agent button highlighted" width="994" data-path="images/voice-agents/quickstart/create-agent.png" />
        </Frame>
      </Step>

      <Step title="Pick your industry and use case">
        Choose the closest match on both screens. We tailor the agent's setup from here.

        <Columns cols={2}>
          <Frame>
            <img src="https://mintcdn.com/upliftai/ui9MmnBHgCyjZxZD/images/voice-agents/quickstart/pick-industry.png?fit=max&auto=format&n=ui9MmnBHgCyjZxZD&q=85&s=9981d317eb58404fe425fd8296cdfe2f" alt="The industry picker with Retail & E-commerce selected" width="580" data-path="images/voice-agents/quickstart/pick-industry.png" />
          </Frame>

          <Frame>
            <img src="https://mintcdn.com/upliftai/ui9MmnBHgCyjZxZD/images/voice-agents/quickstart/pick-use-case.png?fit=max&auto=format&n=ui9MmnBHgCyjZxZD&q=85&s=69d31e0afcc2842d2db37d4e748fe3ea" alt="The use case picker with Lead Qualification selected" width="580" data-path="images/voice-agents/quickstart/pick-use-case.png" />
          </Frame>
        </Columns>
      </Step>

      <Step title="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**.

        <Frame>
          <img src="https://mintcdn.com/upliftai/ui9MmnBHgCyjZxZD/images/voice-agents/quickstart/describe-agent.png?fit=max&auto=format&n=ui9MmnBHgCyjZxZD&q=85&s=a561b767305195fe3ee92d8040c9aab1" alt="The agent form with a heater lead qualification goal, Check Goal Clarity and Create agent highlighted" width="480" data-path="images/voice-agents/quickstart/describe-agent.png" />
        </Frame>

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

      <Step title="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.

        <Frame>
          <img src="https://mintcdn.com/upliftai/ui9MmnBHgCyjZxZD/images/voice-agents/quickstart/call-your-phone.gif?s=a5c39f0f90de10ec9992915f5820b3e4" alt="Clicking the phone button, typing a number, then clicking Call Now" width="852" data-path="images/voice-agents/quickstart/call-your-phone.gif" />
        </Frame>
      </Step>
    </Steps>
  </Tab>

  <Tab title="API">
    You need an API key. Make one on the [API keys page](https://upliftai.org/app/developer/api-keys), then:

    ```bash theme={null}
    export UPLIFT_API_KEY=your-key
    ```

    Already made an assistant in [Quickstart: Web](/voice-agents/getting-started/quickstart-web)? Export its id as `ASSISTANT_ID` and skip to step 2.

    <Steps>
      <Step title="Create the assistant">
        [Create an assistant](/api-reference/assistants/create-an-assistant) with a prompt and a voice:

        ```bash theme={null}
        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](/orator_voices).

        Copy `realtimeAssistantId` from the response:

        ```bash theme={null}
        export ASSISTANT_ID=your-assistant-id
        ```
      </Step>

      <Step title="Call your phone">
        [Dispatch a call](/api-reference/starting-a-conversation/dispatch-a-call-from-this-assistant) with your own number. `+923001234567` and `03001234567` both work.

        ```bash theme={null}
        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" }'
        ```

        ```json Response theme={null}
        {
          "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.
      </Step>

      <Step title="Read what happened">
        The `callId` is the call's **session id**. Export it, then [get the session's status](/api-reference/sessions-%26-call-records/get-a-sessions-status) to see how it went:

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

        ```json A 40-second call you picked up, trimmed theme={null}
        {
          "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](/voice-agents/calling/session-details), a few seconds after you hang up.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 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](/voice-agents/concepts/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](/voice-agents/concepts/phone-call-states) lists them all.

## What next

* **Personalize the call.** Pass each customer's details on the dial — see [Per-call instructions](/voice-agents/personalization/per-call-instructions).
* **Call a whole list.** A [campaign](/voice-agents/campaigns/getting-started) dials everyone, retries, and hands back results per person.
* **Write a better prompt.** [Voice prompting](/voice-agents/assistants/voice-prompting) covers what works on a call. Or [build from a brief](/voice-agents/assistants/build-refine-simulate) and we write the Urdu prompt for you.
* **Get results pushed to you.** [Webhooks](/voice-agents/webhooks/overview) send the transcript and grade as each call finishes.