# Conferences and queues

Conferences are created by CoXML `<Dial><Conference>`; this API reads them, ends them, plays announcements and
manages participants. Queues hold callers until an agent takes them (`<Enqueue>`, the `enqueue` action).
Paths are relative to `https://api.contactivity.io/v1/projects/{project_id}`; see the [overview](/guides/overview.md).

| Method | Path | Scope | Purpose |
|---|---|---|---|
| GET | `/conferences` | `conferences:read` | List conferences (paged) |
| GET | `/conferences/{conference_id}` | `conferences:read` | Fetch a conference |
| POST | `/conferences/{conference_id}/actions/{action}` | `conferences:write` | `end` or `announce` |
| GET | `/conferences/{conference_id}/participants` | `conferences:read` | List participants (one page, up to 1000) |
| POST | `/conferences/{conference_id}/participants` | `conferences:write`, `calls:write` | Dial a participant in |
| GET | `/conferences/{conference_id}/participants/{call_id}` | `conferences:read` | Fetch a participant |
| PATCH | `/conferences/{conference_id}/participants/{call_id}` | `conferences:write`, `calls:write` | Mute, hold, coach, announce |
| DELETE | `/conferences/{conference_id}/participants/{call_id}` | `conferences:write`, `calls:write` | Remove (hang up) a participant |
| POST | `/queues` | `queues:write` | Create a queue |
| GET | `/queues` | `queues:read` | List queues (paged) |
| GET | `/queues/{queue_id}` | `queues:read` | Fetch a queue |
| PATCH | `/queues/{queue_id}` | `queues:write` | Change `max_size` |
| DELETE | `/queues/{queue_id}` | `queues:write` | Archive an empty queue |
| GET | `/queues/{queue_id}/members` | `queues:read` | Waiting calls (one page, up to 5000) |
| GET | `/queues/{queue_id}/members/{call_id}` | `queues:read` | A member, or `front` |
| POST | `/queues/{queue_id}/members/{call_id}/dequeue` | `queues:write`, `calls:write` | Take a call off the queue |

In participant paths `{call_id}` may also be the participant's `label`.

## Conferences

Object: `id` (`CF…`), `name`, `status` (`init`, `in_progress`, `completed`), `created_at`, `updated_at`.
List filters: `name` (exact), `status`.

Actions: `end` (no body) and `announce` (`{"announce_url": "https://…"}`, CoXML or audio played to everyone).
Both return `200` and the conference. Errors: `404 unknown_action`, `404 not_found`, `400 invalid_parameter`
(param `announce_url`), `422 call_state` (not in progress), `503 engine_unavailable`.

```sh
curl -X POST https://api.contactivity.io/v1/projects/$PROJECT_ID/conferences/$CONF_ID/actions/end \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Idempotency-Key: $(uuidgen)"
```

## Participants

Object: `call_id`, `conference_id`, `label`, `status` (e.g. `connecting`, `ringing`, `connected`, `complete`,
`failed`), `muted`, `on_hold`, `start_conference_on_enter`, `end_conference_on_exit`, `coaching`,
`coaching_call_id`, `created_at`.

Add (`POST`, returns `201`):

| Field | Type | Rules |
|---|---|---|
| `from` | string | Required. A number of the project or a verified number |
| `to` | string | Required. E.164, `client:<name>` or SIP URI |
| `label` | string | Up to 64 letters, digits, `_`, `.`, `-` |
| `muted` | boolean | Default false |
| `start_conference_on_enter` | boolean | Default true |
| `end_conference_on_exit` | boolean | Default false |
| `beep` | string | `true` (default), `false`, `on_enter`, `on_exit` |
| `timeout_secs` | integer | 5-600, default 30 |
| `coaching_call_id` | string | A call (`CA…`) this participant coaches |
| `record` | boolean | |
| `status_callback_url`, `status_callback_events`, `recording_status_callback_url` | | Callbacks for the new call |

Update (`PATCH`, returns `200`): `muted`, `on_hold`, `hold_audio_url`, `announce_url` (played to this
participant), `coaching`, `coaching_call_id`.

```sh
curl -X PATCH https://api.contactivity.io/v1/projects/$PROJECT_ID/conferences/$CONF_ID/participants/agent-1 \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" -H "Content-Type: application/json" \
  -d '{"muted": true}'
```

Errors: `400 invalid_parameter` (param `to`, `from`, `beep`, `timeout_secs`, `label`, `coaching_call_id`,
`hold_audio_url`, `announce_url`, ...), `402 insufficient_balance`, `403 caller_id_not_verified`,
`403 destination_blocked`, `404 not_found`, `422 call_state` (conference not in progress), `503 engine_unavailable`.
Removing returns `204`.

## Queues

Object: `id` (`QU…`), `name`, `max_size`, `current_size`, `average_wait_secs`, `created_at`.

Create: `name` (required, 1-64 characters, unique in the project), `max_size` (1-5000, default 100). Errors:
`400 invalid_parameter` (param `name`, `max_size`), `409 already_exists`. Update takes `max_size`. Delete archives
the queue: `204`, or `409 queue_not_empty`. An archived queue refuses new callers and keeps its name taken.

```sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/queues \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"name": "support", "max_size": 50}'
```

## Members

Object: `call_id`, `queue_id`, `position` (1 = front), `wait_secs`, `enqueued_at`. Use `front` as `{call_id}`
for the longest-waiting caller.

Dequeue sends the call to new CoXML: give one of `coxml_url` (+ `coxml_method`, default `POST`) or `app_id` (a
CoXML voice app with a voice URL). Returns `200` and the member. Errors: `400 invalid_parameter` (param
`coxml_url`, `coxml_method`, `app_id`), `404 not_found`, `422 call_state`, `503 engine_unavailable`.

```sh
curl https://api.contactivity.io/v1/projects/$PROJECT_ID/queues/$QUEUE_ID/members/front/dequeue \
  -H "Authorization: Bearer $CONTACTIVITY_API_KEY" \
  -H "Content-Type: application/json" -H "Idempotency-Key: $(uuidgen)" \
  -d '{"coxml_url": "https://example.com/connect-agent.xml"}'
```