Quick Agent Actions

Quick Agent Actions are the shortest path from “an AI agent wants to reach someone” to a real phone call or text. There is no number to provision, no assistant to configure, and no campaign to build: you send a goal, LumisReach runs the conversation, and you poll one endpoint for the outcome. Everything here runs on Telnyx + LiveKit, the same stack behind the rest of the platform.

Quick AI Phone Call

An AI agent calls one or more numbers from a shared LumisReach number and works toward your goal, with retries when nobody picks up.

Quick AI Text

An AI agent opens an SMS thread from a registered shared sender and keeps answering replies until the goal is met.

AI Phone Number

Buy a number and configure the agent that answers it — calls and, optionally, texts — in a single request.

Shared senders

Quick calls and quick texts go out from numbers LumisReach owns, on the LumisReach Official account. That is what removes the setup step: you do not buy a number, register a brand, or wait for provisioning before your first call. What this means in practice:

The recipient sees a LumisReach number, not one of yours. A single job can go out from more than one number — each destination reports its own from_number — so no single number carries an entire job.
Texts are already registered. The shared SMS senders sit on LumisReach’s approved A2P 10DLC campaign, so the first message is registered traffic rather than filtered traffic.
Everything the conversation produces is yours. Call records, recordings, transcripts, messages and contacts are written into your workspace, scoped to your organization like any other data.
Replies come back to us, not to you. A shared number cannot ring your phone. When someone needs to be able to call or text you back, provision your own number with POST /v1/quick/ai-numbers.

Daily limits

Carriers flag a number that places too many calls in a day, and a flagged shared number would degrade every account using the pool. So each shared number has a daily ceiling, and the pool spreads work to stay under it:

Calls: up to 75 per number per day once the number is warmed up. A number bought in the last week is held to 15/day and 40/day in its second week, the same ramp outbound campaigns use.
Texts: up to 500 outbound messages per number per day.
Selection: each leg draws a number at random from those that still have room, weighted by how much room is left, so traffic self-levels instead of piling onto one number.

A number at its ceiling is not used again until the next day — including for a retry that comes due after the number filled up. If the whole pool is exhausted, the request returns 409 with Every shared LumisReach … number has reached its daily volume limit; destinations a job could not cover are recorded with end_reason: "shared_pool_daily_limit" rather than dropped. Provision your own number with POST /v1/quick/ai-numbers when you need volume beyond what the shared pool allows.

Pricing

Quick actions are priced per action and charged to the wallet of the organization that owns the API key you authenticate with. They do not draw down plan-included minutes or messages — the shared sender carries no line fee, so the usage is billed à la carte.

Action	Price
Quick AI phone call	$0.20 per call placed + $ 0.20 per minute of conversation
Quick AI text message	$0.05 per outbound message
AI phone number	$5 per month for the line (calls and texts on it bill at your plan’s rates)

The

0.20 call fee is charged when the call is **placed**, not when it is answered — and each retry is a new placed call. A job with `retry_attempts: 2` that never reaches anyone costs

0.60. Talk time is billed by the second at the per-minute rate. For texts, only outbound messages are billed; replies from the recipient are free.

If the wallet balance runs out mid-job, auto-recharge fires if it is enabled on the account; otherwise the account pauses and remaining attempts stop. Check your balance and top-up settings under Settings → Billing.

Place an AI call

curl -X POST https://api.lumisreach.com/api/v1/quick/ai-calls \
  -H "Authorization: Bearer $LUMISREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_numbers": ["+14155550123"],
    "goal": "Confirm that Dana still wants the 3pm Thursday appointment, and reschedule to Friday if not.",
    "opening_message": "Hi, this is Ada calling from Northside Dental about your appointment.",
    "retry_attempts": 2,
    "retry_delay_minutes": 15,
    "voice": "marin"
  }'

{
  "data": {
    "id": "0f3c...c81",
    "kind": "ai_call",
    "status": "running",
    "from_number": "+14153261744",
    "target_count": 1,
    "status_url": "/api/v1/quick/actions/0f3c...c81",
    "pricing": {
      "start_fee_usd": 0.2,
      "per_minute_usd": 0.2,
      "note": "Charged per initiated call (including each retry), plus per-second conversation time at the per-minute rate."
    }
  }
}

The response returns as soon as the first attempt is dialing. Retries are automatic: if a number rings out, goes to voicemail, or is busy, the agent tries again after retry_delay_minutes until retry_attempts is exhausted.

What you can configure

Field	What it does
`goal`	The spine of the system prompt. Write it as an outcome, not a script.
`instructions`	Tone, facts the agent may state, objections to expect.
`opening_message`	What the agent says first, once the recipient speaks.
`voice`, `voice_model_tier`, `language`	Voice selection and language.
`retry_attempts`, `retry_delay_minutes`	How persistently to chase an unanswered number.
`max_call_duration_seconds`	Hard stop on call length (default 10 minutes).
`voicemail_enabled`, `voicemail_message`	Whether to leave a voicemail, and exactly what to say.
`contact_name`	Used for `{{CONTACT_NAME}}` in the conversation.

Send AI text messages

curl -X POST https://api.lumisreach.com/api/v1/quick/ai-texts \
  -H "Authorization: Bearer $LUMISREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_numbers": ["+14155550123"],
    "goal": "Find out whether they still want the quote, and if so which day next week works for a call.",
    "first_message": "Hi Dana, it is Ada at Northside. Still want that quote? Happy to send it over.",
    "max_messages": 4
  }'

Omit first_message and the agent writes the opener from the goal. After that it answers each reply on its own until the goal is met, max_messages outbound messages have been sent, the recipient goes quiet for conversation_timeout_hours, or they text STOP.

STOP is honored automatically and the thread ends immediately. Opt-out language is appended to the first message to a new recipient. Text only people who have agreed to hear from you — the shared sender carries LumisReach’s 10DLC registration, and a complaint against it affects every account using it.

Check on a job

Both kinds of job report through the same endpoint.

curl https://api.lumisreach.com/api/v1/quick/actions/0f3c...c81 \
  -H "Authorization: Bearer $LUMISREACH_API_KEY"

{
  "data": {
    "id": "0f3c...c81",
    "kind": "ai_call",
    "status": "running",
    "goal": "Confirm that Dana still wants the 3pm Thursday appointment...",
    "from_number": "+14153261744",
    "targets": [
      {
        "to_number": "+14155550123",
        "from_number": "+14153261744",
        "status": "in_progress",
        "live_call_status": "ringing",
        "attempts": 1,
        "last_call_id": "b91e...4af",
        "messages_sent": 0,
        "messages_received": 0,
        "goal_achieved": false,
        "end_reason": null,
        "summary": null
      }
    ],
    "counts": {
      "total": 1,
      "pending": 0,
      "in_progress": 1,
      "completed": 0,
      "no_answer": 0,
      "failed": 0,
      "opted_out": 0,
      "canceled": 0
    },
    "created_at": "2026-09-19T17:02:11.480Z",
    "completed_at": null
  }
}

A target’s status is one of pending, in_progress, completed, no_answer, failed, opted_out or canceled. While a call is live, live_call_status reports what the call itself is doing (ringing, in_progress, …) so polling shows the call as it happens. end_reason explains how a finished target ended: answered, goal_achieved, voicemail, max_attempts, max_messages, opted_out, canceled, shared_pool_daily_limit, or the provider’s error text. from_number is the shared number that particular destination was reached from. To stop a job early, POST /v1/quick/actions/{id}/cancel. Remaining dials and AI replies stop; a call that is already connected is allowed to finish.

Buy a number with an AI agent

When people need to reach you — an inbound line, a number on a listing, a callback number — buy one and configure its agent in the same request:

curl -X POST https://api.lumisreach.com/api/v1/quick/ai-numbers \
  -H "Authorization: Bearer $LUMISREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "area_code": "415",
    "name": "Support line",
    "business_name": "Northside Dental",
    "business_description": "A family dental practice in San Francisco. Cleanings, fillings, crowns, Invisalign.",
    "greeting": "Thanks for calling Northside Dental, this is Ada. How can I help?",
    "handle_calls": true,
    "handle_texts": true
  }'

handle_calls (default true) controls whether the AI answers inbound calls. handle_texts (default false) puts the same agent on inbound SMS for that number. Provisioning is asynchronous — poll until it reports ready:

curl https://api.lumisreach.com/api/v1/quick/ai-numbers/42 \
  -H "Authorization: Bearer $LUMISREACH_API_KEY"

{
  "data": {
    "id": 42,
    "phone_number": "+14155551234",
    "status": "ready",
    "handles_calls": true,
    "handles_texts": true,
    "sms_registered": true,
    "agent": {
      "id": "8c1d...7b2",
      "name": "Northside Dental",
      "voice": "marin",
      "language": "en",
      "greeting": "Thanks for calling Northside Dental, this is Ada. How can I help?",
      "prompt": "..."
    }
  }
}

status moves provisioning → ready, or failed if the number could not be wired up. While it is provisioning, phone_number is null; once it is ready, the number is live and answering.

Authentication

Quick Agent Actions use the same Bearer API key as the rest of the v1 API. A key created under Settings → Developer API works on every endpoint on this page with no extra configuration. See Authentication.

Using these from an AI agent

Every action on this page is also exposed as a tool on the LumisReach MCP server, so an agent can call, text, and provision numbers without you writing HTTP glue. See MCP server.

Getting Started

Concepts

Phone Numbers

Caller IDs

Enterprise Registration

Enterprise Registration (Legacy)

Branded Calling

Calls

SMS

WebRTC

Documents

Reputation

Usage

Quick Agent Actions

Quick AI Phone Call

Quick AI Text

AI Phone Number

Shared senders

Daily limits

Pricing

Place an AI call

What you can configure

Send AI text messages

Check on a job

Buy a number with an AI agent

Authentication

Using these from an AI agent

Quick AI Phone Call

Quick AI Text

AI Phone Number

​Shared senders

​Daily limits

​Pricing

​Place an AI call

​What you can configure

​Send AI text messages

​Check on a job

​Buy a number with an AI agent

​Authentication

​Using these from an AI agent

Shared senders

Daily limits

Pricing

Place an AI call

What you can configure

Send AI text messages

Check on a job

Buy a number with an AI agent

Authentication

Using these from an AI agent