Worked claim→launch dialer samples

The preview-dial loop: claim → review → launch

Outbound-campaign operators run the dialer workspace. Progressive, predictive, and agentless campaigns fire through the pacing scheduler automatically; preview mode is the one where a human reviews each contact card before the call launches. That human loop compresses into two endpoints, and both are worked below end-to-end.

1. Claim the next contact

The agent’s frontend claims the next contact with GET /api/v1/dialer/next-call:

cURL

curl "https://api.orbit.devotel.io/api/v1/dialer/next-call?campaign_id=cmp_71bd" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/dialer/next-call?campaign_id=cmp_71bd',
  {
    method: 'GET',
    headers: { 'X-API-Key': process.env.ORBIT_API_KEY! },
  },
)
console.log(await res.json())

{
  "data": {
    "contact": {
      "id": "dc_3f9ac42b",
      "phone_e164": "+14155552671",
      "display_name": "Dana Reyes",
      "attempts": 1
    },
    "preview_decision_seconds": 30,
    "decision_expires_at": "2026-08-01T12:01:30.000Z"
  },
  "meta": {
    "request_id": "req_next_call",
    "timestamp": "2026-08-01T12:00:00.000Z"
  }
}

The claim is atomic — two agents polling concurrently never receive the same number — so the response is the work ticket the agent reviews on their screen. preview_decision_seconds is the per-campaign review countdown; decision_expires_at is the server-side deadline for that countdown. 204 No Content means the campaign is progressive / predictive / agentless (calls fire automatically); 404 means the campaign is not active. A null contact means the list is drained.

2. Launch the dial

Once the agent clicks “Call”, the dial launches with POST /api/v1/dialer/dial:

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/dial" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: idem_dc_3f9ac42b_launch" \
  -d '{"campaign_id":"cmp_71bd","contact_id":"dc_3f9ac42b"}'

Node.js

const launch = await fetch('https://api.orbit.devotel.io/api/v1/dialer/dial', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.ORBIT_API_KEY!,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'idem_dc_3f9ac42b_launch',
  },
  body: JSON.stringify({
    campaign_id: 'cmp_71bd',
    contact_id: 'dc_3f9ac42b',
  }),
})
console.log(await launch.json())

{
  "data": {
    "attempt_id": "att_0b9f21c3",
    "jambonz_call_sid": "jbs_47c1ac2e9d",
    "contact_id": "dc_3f9ac42b",
    "campaign_id": "cmp_71bd"
  },
  "meta": {
    "request_id": "req_dial_launch",
    "timestamp": "2026-08-01T12:00:42.000Z"
  }
}

The contact must still be in the dialing (claimed) state, or the request rejects with 409 CLAIM_NOT_HELD. The requesting operator records as the call’s agent for the TCPA audit trail, and the call itself exits through the Devotel softswitch — the preview loop never dials a number outside the commit path. Pass an Idempotency-Key so a retried client click never double-dials the same contact.

Hopper controls: pause and resume a running campaign

Pause and resume are the same PATCH /api/v1/dialer/campaigns/{id} operation with a status body field — valid for progressive and preview campaigns alike. Pausing stops the pacing scheduler and the preview claim queue; in-flight legs terminate normally.

Pause — cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"paused"}'

Pause — Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'paused' }),
  },
)
console.log(await res.json())

Resume — cURL

curl -X PATCH "https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"active"}'

Resume — Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd',
  {
    method: 'PATCH',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ status: 'active' }),
  },
)
console.log(await res.json())

Resuming stays an explicit operator action — when the org-wide compliance emergency stop is engaged, a missing voice application, or a recording-consent gap blocks activation, the patch rejects with a descriptive 4xx instead of silently restarting the hopper.

Disposition the contact with an optional callback

After the call wraps, the agent submits the outcome with POST /api/v1/dialer/campaigns/{id}/dispositions. When the disposition is callback_later, callback_scheduled_at is required: ISO-8601 with offset, in the future, and within 90 days.

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd/dispositions" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attempt_id": "att_0b9f21c3",
    "disposition": "callback_later",
    "callback_scheduled_at": "2026-08-02T15:30:00+02:00",
    "notes": "Customer asked for a callback tomorrow afternoon."
  }'

Node.js

const res = await fetch(
  'https://api.orbit.devotel.io/api/v1/dialer/campaigns/cmp_71bd/dispositions',
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ORBIT_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      attempt_id: 'att_0b9f21c3',
      disposition: 'callback_later',
      callback_scheduled_at: '2026-08-02T15:30:00+02:00',
      notes: 'Customer asked for a callback tomorrow afternoon.',
    }),
  },
)
console.log(await res.json())

The contact moves to its next lifecycle status (callback_scheduled, dnc, wrong_number, connected, …). A dnc or wrong_number disposition also writes a suppression entry, so future dial attempts to that number are blocked across every campaign in your tenant. Dispositions are recorded against the claim-time agent and are audit-loggable for TCPA defense.

Where errors go

The dialer rejects with a stable error.code in the envelope — the full registry of codes across the API lives in the on-page errors matrix, Error codes. The failures you will actually hit in this loop:

Status	Code	When
`404`	—	`GET /next-call` — the campaign is not active (or not found).
`409`	`CLAIM_NOT_HELD`	`POST /dial` — the contact is no longer in the claimed `dialing` state (claim expired or never claimed).
`400`	`VALIDATION_ERROR`	`POST /dispositions` — `callback_scheduled_at` is missing, in the past, or beyond 90 days on a `callback_later` disposition.
`409`	—	`PATCH /campaigns/{id}` — a blocked activation (emergency stop, unresolved voice application, recording-consent gap).
`409`	`DIALER_CAMPAIGN_IN_FLIGHT` / `DIALER_LIST_IN_FLIGHT`	`DELETE` — contacts are still `dialing`; pause and let in-flight legs terminate first.

Parse error.code, not the HTTP status alone — for example 409 carries both the claim-conflict and the in-flight-delete cases.

SDK surface bridge — List outbound-dialer campaigns, queue the next hop of the campaign FIFO, or trigger one alias lane — all with the sandbox key.

These three tabs mirror SDK status and coverage. Python fronts client.request, Go fronts client.Request, and TS fronts fetch-TS — each with the sandbox key.

List dialer campaigns

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY"

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns', {
  method: 'GET',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
  },
})
console.log(await res.json())

client.request

r = requests.get("https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns", headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	http.DefaultClient.Do(req)
}

Queue the next campaign hop

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/queue" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "fifo": "next"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/queue', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "fifo": "next"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/queue", json={
  "fifo": "next"
}, headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/queue", bytes.NewBuffer([]byte(`{
  "fifo": "next"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Fire one alias lane

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/alias" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "lane": "one"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/alias', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "lane": "one"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/alias", json={
  "lane": "one"
}, headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/alias", bytes.NewBuffer([]byte(`{
  "lane": "one"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

Alias-lane request inbox

cURL

curl -X POST "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/request" \
  -H "X-API-Key: ORBIT_SANDBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inbox": "alias"
}'

fetch-TS (Node SDK style)

const res = await fetch('https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/request', {
  method: 'POST',
  headers: {
'X-API-Key': process.env.ORBIT_SANDBOX_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
  "inbox": "alias"
},
})
console.log(await res.json())

client.request

r = requests.post("https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/request", json={
  "inbox": "alias"
}, headers={ "X-API-Key": os.environ["ORBIT_SANDBOX_KEY"] })
print(r.json())

client.Request

package main

import (
	"bytes"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("POST", "https://api.orbit.devotel.io/api/v1/voice/dialer/campaigns/cmp_demo/request", bytes.NewBuffer([]byte(`{
  "inbox": "alias"
}`)))
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_SANDBOX_KEY"))
	req.Header.Set("Content-Type", "application/json")
	http.DefaultClient.Do(req)
}

API Reference

All Endpoints

The preview-dial loop: claim → review → launch

1. Claim the next contact

2. Launch the dial

Hopper controls: pause and resume a running campaign

Disposition the contact with an optional callback

Where errors go

SDK surface bridge — List outbound-dialer campaigns, queue the next hop of the campaign FIFO, or trigger one alias lane — all with the sandbox key.

List dialer campaigns

Queue the next campaign hop

Fire one alias lane

Alias-lane request inbox

​The preview-dial loop: claim → review → launch

​1. Claim the next contact

​2. Launch the dial

​Hopper controls: pause and resume a running campaign

​Disposition the contact with an optional callback

​Where errors go

​SDK surface bridge — List outbound-dialer campaigns, queue the next hop of the campaign FIFO, or trigger one alias lane — all with the sandbox key.

​List dialer campaigns

​Queue the next campaign hop

​Fire one alias lane

​Alias-lane request inbox

The preview-dial loop: claim → review → launch

1. Claim the next contact

2. Launch the dial

Hopper controls: pause and resume a running campaign

Disposition the contact with an optional callback

Where errors go

SDK surface bridge — List outbound-dialer campaigns, queue the next hop of the campaign FIFO, or trigger one alias lane — all with the sandbox key.

List dialer campaigns

Queue the next campaign hop

Fire one alias lane

Alias-lane request inbox