Status codes
Stable machine-readable codes used by the Partner API. Prefer GET /api/external/v1/reference/statuses for programmatic label maps (read-only,
deterministic, no database). Conversation resources return codes only — not *_label fields.
Resource field status on conversations maps to the conversation_status catalog below.
Conversation status
| Code | Label | Description |
|---|---|---|
pending | Pending | Accepted but not yet dispatched. |
dispatched | Dispatched | Sent to the agent / telephony worker. |
in_progress | In Progress | Customer connected; call active. |
completed | Completed | Lifecycle ended successfully. |
failed | Failed | Failed during lifecycle. |
escalated | Escalated | Handed off / transferred to a human. |
dispatch_failed | Dispatch Failed | Synchronous dispatch failed; no lifecycle events. |
Webhooks: conversation.dispatched, conversation.connected, conversation.ended, conversation.failed.
Outcomes
Partner field outcome (e.g. NO_ANSWER, SUCCESS, CALLBACK). Full list: reference endpoint outcomes section.
Dispositions
Agent Desktop wrap-up codes stored as metrics.disposition.code (e.g. wrong_number). Not a top-level conversation DTO field. Catalog: reference dispositions.
HTTP / envelope errors
Problem error.code values such as unauthorized, validation_error, rate_limited. See Auth conventions and reference errors.
Webhook registration errors (400)
Creating or updating /webhook-endpoints rejects invalid contract fields with HTTP 400 Bad Request (not silent remap). Envelope still uses error.code + error.detail.
| HTTP | Code | When |
|---|---|---|
400 | invalid_filter_field |
Filter field is not supported (v1 allows agent.id only).
|
400 | invalid_filter_operator |
Operator not in eq | neq | in | not_in.
|
400 | invalid_filter_values | Missing values, wrong arity for eq/neq, or caps exceeded (max 10 filters / 50 values). |
400 | invalid_event |
Unknown event name or wildcard (allowed wildcards: conversation.*, campaign.*, contact.*).
|
400 | invalid_api_version | api_version other than v1.
|
400 | invalid_status | status not active or disabled.
|
422 | validation_error | Malformed JSON body, missing URL, or non-http(s) URL. |
404 | not_found | Webhook endpoint or delivery id not found for this tenant. |
502 | bad_gateway | POST …/test could not deliver to your URL (transport error or non-2xx).
|
Public webhook data.conversation.status uses the conversation status codes above (
dispatched, in_progress, completed, failed, …). Govern Filters (Attribute / Operator / Values) builds filters[]; catalog: GET /webhook-filter-metadata. See Receive webhooks.
Reports — VS status codes (catalog v1)
Product reporting uses this separate VS catalog with Status Code, Call Status, Call Result, and Status Description. Source: Core internal/reports/statuscodes.go.
These codes are not returned on /api/external/v1/conversations or GET /reference/statuses. Reserved: VS6xxx (future).
VS2xxx — Successful
| Status Code | Call Status | Call Result | Status Description |
|---|---|---|---|
VS2000 | Completed | Completed | Call completed successfully. |
VS2001 | Completed | Promise To Pay | Customer promised to pay. |
VS2002 | Completed | Interested | Customer expressed interest. |
VS2003 | Completed | Not Interested | Customer is not interested. |
VS2004 | Completed | Callback Scheduled | A callback was scheduled. |
VS2005 | Completed | Transferred | Call was transferred. |
VS2006 | Completed | Verified | Verification completed. |
VS2007 | Completed | Information Collected | Required information was collected. |
VS3xxx — Customer outcomes
| Status Code | Call Status | Call Result | Status Description |
|---|---|---|---|
VS3001 | No Answer | No Answer | Customer did not answer the call. |
VS3002 | Busy | Busy | Customer line was busy. |
VS3003 | Rejected | Rejected | Customer rejected the call. |
VS3004 | Voicemail | Voicemail | Call reached voicemail. |
VS3005 | Disconnected | Call Dropped | Call disconnected unexpectedly. |
VS3006 | Invalid Number | Invalid Number | Phone number is invalid. |
VS3007 | DND | DND | Number is on do-not-disturb. |
VS4xxx — Platform errors
| Status Code | Call Status | Call Result | Status Description |
|---|---|---|---|
VS4001 | Failed | Dispatch Failed | Call could not be dispatched. |
VS4002 | Failed | Media Timeout | Media connection timed out. |
VS4003 | Failed | Network Error | A network error occurred. |
VS4004 | Failed | Provider Error | Telephony provider reported an error. |
VS4005 | Failed | AI Runtime Error | AI runtime failed during the call. |
VS4006 | Failed | STT Error | Speech-to-text failed. |
VS4007 | Failed | TTS Error | Text-to-speech failed. |
VS4008 | Failed | Recording Error | Recording failed. |
VS4009 | Failed | Internal Error | An internal platform error occurred. |
VS5xxx — Business rules
| Status Code | Call Status | Call Result | Status Description |
|---|---|---|---|
VS5001 | Cancelled | Cancelled | Call was cancelled. |
VS5002 | Skipped | Frequency Cap | Skipped due to frequency cap. |
VS5003 | Skipped | Outside Schedule | Skipped outside calling schedule. |
VS5004 | Skipped | Retry Exhausted | Maximum retries reached. |
VS5005 | Skipped | Blacklisted | Number is blacklisted. |
VS5006 | Skipped | Consent Missing | Required consent is missing. |