Hangup

The Hangup verb immediately terminates the call.

Example

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "Thank you for calling. Goodbye."
    },
    {
      "verb": "Hangup"
    }
  ]
}

Parameters

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

Basic Usage

End the call with default reason:

{
  "verb": "Hangup"
}

Specify a reason:

{
  "verb": "Hangup",
  "reason": "completed"
}

Reasons

Completed

Normal call completion (default):

{
  "verb": "Hangup",
  "reason": "completed"
}

Busy

Indicate the call ended because the line is busy:

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

Rejected

Indicate the call was rejected:

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

The reason parameter affects:

Call detail records (CDR)
Status callbacks
Analytics and reporting

Use Cases

Normal Call Completion

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "Your request has been processed. Have a great day!"
    },
    {
      "verb": "Pause",
      "length": 1
    },
    {
      "verb": "Hangup",
      "reason": "completed"
    }
  ]
}

After Voicemail

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "Thank you for your message. We'll get back to you soon."
    },
    {
      "verb": "Hangup"
    }
  ]
}

Invalid Input

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "I'm sorry, I didn't understand that. Please try again later. Goodbye."
    },
    {
      "verb": "Hangup",
      "reason": "rejected"
    }
  ]
}

After Maximum Retries

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "You have exceeded the maximum number of attempts. Please contact support. Goodbye."
    },
    {
      "verb": "Hangup",
      "reason": "rejected"
    }
  ]
}

Execution Flow

When Hangup is encountered:

Any remaining instructions in the VoxML are ignored
The call is immediately terminated
Status callbacks (if configured) are triggered
Call duration is recorded for billing

Instructions after Hangup will not execute:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Hangup"
    },
    {
      "verb": "Say",
      "text": "This will never be played."
    }
  ]
}

Implicit Hangup

You don't always need to explicitly use Hangup. The call automatically ends when:

All VoxML instructions have been executed
The caller hangs up
A timeout occurs with no further instructions

However, explicitly using Hangup is a best practice for clarity.

Best Practices

Always say goodbye before hanging up
Use appropriate reason values for analytics
Add a brief pause before Hangup to ensure messages complete
Make Hangup the last instruction in your VoxML
Use explicit Hangup rather than relying on implicit termination

Hangup vs. Reject

Hangup: Ends an answered call. The caller has been connected and billed.

Reject: Refuses an incoming call before answering. No billing occurs.

Use Hangup during a call:

{
  "verb": "Say",
  "text": "Goodbye"
},
{
  "verb": "Hangup"
}

Use Reject for incoming calls you don't want to answer:

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

Status Callbacks

If you've configured status callbacks on your TryVox application, Hangup triggers a call-ended event:

{
  "call_uuid": "call_abc123",
  "status": "completed",
  "duration": 45,
  "end_time": "2026-04-09T10:30:00Z",
  "hangup_reason": "completed"
}

The hangup_reason field will contain the value you specified in the Hangup verb.

Hangup

On this page