---
title: How calls work for your agent | API Docs
description: The pieces of a call, what Linq decides and what you decide, and the logic to build around calls to your agent.
---

This page is for a business that runs its own voice agent on its own Linq numbers. It explains how the pieces fit together, which parts of a call Linq handles, and which parts are yours to decide. For the setup steps, start with the [Quickstart](/channel/voice/getting-started/quickstart/index.md).

## The pieces

```
caller ──► your Linq number ──► its SIP profile ──► your agent
                  │
                  └── Linq keeps a call record and sends call events to your webhook
```

- **Your Linq number** is the number people call. The same number can also [send messages](/channel/imessage/guides/messaging/sending-messages/index.md).
- **A SIP profile** tells Linq where to send the number’s calls: a primary URI and, optionally, a backup URI.
- **Your agent** is the SIP endpoint, or your voice-agent platform’s SIP address, that answers the call.
- **The call record and call events.** Linq can send a webhook when a call rings, when it’s answered and when it ends, and keeps a record of the call. Both use the same `id`.

A number has at most one profile, and one profile can serve many numbers. When you assign, move or clear a number’s profile, or change a profile’s URI, allow about 5 minutes before test calls reach the new endpoint. Calls already in progress keep going where they started.

### When you use each request

| You want to                                       | Request                                                                                                      | When                                                                                                                |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
| Tell Linq where your agent answers                | Create a profile: `POST /v3/sip-profiles`                                                                    | Once per agent: one SIP URI per agent. Reuse the profile for every number that agent answers.                       |
| Bring a number into voice                         | Assign the profile: `PUT /v3/phone-numbers/{phoneNumber}/sip-profile`                                        | Once per number. Allow about 5 minutes before test calls arrive.                                                    |
| Send a number to a different agent                | Assign that agent’s profile: `PUT /v3/phone-numbers/{phoneNumber}/sip-profile`                               | When you want it. Allow about 5 minutes before calls go to the new agent.                                           |
| Move your agent to a new address                  | Update the profile’s URI: `PUT /v3/sip-profiles/{sipProfileId}`                                              | When your agent moves. Allow about 5 minutes before calls reach the new address. Calls in progress aren’t affected. |
| Stop taking calls on a number                     | Clear the assignment: assign `null`                                                                          | When you stop. Allow about 5 minutes before Linq stops sending the number’s calls to your agent.                    |
| See call history, or reconcile with your own logs | List calls: `GET /v3/phone-numbers/{phoneNumber}/call-voice`, or get one: `GET /v3/call-voice/{callVoiceId}` | As often as you need.                                                                                               |
| Update your own systems as calls happen           | Subscribe to call events: `POST /v3/webhook-subscriptions`                                                   | Once.                                                                                                               |

[Connect your SIP endpoint](/channel/voice/getting-started/connect-your-sip-endpoint/index.md) has the full request for each one.

## What happens on a call, and who decides

### Linq decides

- **Where the call goes:** to the profile assigned to the number that was dialled.
- **How long to wait:** your endpoint has 3 seconds to reply to the INVITE (the SIP request that starts the call), then up to 30 seconds to answer with `200`. You can’t change the ring time through the API.
- **One failover:** if your primary doesn’t reply, doesn’t answer in time, or returns `408` or a `5xx`, Linq tries your backup once.
- **The longest call:** 4 hours. Linq then hangs up both sides.
- **The outcome:** Linq classifies how each call ended; see [Call outcomes](/channel/voice/getting-started/connect-your-sip-endpoint#call-outcomes/index.md).

### You decide: your answer

Your endpoint’s reply to the INVITE is how you tell Linq what you want to happen to the call. On a hosted voice-agent platform, the platform sends these replies for you; check which ones it lets you control.

| Your answer                                  | What it means                        | What happens                                                | Event / status                                                             |
| -------------------------------------------- | ------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------------------------------- |
| `200 OK`                                     | I’ll take the call.                  | Your agent is on the call.                                  | `call_voice.answered`, then `call_voice.ended` / `completed`               |
| `486` or `603`                               | I’m busy, or I won’t take this call. | The call ends. Linq doesn’t try your backup.                | `call_voice.declined` / `busy`                                             |
| `503`                                        | Send it to my backup.                | Linq tries your backup once. With no backup, the call ends. | The backup’s outcome; with no backup, `call_voice.failed` / `failed`       |
| No reply in 3 s, no answer in 30 s, or `408` | My agent didn’t answer in time.      | Linq tries your backup once. With no backup, the call ends. | The backup’s outcome; with no backup, `call_voice.no_answer` / `no_answer` |

Other replies:

- Any other `5xx` works like `503`.
- `480` ends the call as no answer and `600` as busy, without trying your backup; `487` ends it as canceled.
- Any other `4xx` or `6xx`, such as `404` or `488`, ends the call as `call_voice.failed` / `failed`, with no failover.
- Don’t challenge Linq’s INVITE with `401` or `407`: that fails the call too.

When your agent is full, reply `486`, or `503` if you have a backup. With no backup, `503` ends the call as `failed`.

Events and call records don’t include the SIP code you returned, so keep it in your own logs.

## Logic you’ll build

Linq doesn’t screen callers for you: there are no opening hours, per-caller limits or block lists. Every call it can route to your number goes to your agent. Start with the simple default in each section below, and add more when you need it.

### Screening before you answer

Simple default: answer every call to your numbers.

Next step: before you answer, check the Request-URI user part (the part before `@` in the INVITE). Linq sets it to the called number. If it isn’t one of your numbers, reject the call with a `404`. Anyone can point a SIP profile at your address, so a call from Linq isn’t necessarily for you. This check filters out misrouted calls, but it doesn’t prove the call comes from your Linq account; see [Protect your endpoint](/channel/voice/getting-started/connect-your-sip-endpoint#protect-your-endpoint/index.md). A hosted platform that routes on the called number already does this check.

When you need more, decide before you answer: opening hours, a limit per caller number (it can be spoofed or hidden; see [Caller identity](#caller-identity)), allow or block lists, and what to do with callers who hide their number. To give the caller a message, such as your opening hours, answer with `200` and have your agent say it. `486` or `603` turns the call away without one.

### How a call ends

The caller usually hangs up, and Linq relays the caller’s `BYE` to your endpoint. Plan how your agent wraps up a call: for example, a limit on call length, after which your agent says goodbye. Linq’s 4-hour limit is a backstop, not a policy. Your voice platform may end calls sooner. For example, OpenAI’s Live API ends connected calls after 2 hours.

### Caller identity

Caller ID can be spoofed, and some callers hide their number. Don’t use the caller’s number to identify or authenticate a caller, and plan for calls with no usable number. The caller is in the `From` header and in each event’s `from`. Don’t assume a format: normalize the number before you store or reuse it.

### Events

You don’t need events to answer calls; they’re for your own records.

- The events that end a call are `call_voice.ended`, `call_voice.declined`, `call_voice.no_answer` and `call_voice.failed`.
- Treat the event that ends the call, or the call record, as the call’s outcome.
- Dedupe on `event_id`.
- Events can arrive late, twice, out of order, or not at all.
- When you’re missing an event or unsure of an outcome, read the call record with `GET /v3/call-voice/{callVoiceId}`.

### Matching your call to Linq’s record

Linq adds an `X-Linq-Call-Id` header to every INVITE it sends to your endpoint. Its value is the call’s `id`: the `id` of the call record and the `data.id` in each call event. Save it with your call, then use it to read the record with `GET /v3/call-voice/{callVoiceId}` and to match call events to your call.

```
X-Linq-Call-Id: 00000000-0000-0000-0000-000000000000
```

## Checklist

### Minimum to go live

- [ ] A SIP profile assigned to your number, and a test call your agent answers.
- [ ] Your firewall allows [Linq’s addresses](/channel/voice/getting-started/connect-your-sip-endpoint#allow-linqs-addresses/index.md), and your endpoint doesn’t challenge Linq’s INVITEs with `401` or `407`.
- [ ] Your certificate is valid for the host in your URI.
- [ ] If your platform routes on the called number, your Linq number is added there.
- [ ] A plan for when your agent can’t answer: `486` when it’s full, or a backup URI and `503`.

### What you’ll want later

- [ ] Call events: subscribe, and dedupe them on `event_id`.
- [ ] A [backup URI](/channel/voice/getting-started/connect-your-sip-endpoint#add-a-backup-endpoint-failover/index.md), and `503` from your primary when it’s down for maintenance.
- [ ] Screening: a check of the called number, opening hours, limits per caller number, callers who hide their number.
- [ ] A wrap-up plan: a call-length limit, after which your agent says goodbye.
- [ ] Store the `X-Linq-Call-Id` of each call with your call.
- [ ] Reconciliation: list your calls and match them to your own logs by `id`.

## Next steps

- [Quickstart](/channel/voice/getting-started/quickstart/index.md): route your first call.
- [Connect your SIP endpoint](/channel/voice/getting-started/connect-your-sip-endpoint/index.md): every setting, plus [call outcomes](/channel/voice/getting-started/connect-your-sip-endpoint#call-outcomes/index.md).
- [Webhooks guide](/channel/imessage/guides/webhooks/index.md)
