Callbacks

Generated from DialerDigital/core commit 6e9f026f0a72 — spec openapi/dialer-v1.yaml v0.36.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Consumer-agreed redial appointments.

Endpoints

Method	Path	Summary
`GET`	`/v1/callbacks`	Callback queue view / due feed
`POST`	`/v1/callbacks`	Schedule a consumer-agreed redial
`POST`	`/v1/callbacks/{id}/complete`	pending → done
`POST`	`/v1/callbacks/{id}/cancel`	pending → cancelled
`POST`	`/v1/callbacks/{id}/miss`	pending → missed

Callback queue view / due feed

http

GET /v1/callbacks

due=now (also true/1) is the runner-facing due feed (pending AND scheduled_at <= now, priority then time order); otherwise the queue view filtered by status (default pending, soonest first).

Parameters

Name	In	Type	Required	Description
`due`	query	`now` · `true` · `1`	no
`status`	query	`pending` · `done` · `cancelled` · `missed`	no
`campaign_id`	query	string (uuid)	no
`debt_id`	query	string (uuid)	no
`limit`	query	integer	no	Page size (default 100, max 1000).

Responses

`200`

Callbacks matching the view.

Field	Type	Required
`callbacks`	array of Callback	yes
`callbacks[].id`	string (uuid)	no
`callbacks[].tenant_id`	string (uuid)	no
`callbacks[].debt_id`	string (uuid)	no
`callbacks[].contact_phone`	string	no
`callbacks[].campaign_id`	string (uuid) \| null	no
`callbacks[].agent_id`	string (uuid) \| null	no
`callbacks[].scheduled_at`	string (date-time)	no
`callbacks[].note`	string \| null	no
`callbacks[].priority`	integer	no
`callbacks[].status`	`pending` · `done` · `cancelled` · `missed`	no
`callbacks[].created_at`	string (date-time)	no
`callbacks[].updated_at`	string (date-time)	no

`400` — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

Schedule a consumer-agreed redial

http

POST /v1/callbacks

contact_phone must already be a contact of the debt (the gates need line/locale data) → 422 otherwise; less than 10 minutes notice → 422; the number is in R16 quarantine → 422 (the platform will not promise a call it cannot make); unknown debt → 404; bad timestamp → 400. campaign_id defaults to the debt's. The campaign runner dials due callbacks BEFORE fresh leads.

Request body (JSON, required)

Field	Type	Required	Description
`debt_id`	string (uuid)	yes
`contact_phone`	string	yes	E.164 of an existing contact of the debt.
`scheduled_at`	string (date-time)	yes	RFC 3339, at least 10 minutes in the future.
`campaign_id`	string (uuid)	no
`agent_id`	string (uuid)	no
`note`	string	no
`priority`	integer	no

json

{
  "debt_id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "contact_phone": "+13125551001",
  "scheduled_at": "2026-07-06T16:30:00Z",
  "note": "postman: consumer pidió el martes"
}

Responses

`201`

Scheduled callback.

Field	Type	Required
`callback`	object (Callback)	yes
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.updated_at`	string (date-time)	no

`400` — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

The tenant is suspended.

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`422` — Unprocessable

Shape is fine, semantics are not (broken domain rule).

json

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at must be at least 10 minutes out"
  }
}

pending → done

http

POST /v1/callbacks/{id}/complete

Status machine pending → done|cancelled|missed (terminal); 409 on re-transition.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as `404`.

Responses

`200`

The completed callback.

Field	Type	Required
`callback`	object (Callback)	yes
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.updated_at`	string (date-time)	no

`401` — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`404` — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

pending → cancelled

http

POST /v1/callbacks/{id}/cancel

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as `404`.

Responses

`200`

The cancelled callback.

Field	Type	Required
`callback`	object (Callback)	yes
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.updated_at`	string (date-time)	no

`401` — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`404` — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

pending → missed

http

POST /v1/callbacks/{id}/miss

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	yes	Resource UUID. Malformed or cross-tenant ids read as `404`.

Responses

`200`

The missed callback.

Field	Type	Required
`callback`	object (Callback)	yes
`callback.id`	string (uuid)	no
`callback.tenant_id`	string (uuid)	no
`callback.debt_id`	string (uuid)	no
`callback.contact_phone`	string	no
`callback.campaign_id`	string (uuid) \| null	no
`callback.agent_id`	string (uuid) \| null	no
`callback.scheduled_at`	string (date-time)	no
`callback.note`	string \| null	no
`callback.priority`	integer	no
`callback.status`	`pending` · `done` · `cancelled` · `missed`	no
`callback.created_at`	string (date-time)	no
`callback.updated_at`	string (date-time)	no

`401` — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature).

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`404` — NotFound

Unknown id, malformed (non-UUID) id OR another tenant's id — RLS returns zero rows, so all three are indistinguishable by design (no existence leak, never a 403 for foreign ids).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

Callbacks ​

Endpoints ​

Callback queue view / due feed ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

Schedule a consumer-agreed redial ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

422 — Unprocessable ​

pending → done ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

pending → cancelled ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

pending → missed ​

200 ​

401 — Unauthorized ​

404 — NotFound ​

409 — Conflict ​

Callbacks

Endpoints

Callback queue view / due feed

`200`

`400` — BadRequest

`401` — Unauthorized

Schedule a consumer-agreed redial

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`422` — Unprocessable

pending → done

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

pending → cancelled

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict

pending → missed

`200`

`401` — Unauthorized

`404` — NotFound

`409` — Conflict