Send IllyVoIP SMS from a Bubble backend workflow

Configure an IllyVoIP SMS call in Bubble’s API Connector and invoke it from a controlled backend workflow. Keep the API key private and store a message intent before sending. A browser button can request a permitted action, but it must not let a user choose arbitrary recipients, sender names or unrestricted SMS text.

1. Define the permitted notification

Choose a concrete app event, such as a requested status update. Decide which authenticated user may trigger it, which record owns the recipient and which approved text template is allowed. Enforce those rules in the backend, along with quotas and duplicate prevention. Hiding a button in the page is not an access check.

Prepare an IllyVoIP account key and an allowed SMS sender. You also need Bubble backend workflow/API Connector access for your current plan. Separate development data from production recipients. Initialising an API Connector call can execute the actual request; do not initialise an SMS send casually against a real phone number.

2. Configure the private API Connector call

1. Add an API connection for IllyVoIP. Create a call used as an Action, with method POST, HTTPS host api.illyvoip.com and path /api/v1/sms/messages.
2. Configure X-Api-Key as a secret private header. Keep the call server-side; do not enable a client-side execution option for this authenticated request.
3. Set the content type to application/json and add an Idempotency-Key header whose value is supplied from the persisted backend message intent.
4. Define from, to as an array, and message in the JSON body. Use JSON-safe parameter encoding; dynamic text containing quotes or newlines must not break the body.

{"from":"YOUR_ALLOWED_SENDER","to":["YOUR_AUTHORIZED_NUMBER"],"message":"Your requested update is ready."}

Bubble’s server execution does not by itself make every connector field secret. Mark credential fields Private as instructed by Bubble. Keep the sender constrained to your reviewed configuration, and resolve the recipient from a record the caller is permitted to act on.

3. Initialise the schema without an accidental send

Use the connector’s manual response/schema option when your version offers it, or an isolated mock with the documented response shape. If you choose to initialise against IllyVoIP, treat that as an intentional potentially billable send to an authorised test recipient. Record its key and result so the test does not become an unexplained duplicate later.

The response includes status, accepted queued_message_ids, rejected invalid_numbers and duplicate/replay information. Model those fields separately. Do not simplify the action result to a single boolean called “delivered.”

4. Persist and claim one message intent

Create a backend record for the business event and notification version before dispatch. Store the approved recipient, sender, exact message, stable idempotency key and state. Use an atomic uniqueness/claim mechanism to prevent two workers from creating separate intents for the same event. A search-then-create sequence without concurrency protection can race; use a suitable transactional backend if your Bubble data workflow cannot guarantee the claim.

Generate the key once for that intent. Keys allow 8–128 letters, numbers, dots, colons, underscores or dashes. Reusing a key with changed text or recipients is not an authorised retry. If the business message changes, decide explicitly whether it is a genuinely new notification and create a reviewed new intent.

5. Send from the backend and reconcile uncertainty

1. Authenticate and authorise the request; load the stored intent and current recipient eligibility.
2. Claim the unsent intent once and call the connector action with its frozen values.
3. On acceptance, store the returned message ID and queued state. Handle immediate recipient rejection and content-review errors explicitly.
4. On timeout or an incomplete result, retain the key and body. Reconcile the same request rather than generating a new key and sending again.
5. Use GET /api/v1/sms/messages/status with the returned message_id, or verified webhooks, to update delivery state.

6. Review the user-facing result

Show “queued” or “submitted” when that is what the API confirms. Delivery is a later result and does not prove the recipient read the message. Restrict who can inspect numbers, message text and execution logs. Test a double-click, concurrent triggers, unauthorised record access, invalid recipient and a lost response before enabling a real workflow. Do not retry a deliberate validation or content-review rejection as though it were a temporary network error.

Related guides

• Send an SMS with the IllyVoIP API and track delivery
• Handle HTTP 429 rate-limit responses from the IllyVoIP API
• Troubleshoot IllyVoIP API authentication and permission errors

Reference

Current instructions and technical reference: Bubble API Connector.

Reviewed 12 October 2026 against the current IllyVoIP controls, implementation and applicable references. Available options depend on account permissions and service state.