Settings
Every call needs Authorization: Bearer <key>. 4 calls:
- Compliance settings:
GET /v1/settings/compliance - Change compliance settings:
PATCH /v1/settings/compliance - My notification settings:
GET /v1/settings/notifications - Change my notification settings:
PATCH /v1/settings/notifications
Compliance settings
GET /v1/settings/compliance
Quiet hours, custom STOP keywords, the opt-out confirmation text and the consent requirement, plus the platform rules around them. Settings apply to the whole organisation.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
built_in_stop_keywords | string[] | |
can_change | boolean | Whether the caller can change these settings: they apply to every workspace in the organisation, so a change needs full compliance access in each one. |
opt_out_confirmation | string | |
platform_quiet_hours | object | |
platform_quiet_hours.end | string | Local time, HH:MM. |
platform_quiet_hours.start | string | Local time, HH:MM. |
quiet_hours | object | |
quiet_hours.end | string | Local time, HH:MM. |
quiet_hours.start | string | Local time, HH:MM. |
require_consent | boolean | Only message contacts whose consent is opted_in. |
sending_limits | object | |
sending_limits.identical_text_max_per_day | integer | From 1 to 9007199254740991. |
sending_limits.new_contact_window_days | integer | From 1 to 9007199254740991. |
sending_limits.new_contacts_per_day | integer | From 0 to 9007199254740991. |
sending_limits.new_contacts_per_hour | integer | From 0 to 9007199254740991. |
sending_limits.pre_reply_max_chars | integer | From 1 to 9007199254740991. |
sending_limits.pre_reply_max_messages | integer | From 1 to 9007199254740991. |
sending_limits.reply_ratio_min | number | From 0 to 1. |
sending_limits.sends_per_day | integer | From 0 to 9007199254740991. |
sending_limits.unanswered_streak_pause | integer | From 1 to 9007199254740991. |
sending_limits.warmup_curve | object[] | |
sending_limits.warmup_curve[].from_day | integer | From 1 to 9007199254740991. |
sending_limits.warmup_curve[].new_per_day | integer | From 0 to 9007199254740991. |
sending_limits.warmup_curve[].to_day | integer or null | From 1 to 9007199254740991. |
stop_keywords | string[] |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Change compliance settings
PATCH /v1/settings/compliance
Quiet hours are in each contact's local time and must cover the platform's quiet hours: they can be made longer, never shorter or turned off. STOP keywords are added to the built-in ones. Changes apply to every workspace in the organisation, so the caller needs full compliance access in each one (otherwise 403), and the change is audited in each workspace.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
opt_out_confirmation | string | No | Up to 300 characters. |
quiet_hours | object | No | |
quiet_hours.end | string | Yes | Local time, HH:MM. |
quiet_hours.start | string | Yes | Local time, HH:MM. |
require_consent | boolean | No | |
stop_keywords | string[] | No | Up to 20 items. |
Response 200
| Field | Type | Description |
|---|---|---|
built_in_stop_keywords | string[] | |
can_change | boolean | Whether the caller can change these settings: they apply to every workspace in the organisation, so a change needs full compliance access in each one. |
opt_out_confirmation | string | |
platform_quiet_hours | object | |
platform_quiet_hours.end | string | Local time, HH:MM. |
platform_quiet_hours.start | string | Local time, HH:MM. |
quiet_hours | object | |
quiet_hours.end | string | Local time, HH:MM. |
quiet_hours.start | string | Local time, HH:MM. |
require_consent | boolean | Only message contacts whose consent is opted_in. |
sending_limits | object | |
sending_limits.identical_text_max_per_day | integer | From 1 to 9007199254740991. |
sending_limits.new_contact_window_days | integer | From 1 to 9007199254740991. |
sending_limits.new_contacts_per_day | integer | From 0 to 9007199254740991. |
sending_limits.new_contacts_per_hour | integer | From 0 to 9007199254740991. |
sending_limits.pre_reply_max_chars | integer | From 1 to 9007199254740991. |
sending_limits.pre_reply_max_messages | integer | From 1 to 9007199254740991. |
sending_limits.reply_ratio_min | number | From 0 to 1. |
sending_limits.sends_per_day | integer | From 0 to 9007199254740991. |
sending_limits.unanswered_streak_pause | integer | From 1 to 9007199254740991. |
sending_limits.warmup_curve | object[] | |
sending_limits.warmup_curve[].from_day | integer | From 1 to 9007199254740991. |
sending_limits.warmup_curve[].new_per_day | integer | From 0 to 9007199254740991. |
sending_limits.warmup_curve[].to_day | integer or null | From 1 to 9007199254740991. |
stop_keywords | string[] |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
My notification settings
GET /v1/settings/notifications
Which events reach you by email and push in this workspace, and your quiet hours (in the organisation’s time zone), when email and push wait. Service emails listed in required always go out.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
Response 200
| Field | Type | Description |
|---|---|---|
events | object | |
quiet_hours | object or null | |
quiet_hours.end | string | Local time, HH:MM. |
quiet_hours.start | string | Local time, HH:MM. |
required | object | Channels that are always on for an event (service emails). |
time_zone | string | The organisation's time zone, which quiet hours use. |
unavailable | enum[] | Events bubbl3 does not send yet; their preferences are kept for later. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.
Change my notification settings
PATCH /v1/settings/notifications
Sets the channels for the events given (others are left as they are) and your quiet hours (null turns them off; equal start and end means none). A required service email can’t be turned off.
Headers
| Name | Type | Required | Description |
|---|---|---|---|
x-workspace-id | string | No | Workspace for session (JWT) callers. API keys carry their own workspace. |
idempotency-key | string | No | Makes the write safe to retry for 24 hours. 1 to 255 printable characters. Keys starting with outreach:, workflow: or agent: are reserved for messages bubbl3 sends itself and are refused with 400. Up to 255 characters. |
Request body
| Field | Type | Required | Description |
|---|---|---|---|
events | object | No | |
quiet_hours | object or null | No | |
quiet_hours.end | string | Yes | Local time, HH:MM. |
quiet_hours.start | string | Yes | Local time, HH:MM. |
Response 200
| Field | Type | Description |
|---|---|---|
events | object | |
quiet_hours | object or null | |
quiet_hours.end | string | Local time, HH:MM. |
quiet_hours.start | string | Local time, HH:MM. |
required | object | Channels that are always on for an event (service emails). |
time_zone | string | The organisation's time zone, which quiet hours use. |
unavailable | enum[] | Events bubbl3 does not send yet; their preferences are kept for later. |
Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.