# Safe Mode

## Endpoints

- `GET /messaging/projects/{projectId}/safe-mode`: [Get project safe mode](https://docs.polymorfa.com/api/safe-mode/get-project-safe-mode)
- `GET /messaging/{session}/safe-mode`: [Get session safe mode](https://docs.polymorfa.com/api/safe-mode/get-session-safe-mode)
- `PUT /messaging/projects/{projectId}/safe-mode`: [Update project safe mode](https://docs.polymorfa.com/api/safe-mode/update-project-safe-mode)
- `PUT /messaging/{session}/safe-mode`: [Update session safe mode](https://docs.polymorfa.com/api/safe-mode/update-session-safe-mode)

## The project Safe Mode object

### Attributes

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `ceiling` (object, required). Structured ceiling values for this native project safe mode.
  - `presence` (string, required). Specifies presence for this ceiling. Values: `dark`, `online_while_sending`, `online_hours`.
  - `typing` (string, required). Specifies typing for this ceiling. Values: `off`, `before_text`, `before_all`.
  - `reads` (string, required). Specifies reads for this ceiling. Values: `off`, `replied_chats`, `all_inbound`.
  - `pacing` (string, required). Specifies pacing for this ceiling. Values: `off`, `jittered`, `conversation`.
  - `onlineStart` (integer, required, range 0–23). Specifies online start for this ceiling.
  - `onlineEnd` (integer, required, range 0–23). Specifies online end for this ceiling.
- `entitled` (boolean, required). Whether entitled.
- `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native project safe mode.
```json
{
  "projectId": "00000000-0000-4000-8000-000000000000",
  "ceiling": {
    "presence": "dark",
    "typing": "off",
    "reads": "off",
    "pacing": "off",
    "onlineStart": 0,
    "onlineEnd": 0
  },
  "entitled": true,
  "entitlementReason": "string"
}
```

## The number Safe Mode object

### Attributes

- `session` (string, required). Identifier of the connected Polymorfa session.
- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
- `project` (object, required). Structured project values for this native session safe mode.
  - `presence` (string, required). Specifies presence for this project. Values: `dark`, `online_while_sending`, `online_hours`.
  - `typing` (string, required). Specifies typing for this project. Values: `off`, `before_text`, `before_all`.
  - `reads` (string, required). Specifies reads for this project. Values: `off`, `replied_chats`, `all_inbound`.
  - `pacing` (string, required). Specifies pacing for this project. Values: `off`, `jittered`, `conversation`.
  - `onlineStart` (integer, required, range 0–23). Specifies online start for this project.
  - `onlineEnd` (integer, required, range 0–23). Specifies online end for this project.
- `override` (object, required). Structured override values for this native session safe mode.
  - `presence` (string, required). Specifies presence for this override. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
  - `typing` (string, required). Specifies typing for this override. Values: `inherit`, `off`, `before_text`, `before_all`.
  - `reads` (string, required). Specifies reads for this override. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
  - `pacing` (string, required). Specifies pacing for this override. Values: `inherit`, `off`, `jittered`, `conversation`.
- `effective` (object, required). Structured effective values for this native session safe mode.
  - `presence` (string, required). Specifies presence for this effective. Values: `dark`, `online_while_sending`, `online_hours`.
  - `typing` (string, required). Specifies typing for this effective. Values: `off`, `before_text`, `before_all`.
  - `reads` (string, required). Specifies reads for this effective. Values: `off`, `replied_chats`, `all_inbound`.
  - `pacing` (string, required). Specifies pacing for this effective. Values: `off`, `jittered`, `conversation`.
  - `onlineStart` (integer, required, range 0–23). Specifies online start for this effective.
  - `onlineEnd` (integer, required, range 0–23). Specifies online end for this effective.
- `applied` (object, required, nullable). Structured applied values for this native session safe mode.
  - `observedAt` (string, required). ISO 8601 timestamp when Polymorfa observed this state.
  - `presence` (string, required, nullable). Specifies presence for this applied.
  - `typing` (string, required, nullable). Specifies typing for this applied.
  - `reads` (string, required, nullable). Specifies reads for this applied.
  - `pacing` (string, required, nullable). Specifies pacing for this applied.
- `mismatch` (boolean, required). Whether mismatch.
- `entitled` (boolean, required). Whether entitled.
- `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native session safe mode.
```json
{
  "session": "string",
  "projectId": "00000000-0000-4000-8000-000000000000",
  "project": {
    "presence": "dark",
    "typing": "off",
    "reads": "off",
    "pacing": "off",
    "onlineStart": 0,
    "onlineEnd": 0
  },
  "override": {
    "presence": "inherit",
    "typing": "inherit",
    "reads": "inherit",
    "pacing": "inherit"
  },
  "effective": {
    "presence": "dark",
    "typing": "off",
    "reads": "off",
    "pacing": "off",
    "onlineStart": 0,
    "onlineEnd": 0
  },
  "applied": {
    "observedAt": "string",
    "presence": "string",
    "typing": "string",
    "reads": "string",
    "pacing": "string"
  },
  "mismatch": true,
  "entitled": true,
  "entitlementReason": "string"
}
```

## Get project safe mode

`GET https://api.polymorfa.com/messaging/projects/{projectId}/safe-mode` (Messaging API)

Required permission: `sessions:read`

**Required scope:** `sessions:read`

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Request

```bash
curl "https://api.polymorfa.com/messaging/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Project Safe Mode ceiling, and whether the plan includes BanSafe Lite
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `ceiling` (object, required). Structured ceiling values for this native project safe mode.
    - `presence` (string, required). Specifies presence for this ceiling. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this ceiling. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this ceiling. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this ceiling. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this ceiling.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this ceiling.
  - `entitled` (boolean, required). Whether entitled.
  - `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native project safe mode.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "ceiling": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Get session safe mode

`GET https://api.polymorfa.com/messaging/{session}/safe-mode` (Messaging API)

Required permission: `sessions:read`

**Protocols:** Linked Device API

**Required scope:** `sessions:read`

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.

### Request

```bash
curl "https://api.polymorfa.com/messaging/<session>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22"
```

### Responses

#### 200

Project ceiling, number override, the effective policy, and whether the plan includes BanSafe Lite
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `project` (object, required). Structured project values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this project. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this project. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this project. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this project. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this project.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this project.
  - `override` (object, required). Structured override values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this override. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this override. Values: `inherit`, `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this override. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this override. Values: `inherit`, `off`, `jittered`, `conversation`.
  - `effective` (object, required). Structured effective values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this effective. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this effective. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this effective. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this effective. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this effective.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this effective.
  - `applied` (object, required, nullable). Structured applied values for this native session safe mode.
    - `observedAt` (string, required). ISO 8601 timestamp when Polymorfa observed this state.
    - `presence` (string, required, nullable). Specifies presence for this applied.
    - `typing` (string, required, nullable). Specifies typing for this applied.
    - `reads` (string, required, nullable). Specifies reads for this applied.
    - `pacing` (string, required, nullable). Specifies pacing for this applied.
  - `mismatch` (boolean, required). Whether mismatch.
  - `entitled` (boolean, required). Whether entitled.
  - `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native session safe mode.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "session": "string",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "project": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "override": {
      "presence": "inherit",
      "typing": "inherit",
      "reads": "inherit",
      "pacing": "inherit"
    },
    "effective": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "applied": {
      "observedAt": "string",
      "presence": "string",
      "typing": "string",
      "reads": "string",
      "pacing": "string"
    },
    "mismatch": true,
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

## Update project safe mode

`PUT https://api.polymorfa.com/messaging/projects/{projectId}/safe-mode` (Messaging API)

Required permission: `sessions:manage`

**Required scope:** `sessions:manage`

Sets the most visible behaviour any number in this project may use. Presence and read receipts are visible to the people this number messages: turning them on makes the number appear online, exposes last-seen subject to the account's privacy settings, and puts blue ticks on incoming messages. Every axis is off by default and only this request changes it.

### Path parameters

- `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.

### Body

- `presence` (string). Specifies presence for this schema. Values: `dark`, `online_while_sending`, `online_hours`.
- `typing` (string). Specifies typing for this schema. Values: `off`, `before_text`, `before_all`.
- `reads` (string). Specifies reads for this schema. Values: `off`, `replied_chats`, `all_inbound`.
- `pacing` (string). Specifies pacing for this schema. Values: `off`, `jittered`, `conversation`.
- `onlineStart` (integer, range 0–23). Specifies online start for this schema.
- `onlineEnd` (integer, range 0–23). Specifies online end for this schema.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/projects/<projectId>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "presence": "dark",
  "typing": "off",
  "reads": "off",
  "pacing": "off",
  "onlineStart": 0,
  "onlineEnd": 0
}'
```

### Responses

#### 200

Project Safe Mode ceiling updated
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `ceiling` (object, required). Structured ceiling values for this native project safe mode.
    - `presence` (string, required). Specifies presence for this ceiling. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this ceiling. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this ceiling. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this ceiling. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this ceiling.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this ceiling.
  - `entitled` (boolean, required). Whether entitled.
  - `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native project safe mode.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "projectId": "00000000-0000-4000-8000-000000000000",
    "ceiling": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 402

`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "billing_error",
    "code": "safe_mode_not_entitled",
    "message": "Safe Mode is not included on this number’s plan.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#safe-mode-not-entitled"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

Stored, but a connected number did not confirm the policy; retry the request
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```

## Update session safe mode

`PUT https://api.polymorfa.com/messaging/{session}/safe-mode` (Messaging API)

Required permission: `sessions:manage`

**Protocols:** Linked Device API

**Required scope:** `sessions:manage`

Sets one number's Safe Mode. Each axis accepts `inherit` to follow the project ceiling. An override may only be equally or more conservative than the ceiling; a more visible value is refused with `safe_mode_exceeds_project_ceiling`.

### Path parameters

- `session` (string, required, min length 1). Identifier of the connected Polymorfa session.

### Body

- `presence` (string). Specifies presence for this schema. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
- `typing` (string). Specifies typing for this schema. Values: `inherit`, `off`, `before_text`, `before_all`.
- `reads` (string). Specifies reads for this schema. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
- `pacing` (string). Specifies pacing for this schema. Values: `inherit`, `off`, `jittered`, `conversation`.

### Request

```bash
curl -X PUT "https://api.polymorfa.com/messaging/<session>/safe-mode" \
  -H "Authorization: Bearer <POLYMORFA_API_KEY>" \
  -H "Polymorfa-Version: 2026-09-22" \
  -H "Content-Type: application/json" \
  -d '{
  "presence": "inherit",
  "typing": "inherit",
  "reads": "inherit",
  "pacing": "inherit"
}'
```

### Responses

#### 200

Number Safe Mode override updated
- `success` (boolean, required). Whether the request succeeded. Values: `true`.
- `data` (object, required). Structured data carried by this object.
  - `session` (string, required). Identifier of the connected Polymorfa session.
  - `projectId` (string (uuid), required, format uuid). Identifier of the Polymorfa project that owns this resource.
  - `project` (object, required). Structured project values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this project. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this project. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this project. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this project. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this project.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this project.
  - `override` (object, required). Structured override values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this override. Values: `inherit`, `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this override. Values: `inherit`, `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this override. Values: `inherit`, `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this override. Values: `inherit`, `off`, `jittered`, `conversation`.
  - `effective` (object, required). Structured effective values for this native session safe mode.
    - `presence` (string, required). Specifies presence for this effective. Values: `dark`, `online_while_sending`, `online_hours`.
    - `typing` (string, required). Specifies typing for this effective. Values: `off`, `before_text`, `before_all`.
    - `reads` (string, required). Specifies reads for this effective. Values: `off`, `replied_chats`, `all_inbound`.
    - `pacing` (string, required). Specifies pacing for this effective. Values: `off`, `jittered`, `conversation`.
    - `onlineStart` (integer, required, range 0–23). Specifies online start for this effective.
    - `onlineEnd` (integer, required, range 0–23). Specifies online end for this effective.
  - `applied` (object, required, nullable). Structured applied values for this native session safe mode.
    - `observedAt` (string, required). ISO 8601 timestamp when Polymorfa observed this state.
    - `presence` (string, required, nullable). Specifies presence for this applied.
    - `typing` (string, required, nullable). Specifies typing for this applied.
    - `reads` (string, required, nullable). Specifies reads for this applied.
    - `pacing` (string, required, nullable). Specifies pacing for this applied.
  - `mismatch` (boolean, required). Whether mismatch.
  - `entitled` (boolean, required). Whether entitled.
  - `entitlementReason` (string, required, nullable). Specifies entitlement reason for this native session safe mode.

Headers:

- `X-RateLimit-Limit` (integer, min 1). Team request quota per rolling minute, when the per-team request limiter applies.
- `X-RateLimit-Remaining` (integer, min 0). Requests left in the per-team quota; zero when this limiter rejects the request.
- `X-RateLimit-Reset` (integer, min 0). Unix timestamp in seconds when the oldest counted request leaves the rolling window, when the per-team request limiter applies. Follow Retry-After on a rejected request.

```json
{
  "success": true,
  "data": {
    "session": "string",
    "projectId": "00000000-0000-4000-8000-000000000000",
    "project": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "override": {
      "presence": "inherit",
      "typing": "inherit",
      "reads": "inherit",
      "pacing": "inherit"
    },
    "effective": {
      "presence": "dark",
      "typing": "off",
      "reads": "off",
      "pacing": "off",
      "onlineStart": 0,
      "onlineEnd": 0
    },
    "applied": {
      "observedAt": "string",
      "presence": "string",
      "typing": "string",
      "reads": "string",
      "pacing": "string"
    },
    "mismatch": true,
    "entitled": true,
    "entitlementReason": "string"
  }
}
```

#### 400

Bad request — request body or params failed validation
- `error` (object, required). Error details returned when the operation fails.
  - `type` (string, required). Type discriminator for this object. Values: `invalid_request_error`, `authentication_error`, `permission_error`, `billing_error`, `conflict_error`, `rate_limit_error`, `api_error`, `upstream_error`.
  - `code` (string, required). Stable machine-readable code for this result. Values: `zero_knowledge_session`, `invalid_parameter`, `invalid_credential`, `entitlement_required`, `gate_limit_reached`, `billing_credit_required`, `addon_required`, `safe_mode_not_entitled`, `warmup_plan_not_entitled`, `method_not_allowed`, `permission_denied`, `missing_scope`, `resource_not_found`, `hms_not_enabled`, `media_fetch_failed`, `resource_gone`, `feature_unavailable`, `stream_cursor_invalid`, `stream_cursor_expired`, `stream_connection_limit_reached`, `state_conflict`, `team_deletion_scheduled`, `hybrid_choice_required`, `hybrid_group_linked_devices_unavailable`, `terms_acceptance_required`, `terms_activation_blocked`, `idempotency_conflict`, `idempotency_in_progress`, `idempotency_outcome_unknown`, `idempotency_replay_unavailable`, `call_claimed`, `call_not_ringing`, `connection_limit`, `unsupported_for_connection`, `call_permission_required`, `invalid_sip_trunk`, `calls_disabled`, `call_recipient_opted_out`, `call_destination_blocked`, `call_permission_request_limited`, `call_permission_granted`, `call_opt_out_limit`, `number_restricted`, `sip_trunk_in_use`, `sip_trunk_revision_conflict`, `sip_trunk_limit`, `sip_unavailable`, `voice_not_enabled`, `provider_credential_invalid`, `provider_unavailable`, `asset_not_ready`, `voice_asset_in_use`, `voice_asset_revision_conflict`, `voice_unavailable`, `rate_limit_exceeded`, `internal_error`, `operation_not_supported`, `upstream_failure`, `service_unavailable`, `credential_verification_unavailable`, `session_not_ready`, `command_dispatch_failed`, `result_unknown`, `parent_bsuid_not_supported`, `recipient_not_on_whatsapp`, `conversation_window_closed`, `template_not_approved`, `media_too_large`, `whatsapp_rate_limited`, `new_chat_limit_reached`, `marketing_disabled_on_cloud_api`, `whatsapp_account_restricted`, `whatsapp_authorization_required`, `whatsapp_payment_method_required`, `whatsapp_number_not_registered`, `bansafe_suspended`, `bansafe_team_suspended`, `bansafe_cold_blocked`, `bansafe_cold_held`, `bansafe_throttled`, `bansafe_daily_allowance_reached`, `bansafe_accounting_unavailable`, `bansafe_send_outcome_unknown`, `campaigns_not_entitled`, `campaign_throughput_capped`, `campaign_approval_required`, `campaign_approval_stale`, `campaign_variables_missing`.
  - `message` (string, required). Human-readable message associated with this result.
  - `param` (string, required, nullable). Specifies param for this error.
  - `request_id` (string, required). Matches the X-Request-Id response header. Include it when you contact support.
  - `request_log_url` (string (uri), format uri). Console page that shows this request. Returned only to team and project credentials whose request was logged.
- `data` (string, required, nullable). Always null for a failed request.
- `docs` (string (uri), required, format uri). Specifies docs for this native public error.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Correct the invalid request field.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-parameter"
}
```

#### 401

Missing or invalid authentication token
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_credential",
    "message": "Supply a valid credential.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#invalid-credential"
}
```

#### 402

`safe_mode_not_entitled`: Safe Mode is part of BanSafe Lite, which is not included on this number's plan
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "billing_error",
    "code": "safe_mode_not_entitled",
    "message": "Safe Mode is not included on this number’s plan.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#safe-mode-not-entitled"
}
```

#### 403

Authenticated but not permitted (missing scope or rule violation)
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "permission_error",
    "code": "permission_denied",
    "message": "The credential does not have access to this resource.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#permission-denied"
}
```

#### 404

Resource not found
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_not_found",
    "message": "The resource is unavailable to this caller.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#resource-not-found"
}
```

#### 500

Internal server error
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "An unexpected service failure occurred. Keep the request ID for support.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#internal-error"
}
```

#### 503

Stored, but a connected number did not confirm the policy; retry the request
Same fields as 400.

Headers:

- `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`: described under 200.

```json
{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "A required service is unavailable. Check completion before repeating a write.",
    "param": null,
    "request_id": "5f0c2a8e-3b1d-4c6f-9e2a-7d4b1c8f6a30"
  },
  "data": null,
  "docs": "https://docs.polymorfa.com/api/errors#service-unavailable"
}
```
