Sinch

Log in to the Sinch Customer Dashboard at portal.sinch.com. Navigate to your project (or create a new one) and click 'Access Keys' in the left sidebar. Click 'New Key', give it a descriptive name like 'Bubble Integration', and copy both the Key ID and the Key Secret — the Key Secret is shown only once, so save it somewhere secure before closing the modal. Next, navigate to the 'Conversation' section in the left sidebar and click 'Apps'. Click 'Create new app', give it a name, and select your project region — choose US if your users are in the Americas, or EU if they are in Europe, because the base URL you use in your API Connector must match the region you select here. After creating the app, add at least one channel: click 'Add channel', select SMS, and follow the prompts to link a Sinch phone number. If you have a WhatsApp Business account connected to Sinch, you can add that channel too. Once the Conversation App is created, copy the App ID displayed on the app detail page. You will need this ID in the request body of every messages:send call. Your project ID is visible in the URL when viewing your project in the dashboard — also copy this, as it appears in the Conversation API endpoint path. Note your region's base URL: US is https://us.conversation.api.sinch.com/v1 and EU is https://eu.conversation.api.sinch.com/v1. Using the wrong region's URL with a valid project ID returns a 404 error that can be confusing to debug — make sure you use the URL that matches the region you selected when creating your Conversation App.

Open your Bubble app editor and click the 'Plugins' tab in the left sidebar. If you do not already have the API Connector installed, click 'Add plugins', search for 'API Connector', and install the one by Bubble. Once installed, click 'API Connector' to open its configuration panel. Click 'Add another API' and name this group 'Sinch Auth'. Do NOT add any shared headers to this group — the Sinch token endpoint uses Basic authentication with your Key ID and Key Secret, not a Bearer token. Instead, at the call level, set the authentication to 'Basic auth' and enter your Key ID as the Username and your Key Secret as the Password. Click the 'Private' checkbox next to the Password field so the Key Secret is marked private and will never be sent to the browser. Add a new call within this group. Name it 'Get Access Token'. Set the method to POST and the URL to https://auth.sinch.com/oauth2/token. Under the request body, add a parameter with key 'grant_type' and value 'client_credentials' and mark the type as 'text' (not 'dynamic'). Set 'Use as' to 'Action'. Click 'Initialize call'. This sends an actual request to Sinch's auth server using your credentials and parses the response shape so Bubble knows the structure. You should receive a JSON response containing an 'access_token' field and an 'expires_in' field (typically 3600). Once Bubble shows the detected fields, click 'Save'. If the initialization fails with a 401, double-check that your Key ID is entered as the Username and Key Secret as the Password — not vice versa, which is a common mistake.

1{
2  "method": "POST",
3  "url": "https://auth.sinch.com/oauth2/token",
4  "authentication": "Basic auth",
5  "username": "<Your Key ID>",
6  "password": "<Your Key Secret — mark PRIVATE>",
7  "body": {
8    "grant_type": "client_credentials"
9  }
10}

Back in the API Connector panel, click 'Add another API' to create a second group — or you can add a second call under a new 'Sinch Messages' group for organization. Name the group 'Sinch Messages'. Add a shared header: key 'Authorization', value 'Bearer [access_token]'. Mark this header as 'Private' by checking the Private checkbox, and set the type to 'Dynamic' so you can pass in the actual token value at runtime from your workflow. Add a new call named 'Send Message'. Set the method to POST and the URL to: https://us.conversation.api.sinch.com/v1/projects/[project_id]/messages:send Replace 'us' with 'eu' if your Conversation App is in the EU region. Mark [project_id] as a dynamic parameter. In the JSON body, add the message structure. Set the body to the JSON shown in the code block below. Mark each field that will be set at runtime as 'Dynamic'. Set 'Use as' to 'Action'. To initialize this call, you need a real access token. Go to your Sinch auth call first, run it manually (you can use a test tool like Postman or open the Initialize call again), copy the access_token value, and paste it temporarily into the Authorization header value for initialization. Also fill in your real project_id, app_id, and a real phone number for recipient. Click 'Initialize call' — this should return a 200 OK with a message_id. Once detected, save the call and remove the hardcoded token value, leaving it as a Dynamic parameter.

1{
2  "method": "POST",
3  "url": "https://us.conversation.api.sinch.com/v1/projects/[project_id]/messages:send",
4  "headers": {
5    "Authorization": "Bearer [access_token -- PRIVATE, DYNAMIC]",
6    "Content-Type": "application/json"
7  },
8  "body": {
9    "app_id": "[app_id]",
10    "recipient": {
11      "identified_by": {
12        "channel_identities": [
13          {
14            "channel": "SMS",
15            "identity": "[phone_e164]"
16          }
17        ]
18      }
19    },
20    "message": {
21      "text_message": {
22        "text": "[message_text]"
23      }
24    },
25    "channel_priority_order": ["WHATSAPP", "SMS"]
26  }
27}

The Backend Workflow is the critical piece that keeps your Key Secret safe. Open the Bubble editor, navigate to the 'Backend Workflows' section (look for 'Backend Workflows' in the left panel — if you do not see it, go to Settings → API and enable 'This app exposes a Workflow API'). Click 'New API workflow' and name it 'sinch-send-message'. Add the following parameters to this Backend Workflow so it can receive the phone number and message text from your frontend: 'recipient_phone' (text), 'message_text' (text). You may also want to add 'app_id' as a parameter if you have multiple Conversation Apps. Before building the workflow steps, first go to your Data tab and create a new data type called 'Sinch Token' with two fields: 'access_token' (text) and 'expires_at' (date). This is where you will cache the token to avoid fetching a new one on every message send. Back in the Backend Workflow editor, add the first action: check if a valid cached token exists. Use 'Search for Sinch Tokens' and filter where expires_at is greater than 'Current date/time'. If a token is found, use it directly in the next step. If no valid token is found, trigger the 'Get Access Token' API action (your Sinch Auth call). After the token call, add a 'Create a new Sinch Token' step: set access_token to the result's access_token field, and set expires_at to 'Current date/time + 50 minutes' (using a slightly shorter window than the actual 60-minute expiry as a safety buffer). Finally, add the 'Send Message' API action (your Sinch Messages call), passing in the access_token (from the cached or newly fetched token), the project_id (stored as a constant in your workflow or as an App setting), the app_id, the recipient phone number from the workflow parameter, and the message text. This entire chain runs server-side — your Key Secret never leaves Bubble's servers. Note: Backend Workflows require Bubble's Starter plan ($32/month) or higher. If you see a message that API Workflows are not enabled, you need to upgrade your plan.

Now that the Backend Workflow exists, you can trigger it from anywhere in your Bubble app. The most common pattern is a button click — for example, a 'Send notification' button on an admin dashboard or an automatic trigger on a data change event. To trigger from a button: select the button element, click the 'Start/Edit Workflow' icon in the Properties panel. Add an action and search for 'Schedule API Workflow'. You will see your 'sinch-send-message' workflow listed. Select it and pass in the required parameters: the recipient's phone number (from an input element or a database field on the current page) and the message text. For automatic triggers based on data changes, use a 'Schedule API Workflow' action inside a Workflow that fires when a record changes — for example, when an Order's status changes to 'Shipped', schedule the sinch-send-message workflow with the order's customer phone number and a message like 'Your order has shipped!'. If you want the message send to happen immediately (not scheduled), you can use 'Schedule API Workflow' with 'Schedule for: Current date/time', which runs it as soon as the workflow is triggered. The distinction between running 'Schedule API Workflow' (always async) and a direct API call action is that Backend Workflows are always async — the frontend does not wait for a response before continuing, which is usually the desired behavior for message sending.

After triggering a test message send from Bubble, open your Sinch Customer Dashboard at portal.sinch.com and navigate to Conversation → Logs. Select your Conversation App from the dropdown and look for the message you just sent. The log shows the message ID, the channel it was delivered on, and the delivery status (DELIVERED, QUEUED, FAILED). If the status is FAILED, click on the log entry to see the failure reason. Common reasons include: incorrect phone number format (Sinch requires E.164 format: +12125551234 with the plus sign and country code), channel configuration errors (WhatsApp sender not approved), or an expired token that was not refreshed correctly. To verify your token caching is working correctly, trigger two message sends within a minute of each other and check your Sinch Token data type in Bubble's Data tab. You should see only one token record (or the same token being reused), not two new ones being created on each send. If you see a new token created on each send, check your expiry comparison logic in the Backend Workflow. Check that your phone number field is storing numbers in E.164 format. If users enter numbers in national format (e.g., (212) 555-1234), you need to clean and format them before passing to Sinch. A simple JavaScript action in the Toolbox plugin can strip non-numeric characters and prepend the country code, or you can use a Bubble expression to format the value.