Reject

The Reject verb rejects an incoming call without answering it. Since the call is never answered, no billing occurs.

Example

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Reject",
      "reason": "busy"
    }
  ]
}

Parameters

Parameter	Type	Required	Default	Description
reason	string	no	rejected	"rejected" or "busy"

Reasons

Rejected (Default)

Reject the call with a generic rejection:

{
  "verb": "Reject",
  "reason": "rejected"
}

The caller typically hears a message like "The person you are calling is not available."

Busy

Reject the call with a busy signal:

{
  "verb": "Reject",
  "reason": "busy"
}

The caller hears a busy tone.

Use Cases

Blacklist/Blocklist

Reject calls from blocked numbers:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Reject",
      "reason": "rejected"
    }
  ]
}

Your webhook logic:

// Check if caller is blocked
if (isNumberBlocked(callData.from)) {
  return {
    voxml_version: "1.0",
    instructions: [
      { verb: "Reject", reason: "rejected" }
    ]
  };
}

Business Hours

Reject calls outside business hours:

if (!isBusinessHours()) {
  return {
    voxml_version: "1.0",
    instructions: [
      { verb: "Reject", reason: "busy" }
    ]
  };
}

Note: This is not recommended. It's better to answer and provide a message:

if (!isBusinessHours()) {
  return {
    voxml_version: "1.0",
    instructions: [
      {
        verb: "Say",
        text: "We are currently closed. Our hours are Monday to Friday, 9 AM to 6 PM."
      },
      { verb: "Hangup" }
    ]
  };
}

Capacity Limits

Reject when call queue is full:

if (getCurrentCallCount() >= MAX_CONCURRENT_CALLS) {
  return {
    voxml_version: "1.0",
    instructions: [
      { verb: "Reject", reason: "busy" }
    ]
  };
}

Again, providing a message is better UX:

if (getCurrentCallCount() >= MAX_CONCURRENT_CALLS) {
  return {
    voxml_version: "1.0",
    instructions: [
      {
        verb: "Say",
        text: "We are experiencing high call volume. Please try again later."
      },
      { verb: "Hangup" }
    ]
  };
}

Spam Prevention

Reject likely spam calls:

if (isSpamNumber(callData.from)) {
  return {
    voxml_version: "1.0",
    instructions: [
      { verb: "Reject", reason: "rejected" }
    ]
  };
}

No Billing

The key advantage of Reject is that rejected calls are not billed. The call is refused before being answered, so no charges apply.

This makes Reject ideal for:

Blocking spam or unwanted callers
Enforcing strict capacity limits
Protecting against toll fraud

Execution Flow

When Reject is encountered:

The call is immediately refused
The caller receives a rejection signal (busy tone or unavailable message)
No billing occurs
Any instructions after Reject are ignored

Reject vs. Hangup

Aspect	Reject	Hangup
When to use	Before answering	During an active call
Billing	No charge	Call is billed
Caller experience	Never connected	Connected, then disconnected
Use case	Block/refuse calls	End active calls

Reject example:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Reject",
      "reason": "busy"
    }
  ]
}

Hangup example:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "Goodbye"
    },
    {
      "verb": "Hangup",
      "reason": "completed"
    }
  ]
}

Best Practices

Use Reject sparingly - answering with a message is usually better UX
Prefer reason: "busy" for temporary unavailability
Use reason: "rejected" for permanent blocks
Consider logging rejected calls for spam analysis
Don't reject all calls outside business hours - provide information instead
Use Reject for clear spam/fraud prevention

Status Callbacks

Rejected calls trigger a call-rejected event in status callbacks:

{
  "call_uuid": "call_abc123",
  "status": "rejected",
  "reject_reason": "busy",
  "from": "+919876543210",
  "to": "+911234567890",
  "timestamp": "2026-04-09T10:30:00Z"
}

When NOT to Use Reject

Avoid using Reject when you should provide information to the caller:

Bad:

{
  "verb": "Reject",
  "reason": "busy"
}

Good:

{
  "verb": "Say",
  "text": "We are currently closed. Please call back Monday through Friday, 9 AM to 6 PM. Thank you."
},
{
  "verb": "Hangup"
}

While Reject saves on billing, providing helpful information creates better customer experience.

Reject

On this page