OneML reference

Dial

The <Dial> verb connects the caller to another phone number. PressOne bridges the two call legs together; once the dialed call ends, PressOne can request an action URL with the outcome.

Attributes

Name	Type	Default	Description
`action`	string (uri)	—	URL to request once the dialed call ends. When absent, execution continues with the next verb in the document.
`method`	string	`POST`	HTTP method used to request `action`. One of `GET` or `POST`.
`timeout`	integer	`30`	Seconds to wait for the dialed party to answer before giving up.
`callerId`	string	—	Number to present to the dialed party as the caller ID. Must be a number your account owns. PressOne fails the dial (`DialCallStatus` of `failed`) if it is not. When omitted, PressOne presents the original caller's number.
`answerOnBridge`	boolean	`false`	Whether to delay answering the caller's leg until the dialed party answers. When `true`, PressOne leaves the caller's leg unanswered until the dialed party picks up, so the caller hears actual ringing until the call connects. When `false`, PressOne answers the caller's leg immediately, before dialing, so the caller typically hears silence instead of ringback until the call connects.
`record`	string	`do-not-record`	Whether to record the dialed call. Accepts `do-not-record`, `record-from-answer`, `record-from-ringing`, `record-from-answer-dual`, `record-from-ringing-dual`, or `record-from-start`. Any value other than `do-not-record` records both parties of the bridged call into a single audio file. `record-from-answer` starts the recording when the dialed party answers; `record-from-ringing` and `record-from-start` begin before the dial, so ringback is captured. The dual-channel variants behave like their base mode but still produce a single mixed channel. When recording is on, the `action` request includes `RecordingUrl`, and `recordingStatusCallback` fires when the recording is ready.
`recordingStatusCallback`	string (uri)	—	URL to notify when the dialed call's recording finishes. PressOne requests this URL once, for the `completed` event only, with `RecordingSource` set to `DialVerb`.
`recordingStatusCallbackMethod`	string	`POST`	HTTP method used to request `recordingStatusCallback`. One of `GET` or `POST`.
`timeLimit`	integer	`14400`	Maximum duration of the dialed call, in seconds. When it expires, PressOne hangs up the dialed party; a call that connected reports a `DialCallStatus` of `completed`. Defaults to four hours.
`hangupOnStar`	boolean	`false`	Whether the caller can press `` to hang up on the dialed party without ending their own call. The document then continues: the `action` URL is requested with a `DialCallStatus` of `completed`. The dialed party's `` has no effect.
`ringTone`	string	—	Country code selecting the ringback tone the caller hears while the dialed party rings. One of `us`, `ca`, `uk`, `nz`, `au`, `de`, `it`, `br`, `mx`, `es`, `pt`, `fr`, `in`, `jp`, or `za`. Other values fall back to the carrier's own ringback. When the dialed party's network sends early media, that audio takes precedence over the selected tone.
`sequential`	boolean	`false`	Whether to dial multiple `<Number>` children one at a time instead of all at once. When `false`, PressOne rings every target simultaneously and bridges the caller to whichever answers first. When `true`, PressOne dials each target in order, moving to the next only if the previous one does not complete.

Nesting

<Dial> accepts a phone number as its text content, or one or more <Number> child elements.

`<Number>`

Name	Type	Default	Description
`sendDigits`	string	—	Accepted but not currently applied. PressOne does not send these DTMF tones to the dialed party after the call connects, regardless of this attribute.

<Number> contains the phone number to dial as text content.

Note: Conference, client, SIP, and queue targets are not available. See the compatibility page for the full list of unsupported targets.

Action parameters

Name	Type	Description
`DialCallStatus`	string	Outcome of the dialed call. One of `completed`, `busy`, `no-answer`, `canceled`, or `failed`.
`DialCallDuration`	integer	Duration of the bridged call, in seconds. Present only when the call bridged.
`DialCallSid`	string	Unique identifier for the dialed call leg. Present only when the call bridged.
`RecordingUrl`	string (uri)	Public URL of the recorded audio file. Present only when `record` was enabled. Recording URLs are publicly readable; see the warning on `<Record>`.

Examples

A simple forward to another number:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+2341700000000">+2341800000001</Dial>
</Response>

Forwarding with an action fallback to voicemail when the call does not complete:

Code
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial action="/dial-complete" callerId="+2341700000000" timeout="20">
    <Number>+2341800000001</Number>
  </Dial>
</Response>

The /dial-complete handler, complete and runnable:

Whether to delay answering the caller's leg until the dialed party answers. When true, PressOne leaves the caller's leg unanswered until the dialed party picks up, so the caller hears actual ringing until the call connects. When false, PressOne answers the caller's leg immediately, before dialing, so the caller typically hears silence instead of ringback until the call connects.

record

string

do-not-record

Whether to record the dialed call. Accepts do-not-record, record-from-answer, record-from-ringing, record-from-answer-dual, record-from-ringing-dual, or record-from-start. Any value other than do-not-record records both parties of the bridged call into a single audio file. record-from-answer starts the recording when the dialed party answers; record-from-ringing and record-from-start begin before the dial, so ringback is captured. The dual-channel variants behave like their base mode but still produce a single mixed channel. When recording is on, the action request includes RecordingUrl, and recordingStatusCallback fires when the recording is ready.

recordingStatusCallback

string (uri)

—

URL to notify when the dialed call's recording finishes. PressOne requests this URL once, for the completed event only, with RecordingSource set to DialVerb.

recordingStatusCallbackMethod

string

POST

HTTP method used to request recordingStatusCallback. One of GET or POST.

timeLimit

integer

14400

Maximum duration of the dialed call, in seconds. When it expires, PressOne hangs up the dialed party; a call that connected reports a DialCallStatus of completed. Defaults to four hours.

hangupOnStar

boolean

false

Whether the caller can press * to hang up on the dialed party without ending their own call. The document then continues: the action URL is requested with a DialCallStatus of completed. The dialed party's * has no effect.

ringTone

string

—

Country code selecting the ringback tone the caller hears while the dialed party rings. One of us, ca, uk, nz, au, de, it, br, mx, es, pt, fr, in, jp, or za. Other values fall back to the carrier's own ringback. When the dialed party's network sends early media, that audio takes precedence over the selected tone.

sequential

boolean

false

Whether to dial multiple <Number> children one at a time instead of all at once. When false, PressOne rings every target simultaneously and bridges the caller to whichever answers first. When true, PressOne dials each target in order, moving to the next only if the previous one does not complete.

Nesting

<Dial> accepts a phone number as its text content, or one or more <Number> child elements.

<Number>

Name

Type

Default

Description

sendDigits

string

—

Accepted but not currently applied. PressOne does not send these DTMF tones to the dialed party after the call connects, regardless of this attribute.

<Number> contains the phone number to dial as text content.

Note: Conference, client, SIP, and queue targets are not available. See the compatibility page for the full list of unsupported targets.

Action parameters

Name

Type

Description

DialCallStatus

string

Outcome of the dialed call. One of completed, busy, no-answer, canceled, or failed.

DialCallDuration

integer

Duration of the bridged call, in seconds. Present only when the call bridged.

DialCallSid

string

Unique identifier for the dialed call leg. Present only when the call bridged.

RecordingUrl

string (uri)

Public URL of the recorded audio file. Present only when record was enabled. Recording URLs are publicly readable; see the warning on <Record>.

Examples

A simple forward to another number:

Code

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial callerId="+2341700000000">+2341800000001</Dial>
</Response>

Forwarding with an action fallback to voicemail when the call does not complete:

Code

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial action="/dial-complete" callerId="+2341700000000" timeout="20">
    <Number>+2341800000001</Number>
  </Dial>
</Response>

The /dial-complete handler, complete and runnable:

const express = require("express");
const app = express();
app.use(express.urlencoded({ extended: false }));

app.post("/dial-complete", (req, res) => {
  const status = req.body.DialCallStatus;
  let oneml;

  if (status === "completed") {
    oneml = `<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Hangup/>
</Response>`;
  } else {
    oneml = `<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Our team is unavailable right now. Please leave a message after the beep.</Say>
  <Record action="/voicemail-complete" maxLength="120"/>
  <Hangup/>
</Response>`;
  }

  res.type("text/xml").send(oneml);
});

app.listen(3000);

Dial

Attributes

Nesting

`<Number>`

Action parameters

Examples

See also

Dial

Attributes

Nesting

`<Number>`

Action parameters

Examples

See also