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

# Make an outbound call from the app or the API

> Have your agent call one person: a test call from the app, or a call from your own system through the API with variables for the agent to use.

Your agent can call people as well as answer them. From the app you can place a quick test call. From your own system, one API request starts a call and passes the details the agent needs, such as the customer's name or order number. To call many people at once, use [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md).

## Before you start

* A phone number in your project with a working outbound connection. See [Bring your own number](https://docs.tryhamsa.com/agents/connect/bring-your-own-number.md).
* The number assigned to an agent, or the agent's ID to pass in the request. See [Phone numbers](https://docs.tryhamsa.com/agents/connect/phone-numbers.md).
* Credits: a call needs a balance above zero.
* For the API: a secret key from **API keys**, kept on your server. See [Create API keys](https://docs.tryhamsa.com/overview/create-api-keys.md).

## Call from the app

There are two ways:

| Where | What it does |
| - | - |
| The number's page > **Test outbound call** | Calls the number you enter in **To** with the number's assigned agent. No variables. See [Test a call from a number](https://docs.tryhamsa.com/agents/connect/phone-numbers.md#test-a-call-from-a-number). |
| Agent editor > **Test** > **Phone call** | Calls **Your phone number** with your draft, using the agent's number. You can fill in values for the agent's variables. See [Test your agent](https://docs.tryhamsa.com/agents/release/test-your-agent.md). |

![The Test outbound call dialog on a number's page, with a UAE number in To](https://mintcdn.com/hamsa-452fa79a/2xrN5xxbhCUDZ-2o/images/agents/connect/test-outbound-call-light.webp?fit=max\&auto=format\&n=2xrN5xxbhCUDZ-2o\&q=85\&s=126e9c8374860e1fff1826a1a6dd1899)

## Call from the API

Send a `POST` to `/v1/voice-agents/phone-number/call` with your API key.

**1. Get a key**

On **API keys**, create a key for **Your server**. With **Limited** access, the quick select **Initiate and monitor voice calls only** covers this request. A public key (`pk_…`) can't place phone calls.

**2. Send the request**

```bash theme={null}
curl -X POST https://api.tryhamsa.com/v1/voice-agents/phone-number/call \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+14155550100",
    "toNumber": "+971501234567",
    "voiceAgentId": "8c1d2f3a-5b6e-4c7d-9e8f-0a1b2c3d4e5f",
    "params": {
      "customer_name": "Sara",
      "order_number": "A-1042"
    }
  }'
```

**3. Keep the job ID**

A `201` response means the call is queued:

```json theme={null}
{
  "success": true,
  "message": "success",
  "data": {
    "jobId": "0f9e8d7c-6b5a-4f3e-8d2c-1b0a9f8e7d6c",
    "voiceAgentId": "8c1d2f3a-5b6e-4c7d-9e8f-0a1b2c3d4e5f"
  }
}
```

The `jobId` is the call's ID. It's the `conversationId` in your [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md) and the call's ID in the [Conversation log](https://docs.tryhamsa.com/agents/monitor/conversation-log.md).

### Request fields

| Field | Required | What it does |
| - | - | - |
| `phoneNumber` | Yes | Your Hamsa number to call from, exactly as it's listed on the phone numbers page, for example `+14155550100`. It must be in the same project as the key. |
| `toNumber` | Yes | The number to call. Must start with `+` and the country code. |
| `voiceAgentId` | No | The agent that makes the call. Leave it out to use the agent the number is assigned to. |
| `params` | No | Values for the agent's variables, as key and value pairs. The agent reads them as `{{customer_name}}`. See [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md). |

### Errors

Errors come back with a `message` and a `messageKey`:

```json theme={null}
{
  "code": 8400,
  "message": "To Number must start with a \"+\" sign for country code!",
  "messageKey": "ToNumberMustStartWithPlus"
}
```

| Message | Why |
| - | - |
| "To Number must start with a "+" sign for country code!" | `toNumber` is missing its `+` and country code. |
| "The phone number does not exist for the user!" | `phoneNumber` isn't a number in this project, or is written differently. |
| "Voice Agent does not exist" | The number has no agent and you sent no `voiceAgentId`, or the ID is wrong. |
| "Balance is insufficient, please renew or upgrade your plan!" | The project is out of credits. See [Billing](https://docs.tryhamsa.com/overview/billing.md). |
| "Bearer token Authorization header is deprecated!" | Send `Authorization: Token YOUR_API_KEY`, not `Bearer`. |

## How the call goes

1. The request is accepted and the call is queued. If your account already has as many calls running as your plan allows, the call waits and tries again every 30 seconds, for up to an hour. If no slot frees up in that time, the call isn't placed: it ends as **Failed** with the error "Concurrency limit reached: no concurrency slot became free within 60 minutes, so the call was not placed." The limit is never exceeded. The agent never starts, so no webhook is sent for it.
2. Hamsa dials `toNumber` from your number. The agent doesn't start until someone answers.
3. When the person answers, the agent joins and speaks its greeting. The [maximum call length](https://docs.tryhamsa.com/agents/settings/call-behavior.md) counts from this moment.
4. If nobody answers, the line is busy or the call is declined, the call ends as **No answer**. Other dialing errors end it as **Failed**. Either way, your [webhook](https://docs.tryhamsa.com/agents/connect/webhooks.md) gets a `no_answer` or `error` event.
5. When an answered call ends, the webhook gets `call_end` with the transcript and outcome.

### Which version calls

API calls run what prod runs. If prod runs an [A/B test](https://docs.tryhamsa.com/agents/release/ab-tests.md), the number you call decides the version, so the same person keeps hearing the same version. You can't choose an environment for an API phone call.

### Values the agent receives

The agent's variables are filled in this order, and a later source wins for the same name:

1. The default values of the agent's variables.
2. The agent's own default parameters.
3. The `params` in your request.

Values set in the [environment](https://docs.tryhamsa.com/agents/variables/environment-variables.md) for prod still win over `params` with the same name.

A variable the agent uses but nobody filled in is empty on the call.

## Good to know

* Variables use double braces: `{{customer_name}}`, not `{customer_name}`.
* The call record shows the from number and the number called.
* To call many people with their own values, upload a list in [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md) instead of looping over this request.

## Related

> [card] [Batch calls](https://docs.tryhamsa.com/agents/connect/batch-calls.md)
>
> Call a list with a schedule, concurrency and retries.

> [card] [Webhooks](https://docs.tryhamsa.com/agents/connect/webhooks.md)
>
> Get the transcript and outcome when the call ends.

> [card] [Pass values when a call starts](https://docs.tryhamsa.com/agents/variables/dynamic-variables.md)
>
> Use params in prompts and messages.

> [card] [Create API keys](https://docs.tryhamsa.com/overview/create-api-keys.md)
>
> Public and secret keys, and what each can do.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.