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, the consent requirement and the optional cold contact limit, 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. |
cold_new_contacts_limit | integer | The highest cold_new_contacts_per_day accepts: the platform’s default daily new-contact cap. From -9007199254740991 to 9007199254740991. |
cold_new_contacts_per_day | integer or null | An optional lower daily limit for new cold contacts (from outbound tools) per line. Null (the default) means off: cold contacts share the line’s normal new-contact limit. From 1 to 9007199254740991. |
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. The optional cold contact limit is off (null) unless set; when set it is from 1 to cold_new_contacts_limit, and null turns it off. 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 |
|---|---|---|---|
cold_new_contacts_per_day | integer or null | No | An optional lower daily limit for new cold contacts per line, from 1 to cold_new_contacts_limit. Null turns it off, so cold contacts share the line’s normal new-contact limit. From 1 to 9007199254740991. |
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. |
cold_new_contacts_limit | integer | The highest cold_new_contacts_per_day accepts: the platform’s default daily new-contact cap. From -9007199254740991 to 9007199254740991. |
cold_new_contacts_per_day | integer or null | An optional lower daily limit for new cold contacts (from outbound tools) per line. Null (the default) means off: cold contacts share the line’s normal new-contact limit. From 1 to 9007199254740991. |
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.