Queue & Fanout

Use POST /v1/calls/batch to queue up to 500 outbound PSTN recipients in one request. The endpoint creates a single call session and enqueues one PSTN participant per recipient.

You can also use the primary Calls API directly by sending multiple pstn participants to POST /v1/calls.

Queue Batch

POST /v1/calls/batch

Request Body

Field	Type	Required	Default	Description
agent_id	uuid	Yes	—	Agent persona to dial with
to	string[]	Yes (unless recipients)	—	Recipient phone numbers in E.164 format (e.g., ["+15559990001", "+15559990002"])
recipients	Recipient[]	Yes (unless to)	—	Recipient objects with per-recipient overrides
from_number	string	No	Tenant default	Shared caller ID in E.164 format. If omitted, Rymi resolves your default number
batch_id	string	No	Auto-generated	Caller-supplied batch identifier for tracking
metadata	object	No	{}	Metadata stored on the call record
variables	object	No	{}	Shared variables passed into queued telephony jobs
post_call	Post-call object	No	Agent default	Per-batch post-call intelligence override

Recipient Object

Use recipients instead of to when you need per-recipient caller ID or metadata.

Field	Type	Required	Default	Description
to or identity	string	Yes	—	Recipient phone number in E.164 format
from_number	string	No	Batch-level from_number	Per-recipient caller ID override
metadata	object	No	{}	Per-recipient metadata

Example — Simple Batch

curl -X POST https://api.rymi.live/v1/calls/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "to": ["+15559990001", "+15559990002"],
    "from_number": "+15559990000",
    "metadata": { "batch_label": "promo-q1" },
    "variables": { "campaign": "spring-offer" }
  }'

Example — Per-Recipient Metadata

curl -X POST https://api.rymi.live/v1/calls/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "550e8400-e29b-41d4-a716-446655440000",
    "recipients": [
      {
        "to": "+15559990001",
        "from_number": "+15559990000",
        "metadata": { "name": "Alice", "plan": "Gold" }
      },
      {
        "to": "+15559990002",
        "metadata": { "name": "Bob", "plan": "Silver" }
      }
    ],
    "from_number": "+15559990000",
    "batch_id": "promo-q1-2026",
    "variables": { "campaign": "spring-offer" }
  }'

Response 202

{
  "id": "call_abc123",
  "room_name": "call_call_abc123",
  "status": "queued",
  "batch_id": "promo-q1-2026",
  "queued": 2,
  "participants": [
    {
      "id": "participant_1",
      "transport": "pstn",
      "identity": "+15559990001",
      "status": "queued",
      "telephony_leg_id": "leg_1",
      "job_id": "job_1"
    },
    {
      "id": "participant_2",
      "transport": "pstn",
      "identity": "+15559990002",
      "status": "queued",
      "telephony_leg_id": "leg_2",
      "job_id": "job_2"
    }
  ]
}

Errors

Status	Meaning
400	Validation error (missing agent_id, empty to/recipients, exceeds 500 limit, invalid E.164 numbers)
401	Missing or invalid API key
402	Insufficient credits
403	Publishable keys cannot use batch API
404	Agent not found for this tenant
409	One or more recipients are on the DNC list (rejected before queueing)

---

Direct Participant Fanout

If you need mixed WebRTC/PSTN rooms or participant-specific metadata, send multiple participants directly to POST /v1/calls:

{
  "agent_id": "550e8400-e29b-41d4-a716-446655440000",
  "participants": [
    {
      "transport": "pstn",
      "identity": "+15559990001",
      "from_number": "+15559990000",
      "metadata": { "name": "Alice", "plan": "Gold" }
    },
    {
      "transport": "pstn",
      "identity": "+15559990002",
      "from_number": "+15559990000",
      "metadata": { "name": "Bob", "plan": "Silver" }
    }
  ],
  "variables": { "campaign": "spring-offer" }
}

---

Queue Stats

Check the health and current status of your queued batch calling worker.

GET /v1/calls/queue/stats

Response 200

{
  "waiting": 150,
  "active": 10,
  "completed": 45,
  "failed": 2
}

Field	Type	Description
waiting	integer	Jobs waiting to be processed
active	integer	Jobs currently being processed
completed	integer	Successfully completed jobs
failed	integer	Jobs that failed

---

Queue Status Flow

Each queued PSTN participant progresses independently:

queued → dialing → in_progress → completed
                                → failed

DNC Filtering

Contacts on your DNC registry are rejected during request validation and are never queued. See Compliance.