SMS fallback

Every call needs Authorization: Bearer <key>. 7 calls:

• List SMS connections: GET /v1/sms-connections
• Connect an SMS provider account: POST /v1/sms-connections
• Get an SMS connection: GET /v1/sms-connections/:id
• Update an SMS connection: PATCH /v1/sms-connections/:id
• Delete an SMS connection: DELETE /v1/sms-connections/:id
• Send a test text: POST /v1/sms-connections/:id/test
• Verify an SMS connection: POST /v1/sms-connections/:id/verify

List SMS connections

GET /v1/sms-connections

The workspace's own SMS provider accounts for SMS fallback. Auth tokens are never returned.

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
data	object[]
data[].account_sid	string
data[].auth_token_last4	string	Last four characters of the auth token. Up to 4 characters.
data[].compliance_confirmed_at	string (date-time) or null	ISO 8601 timestamp.
data[].compliance_confirmed_by	string (uuid) or null	User who confirmed compliance.
data[].created_at	string (date-time)	ISO 8601 timestamp.
data[].from_numbers	string[]
data[].has_auth_token	boolean
data[].id	string	SMS connection id (smc_...).
data[].inbound_webhook_configured_at	string (date-time) or null	ISO 8601 timestamp.
data[].inbound_webhook_url	string	Where Twilio should send inbound messages and status callbacks.
data[].last_error	string or null
data[].last_verified_at	string (date-time) or null	ISO 8601 timestamp.
data[].messaging_service_sid	string or null
data[].prefix_org_name	boolean	Start SMS fallback texts with the organisation name.
data[].provider	enum	One of: twilio.
data[].status	enum	pending until verified; active when verified; failing when the last check failed; disabled by the workspace. One of: pending, active, failing, disabled.
data[].updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Connect an SMS provider account

POST /v1/sms-connections

Stores the workspace's own Twilio credentials (the token encrypted) and verifies them. SMS fallback needs the connection active, verified and compliance-confirmed. With configure_inbound_webhook: true, bubbl3 also points the Messaging Service's or numbers' inbound webhook at inbound_webhook_url; otherwise nothing in the Twilio account is changed.

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
account_sid	string	Yes	Twilio Account SID.
auth_token	string	Yes	Write-only. Stored encrypted and never returned.
compliance_confirmed	boolean	No	true records that a signed-in user confirmed the account is registered for the messages it will send (A2P 10DLC or toll-free verification). API keys cannot set it.
configure_inbound_webhook	boolean	No	Explicit consent to point the number's or Messaging Service's inbound webhook at bubbl3. Off unless set. Only a signed-in user can set it to true. Default false.
from_numbers	string[]	No	Up to 20 items.
messaging_service_sid	string	No	Twilio Messaging Service SID.
prefix_org_name	boolean	No	Default false.
provider	enum	No	One of: twilio. Default "twilio".

Response 201

Field	Type	Description
account_sid	string
auth_token_last4	string	Last four characters of the auth token. Up to 4 characters.
compliance_confirmed_at	string (date-time) or null	ISO 8601 timestamp.
compliance_confirmed_by	string (uuid) or null	User who confirmed compliance.
created_at	string (date-time)	ISO 8601 timestamp.
from_numbers	string[]
has_auth_token	boolean
id	string	SMS connection id (smc_...).
inbound_webhook_configured_at	string (date-time) or null	ISO 8601 timestamp.
inbound_webhook_url	string	Where Twilio should send inbound messages and status callbacks.
last_error	string or null
last_verified_at	string (date-time) or null	ISO 8601 timestamp.
messaging_service_sid	string or null
prefix_org_name	boolean	Start SMS fallback texts with the organisation name.
provider	enum	One of: twilio.
status	enum	pending until verified; active when verified; failing when the last check failed; disabled by the workspace. One of: pending, active, failing, disabled.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Get an SMS connection

GET /v1/sms-connections/:id

Path parameters

Name	Type	Required	Description
id	string	Yes	SMS connection id (smc_...).

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
account_sid	string
auth_token_last4	string	Last four characters of the auth token. Up to 4 characters.
compliance_confirmed_at	string (date-time) or null	ISO 8601 timestamp.
compliance_confirmed_by	string (uuid) or null	User who confirmed compliance.
created_at	string (date-time)	ISO 8601 timestamp.
from_numbers	string[]
has_auth_token	boolean
id	string	SMS connection id (smc_...).
inbound_webhook_configured_at	string (date-time) or null	ISO 8601 timestamp.
inbound_webhook_url	string	Where Twilio should send inbound messages and status callbacks.
last_error	string or null
last_verified_at	string (date-time) or null	ISO 8601 timestamp.
messaging_service_sid	string or null
prefix_org_name	boolean	Start SMS fallback texts with the organisation name.
provider	enum	One of: twilio.
status	enum	pending until verified; active when verified; failing when the last check failed; disabled by the workspace. One of: pending, active, failing, disabled.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Update an SMS connection

PATCH /v1/sms-connections/:id

Changing the account, token or sender puts the connection back to pending until it is verified again. disabled: true stops SMS fallback; false re-enables it as pending.

Path parameters

Name	Type	Required	Description
id	string	Yes	SMS connection id (smc_...).

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
account_sid	string	No	Twilio Account SID.
auth_token	string	No	Rotates the token. The connection must be verified again.
compliance_confirmed	boolean	No	true records that a signed-in user confirmed the account is registered for the messages it will send (A2P 10DLC or toll-free verification). API keys cannot set it.
disabled	boolean	No	true stops SMS fallback; false re-enables it as pending until verified.
from_numbers	string[]	No	Up to 20 items.
messaging_service_sid	string or null	No	Twilio Messaging Service SID.
prefix_org_name	boolean	No

Response 200

Field	Type	Description
account_sid	string
auth_token_last4	string	Last four characters of the auth token. Up to 4 characters.
compliance_confirmed_at	string (date-time) or null	ISO 8601 timestamp.
compliance_confirmed_by	string (uuid) or null	User who confirmed compliance.
created_at	string (date-time)	ISO 8601 timestamp.
from_numbers	string[]
has_auth_token	boolean
id	string	SMS connection id (smc_...).
inbound_webhook_configured_at	string (date-time) or null	ISO 8601 timestamp.
inbound_webhook_url	string	Where Twilio should send inbound messages and status callbacks.
last_error	string or null
last_verified_at	string (date-time) or null	ISO 8601 timestamp.
messaging_service_sid	string or null
prefix_org_name	boolean	Start SMS fallback texts with the organisation name.
provider	enum	One of: twilio.
status	enum	pending until verified; active when verified; failing when the last check failed; disabled by the workspace. One of: pending, active, failing, disabled.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Delete an SMS connection

DELETE /v1/sms-connections/:id

Deletes the stored credentials. SMS fallback stops at once. The audit log keeps a record.

Path parameters

Name	Type	Required	Description
id	string	Yes	SMS connection id (smc_...).

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.

Response 200

Field	Type	Description
deleted	enum	One of: true.
id	string	SMS connection id (smc_...).

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.

Send a test text

POST /v1/sms-connections/:id/test

Sends one fixed text ("Test message from <organization> via bubbl3. Reply STOP to opt out.") to to only, through this connection. Signed-in users only. Needs an active, verified, compliance-confirmed connection. Limited to 5 a minute and 20 in any 24 hours per workspace. Refused for numbers that opted out. Nothing is added to the inbox.

Path parameters

Name	Type	Required	Description
id	string	Yes	SMS connection id (smc_...).

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
to	string	Yes	The only number the test text is sent to. The text itself is fixed and names the organisation.

Response 200

Field	Type	Description
id	string	SMS connection id (smc_...).
provider_message_id	string
sent_at	string (date-time)	ISO 8601 timestamp.
status	string
to	string	Phone number in E.164 format.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500, 503. See errors for the shape and codes.

Verify an SMS connection

POST /v1/sms-connections/:id/verify

Checks the credentials and sender with the provider. A success makes the connection active; a failure makes it failing with last_error. configure_inbound_webhook: true also sets the inbound webhook.

Path parameters

Name	Type	Required	Description
id	string	Yes	SMS connection id (smc_...).

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
configure_inbound_webhook	boolean	No	Explicit consent to point the number's or Messaging Service's inbound webhook at bubbl3. Off unless set. Only a signed-in user can set it to true. Default false.

Response 200

Field	Type	Description
account_sid	string
auth_token_last4	string	Last four characters of the auth token. Up to 4 characters.
compliance_confirmed_at	string (date-time) or null	ISO 8601 timestamp.
compliance_confirmed_by	string (uuid) or null	User who confirmed compliance.
created_at	string (date-time)	ISO 8601 timestamp.
from_numbers	string[]
has_auth_token	boolean
id	string	SMS connection id (smc_...).
inbound_webhook_configured_at	string (date-time) or null	ISO 8601 timestamp.
inbound_webhook_url	string	Where Twilio should send inbound messages and status callbacks.
last_error	string or null
last_verified_at	string (date-time) or null	ISO 8601 timestamp.
messaging_service_sid	string or null
prefix_org_name	boolean	Start SMS fallback texts with the organisation name.
provider	enum	One of: twilio.
status	enum	pending until verified; active when verified; failing when the last check failed; disabled by the workspace. One of: pending, active, failing, disabled.
updated_at	string (date-time)	ISO 8601 timestamp.

Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500. See errors for the shape and codes.