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

# Take and make phone calls with your agent

> Connect a Twilio number to a Builder agent so it answers the calls that come in, and let it dial out from the Builder or from the API.

Once a number from your Twilio account is connected to an agent, that agent **answers every call to the number** and can **dial out from it**. Nothing else to configure in Twilio: Ryvo points the number at your agent for you.

<Info>
  This guide is for agents made in the **Builder**. If you do not have a number in Ryvo yet, start with [Connect your Twilio number](/guides/phone-numbers/import-your-twilio-number).
</Info>

## What you need

1. A **Twilio number** imported in **Phone numbers**.
2. A **published** agent. Calls always use the published version, never the draft you are editing.
3. A **payment method** saved and **credits** in your account. Calls are billed like any other conversation of the agent.

## Connect the number to the agent

<Steps>
  <Step title="Open the agent in the Builder">
    From **Agents**, open the agent and go to the **Channels** tab.
  </Step>

  <Step title="Choose the number">
    On the **Voice** card, pick one of your free numbers under **Choose a number** and click **Connect number**.
  </Step>

  <Step title="Done">
    The card turns **Connected** and says which number it answers on. You can also do it from **Phone numbers**, with the **Assign agent** picker of each row.
  </Step>
</Steps>

<Frame caption="The Voice card in the Builder's Channels tab, with a connected number.">
  <img src="https://mintcdn.com/ryvo-3dab4d1a/04C-GHMZKu_s8s6d/images/portal/canal-telefono.png?fit=max&auto=format&n=04C-GHMZKu_s8s6d&q=85&s=653ec2b52b8e41f0fe2b421678e8fd6c" alt="The Twilio Voice card marked Connected, with Release number and Start call" width="710" height="592" data-path="images/portal/canal-telefono.png" />
</Frame>

### What Ryvo changes in your Twilio account

When you connect the number, Ryvo sets its **voice webhook** in Twilio so incoming calls reach your agent, and **saves the previous setting**. If you release the number (**Release number**) or delete it from Ryvo, the previous setting is restored. Ryvo does not touch anything else in your account.

<Warning>
  If the number was routing calls to a PBX or another flow, that stops the moment you connect it to an agent. Use a dedicated number, or release it to go back to the previous routing.
</Warning>

## Incoming calls

Anyone who dials the number talks to your agent. The agent greets first with its first message and the conversation follows its instructions, knowledge and tools, the same as in the Builder test.

If the agent cannot take the call, the caller hears a short message in the agent's language and the call ends. It happens when:

* the agent is **paused** or has **no published version**;
* the account has **no credits** or no payment method;
* the account reached its **concurrent calls** limit.

The caller never hears the reason. You see it in **Logs**.

## Outgoing calls

### From the Builder

On the same **Voice** card, type the number to call in **Destination Number** (E.164 format, for example `+13055550142`) and click **Start call**. The agent dials from its connected number with its published version.

<Frame caption="Destination Number and Start call.">
  <img src="https://mintcdn.com/ryvo-3dab4d1a/04C-GHMZKu_s8s6d/images/portal/llamar-desde-el-constructor.png?fit=max&auto=format&n=04C-GHMZKu_s8s6d&q=85&s=530bb5a4d99a56ec115b245871d59189" alt="The Destination Number field and the Start call button" width="710" height="246" data-path="images/portal/llamar-desde-el-constructor.png" />
</Frame>

The button stays off, with the reason next to it, while the agent has no number or is not published.

### From the API

`POST /v1/calls` accepts the id of a Builder agent. The call leaves from the number connected to that agent, or from the one you send in `from` if it is also connected to it.

```bash theme={null}
curl -X POST https://api.ryvo.so/v1/calls \
  -H "Authorization: Bearer ryvo_live_..." \
  -H "Idempotency-Key: lead-8842" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "b326e44f-9750-4315-8c67-54315a4fdf6f", "to": "+13055550142"}'
```

The response carries `"runtime": "engine"` and the call `id`. Full details in the [API reference](/api-reference/calls/trigger-an-outbound-call).

## Calls nobody answers

If the other side does not pick up, is busy or the call fails, Twilio tells Ryvo right away and the call closes within seconds. **It is not billed** and it does not use your account's capacity.

## Where you see your calls

Every call shows up in **Calls** with its number, its direction (incoming or outgoing), duration, transcript and cost. In the API, `GET /v1/calls` returns them with `channel: "phone"` and `direction`.

## Who charges you what

| Item | Who charges it |
| - | - |
| The number and the line minutes | **Twilio**, in your account |
| The agent: voice, model and transcription | **Ryvo**, in [credits](/guides/billing/credits-and-charges), the same per minute as a voice call in the browser |

## Common errors

| Message | What it means and what to do |
| - | - |
| «Connect a number to this agent so it can place calls» | The agent has no number. Connect one on the Voice card. |
| «Publish the agent to place calls with it» | Calls use the published version. Publish the agent. |
| «The destination number must be in E.164 format» | Missing `+` or country code, or it has spaces or dashes. |
| The number is not in your Twilio account | You imported a number that belongs to another account. Import it with the credentials of the account that owns it. |
| The number is already connected in Ryvo | The number is already in Ryvo. Look for it in **Phone numbers**. |
| API `409 no_phone_number` / `409 agent_not_published` | The same two cases, from the API. |