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

# Intercom: peer-to-peer auto-answer (push-to-talk)

> Dial one coworker's extension so their softphone or deskphone answers on speaker instantly — for two-way conversation or push-to-talk announcements.

# Intercom: peer-to-peer auto-answer

The intercom dial is the one-to-one counterpart of a [paging
group](/voice/paging-ring-groups-call-park): instead of broadcasting to
every member of a group, you buzz exactly one extension, and the target's
device answers on speaker automatically. It covers the floor-comms
pattern teams expect from a UCaaS platform — "ask the front desk a
question", "top up a colleague on push-to-talk while they roam".

An intercom dial is an **ephemeral action, not stored config**. There is
no intercom entity to create or manage — each dial is validated, resolved,
and rung on the spot, then audit-logged. Dialling a target you have not
pre-configured anywhere still works as long as the target exists.

## Paging groups (many) vs intercom (one)

|             | Paging group                              | Intercom                                      |
| ----------- | ----------------------------------------- | --------------------------------------------- |
| Reach       | Every member of a named group             | One extension                                 |
| Audio       | One-way broadcast (simplex) by default    | Two-way conversation, or one-way push-to-talk |
| Setup       | Stored group you create and member-manage | None — dial by user or SIP username           |
| Primary use | Announcements to a room or team           | Direct 1:1 buzz between coworkers             |

Both are internal, extension-to-extension calls: they never place an
outbound PSTN call. An intercom dial rings a device registered on your
own SIP realm, end of story.

## Dial an extension

`POST /api/v1/voice/intercom/dial`

The endpoint requires an authenticated session with an `owner`, `admin`,
`developer`, or `agent` role — any softphone-capable user can intercom a
coworker.

Request body:

| Field          | Type                        | Description                                                                                                                                                        |
| -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `target.kind`  | `user_id` \| `sip_username` | How to resolve the target: a user id (in-app invite) or a registered SIP username (direct device ring).                                                            |
| `target.value` | string                      | The user id or SIP username. 1–128 characters.                                                                                                                     |
| `mode`         | `two_way` \| `ptt`          | `two_way` (default) opens both microphones for an immediate conversation; `ptt` opens your mic and keeps the target's muted until they key it back.                |
| `message`      | string, optional            | A one-shot spoken message (max 500 characters) read over the speaker on auto-answer instead of opening your live mic — for example "Front desk, line one for you." |

## Auto-answer semantics — user target vs SIP target

The target kind determines how the device picks up:

* **`user_id`** — an in-app auto-answer invite is pushed to that user's
  softphone widget. The invite carries a deep link with `autoAnswer=1` and
  the mode, so the widget accepts the call on speaker instead of showing a
  ringing UI. This is the right kind when you address coworkers by their
  user id.
* **`sip_username`** — the target is resolved against your organization's
  registered SIP credentials and rung directly on its device Contact
  binding with a SIP INVITE carrying the hands-free auto-answer headers
  (below). SIP usernames are checked per organization — a deskphone or
  registered softphone is reached by its SIP username, no user id mapping
  required.

## Hands-free headers vs ring-style

There is no single vendor-standard way to ask a phone to auto-answer, so
the INVITE sends both widely deployed forms together — a phone ignores
the one it does not understand:

* `Call-Info: ...;answer-after=0` — honoured by Cisco, Grandstream, Snom,
  Yealink (the `answer-after` convention).
* `Alert-Info: info=alert-autoanswer;delay=0` — honoured by Polycom,
  Aastra, Mitel devices.

An endpoint that honours neither header still rings and plays your
intercom opening on manual answer — degraded, never silently unanswered.
The INVITE also carries `X-Intercom-Mode: two_way|ptt` so softphone answer
handlers can apply mic policy per mode.

## Response

A `200` response reports the outcome of each stage:

| Field                | Meaning                                                                                             |
| -------------------- | --------------------------------------------------------------------------------------------------- |
| `intercomCallId`     | Identifier for this dial (audit handle).                                                            |
| `mode`, `target`     | Echo of the accepted request.                                                                       |
| `targetResolved`     | `true` when the target existed and was verified.                                                    |
| `notified`           | `true` when a `user_id` target received the in-app invite.                                          |
| `sipOriginated`      | `true` when the SIP device was actually rung.                                                       |
| `sipCallSid`         | The SIP call identifier when `sipOriginated` is true.                                               |
| `sipTargetNotMapped` | `true` when the target resolved but the device could not be rung (a partial outcome, not an error). |

Check `sipOriginated` before telling the operator the line is open: a
verified-but-unrang target returns `200` with `sipOriginated: false` and
`sipTargetNotMapped: true` so you can show "Target verified, could not
reach device" instead of a misleading "Dialing…".

## Error cases

* **400** — body failed validation (unknown target kind, a `mode` outside
  `two_way`/`ptt`, or extra fields — the schema is strict).
* **400** — you intercommed your own user id (`user_id` target only).
* **404** — for a `sip_username` target, no **enabled, non-deleted**
  credential with that username exists **in your organization**. The
  check is org-scoped: another organization's credentials are invisible
  to you.

## Example

```bash theme={null}
curl -X POST https://api.orbit.devotel.io/api/v1/voice/intercom/dial \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "target": { "kind": "sip_username", "value": "desk-101" },
    "mode": "ptt",
    "message": "Front desk, line one for you."
  }'
```

```json theme={null}
{
  "data": {
    "intercomCallId": "intercomCall_01J...",
    "mode": "ptt",
    "target": { "kind": "sip_username", "value": "desk-101" },
    "targetResolved": true,
    "notified": false,
    "sipTargetNotMapped": false,
    "sipOriginated": true,
    "sipCallSid": "CA2ea5e1..."
  }
}
```

Related: [Paging groups, ring groups & call
park](/voice/paging-ring-groups-call-park) for the many-to-one broadcast
sibling, and [Colleagues](/voice/colleagues) for presence-aware contact
lists.