# How to Integrate Retool with Sinch

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Sinch by adding a REST API Resource with Sinch's Conversation API base URL and your Service Plan ID plus Access Token for authentication. Once configured, build queries to send SMS, RCS, WhatsApp, and MMS messages from a unified Retool interface. Setup takes about 20 minutes and gives your operations team an omnichannel messaging dashboard without managing multiple carrier APIs.

## Why Connect Retool to Sinch?

Sinch's strength is its Conversation API — a single unified interface that routes messages to the correct channel (SMS, RCS, WhatsApp, MMS) based on the recipient's device capabilities and your channel priority settings. This means your Retool integration doesn't need separate resources or query configurations for each messaging channel. One Retool query can send an RCS-rich message to recipients who support it and automatically fall back to SMS for others, all through the same API endpoint.

For operations teams, this omnichannel approach is valuable when building customer notification dashboards, support escalation panels, and bulk messaging tools that need to reach customers regardless of whether they have WhatsApp, RCS capabilities, or just basic SMS. Connecting Sinch to Retool lets you build a unified communication panel where agents see message history across all channels for each contact and can send replies through whatever channel that contact prefers.

Sinch also has strong support for RCS Business Messaging — rich messages with images, carousels, quick-reply buttons, and branded sender IDs that appear directly in the native Android Messages app without requiring a separate app. Building RCS message templates and sending them from Retool is a powerful capability for marketing and customer success teams, and Sinch's API makes this accessible through the same Conversation API endpoint used for standard SMS.

## Before you start

- A Sinch account with a configured project (sign up at sinch.com — free trial available with limited credits)
- A Sinch Conversation API app with at least one channel configured (SMS, RCS, or WhatsApp)
- Your Sinch Project ID and an Access Token (OAuth 2.0) or Service Plan ID + API Token from the Sinch Customer Dashboard
- A Retool account (Cloud or self-hosted) with permission to add Resources
- Phone numbers or sender IDs configured in your Sinch account for the channels you want to use

## Step-by-step guide

### 1. Get your Sinch Conversation API credentials

Log into the Sinch Customer Dashboard at app.sinch.com. Navigate to your project (you may need to create one if this is your first Sinch integration). In the left sidebar, find the Conversation API section — it may be listed under 'Messaging' or 'APIs'.

Sinch's Conversation API uses OAuth 2.0 Bearer tokens for authentication. To generate a token, you need your Project ID and an Access Key (Key ID + Key Secret pair). Navigate to Settings → Access Keys in your project, and click New Key to generate an access key pair. Copy the Key ID and Key Secret — the secret will not be shown again.

To obtain an OAuth access token, you exchange these credentials at Sinch's token endpoint: POST to https://auth.sinch.com/oauth2/token with the Key ID and Key Secret as Basic Auth credentials and grant_type=client_credentials in the form body. The response contains an access_token valid for a limited time (typically 1 hour).

For simpler setup, Sinch's SMS API (separate from Conversation API) also supports direct API key authentication without OAuth. If you only need SMS, you can use the SMS-specific endpoint with a simpler auth model.

Store your Sinch Project ID, Key ID, and Key Secret in Retool configuration variables:
- Navigate to Settings → Configuration Variables
- Create SINCH_PROJECT_ID (not secret)
- Create SINCH_KEY_ID (not secret)
- Create SINCH_KEY_SECRET (mark as secret)

You'll also need to note your Sinch Conversation API App ID — find this in the Conversation API section of your project under 'Apps'. This App ID is required in message send requests to specify which channel configuration and sender to use.

**Expected result:** You have Sinch Project ID, Key ID, and Key Secret stored in Retool configuration variables, and you understand the OAuth token exchange process needed before making Conversation API requests.

### 2. Add a Sinch REST API Resource and configure authentication

Open Retool and go to the Resources tab. Click Add Resource → REST API.

In the configuration form:
- Name: 'Sinch Conversation API'
- Base URL: https://us.conversation.api.sinch.com (for US region) or https://eu.conversation.api.sinch.com (for EU region). The region must match your Sinch project's configured region — check in your Sinch dashboard under project settings.

For authentication, since Sinch uses OAuth 2.0 Bearer tokens that expire hourly, the most practical approach for a Retool integration is to use Custom Auth to automatically obtain and refresh the token.

In the Authentication section, select Custom Auth. Click Add Auth Step. Configure a step that calls the Sinch token endpoint:
- Method: POST
- URL: https://auth.sinch.com/oauth2/token
- Authorization: Basic Auth with {{ environment.variables.SINCH_KEY_ID }} as username and {{ environment.variables.SINCH_KEY_SECRET }} as password
- Body (form): grant_type=client_credentials

In the Set Headers section of the Custom Auth configuration, set the Authorization header to Bearer {{ steps.step1.access_token }} — this injects the obtained token into all subsequent API requests.

If Custom Auth configuration is complex for your setup, an alternative is to manually obtain a token via a one-time setup query and store it in a Retool state variable, then add it as a custom header on your Sinch queries. This is simpler but requires manual token refresh.

Click Save Changes to store the resource.

```
// Alternative: Manual token fetch query
// Method: POST, URL: https://auth.sinch.com/oauth2/token
// Headers: Authorization: Basic <Base64(KeyID:KeySecret)>
// Body (x-www-form-urlencoded):
{
  "grant_type": "client_credentials"
}
// Store result: sinchTokenQuery.data.access_token in a Retool state variable
// Use in other queries: custom header Authorization: Bearer {{ sinchToken.value }}
```

**Expected result:** A Sinch Conversation API Resource appears in your Retool Resources list with OAuth authentication configured. A test query to the messages endpoint returns a valid API response.

### 3. Send a message through Sinch's Conversation API

The Sinch Conversation API's message send endpoint is POST /v1/projects/{project_id}/messages:send. This unified endpoint routes messages to the appropriate channel based on the App configuration and specified channel priority.

Create a new query in the Retool Code panel. Select your Sinch Conversation API resource, set Method to POST, and URL to /v1/projects/{{ environment.variables.SINCH_PROJECT_ID }}/messages:send.

In the Body section, select JSON and construct the message payload. The Conversation API message body has a specific structure:
- app_id: your Sinch Conversation App ID (the channel configuration)
- recipient: a contact ID or channel-specific identity (phone number for SMS, WhatsApp number, etc.)
- message: the message content, which differs by type (text_message, media_message, choice_message for interactive RCS)
- channel_priority_order: the list of channels to try in order

For a simple SMS text message:

For a recipient identified by phone number (rather than a Sinch Contact ID), use the channel_identifier format in the to field.

Bind the message text to a Text Area component and the recipient phone number to a Text Input component in your Retool app. Set the query to Manual trigger mode. Add a Button component with an event handler that triggers this query on click, with a confirmation dialog showing the recipient and message preview.

```
// POST body for Sinch Conversation API message send
// Sends a message through the configured channel (SMS, RCS, WhatsApp)
{
  "app_id": "your-sinch-app-id",
  "recipient": {
    "identified_by": {
      "channel_identities": [
        {
          "channel": "{{ channelSelect.value || 'SMS' }}",
          "identity": "{{ recipientPhoneInput.value }}"
        }
      ]
    }
  },
  "message": {
    "text_message": {
      "text": "{{ messageTextArea.value }}"
    }
  },
  "channel_priority_order": [
    "{{ channelSelect.value || 'SMS' }}"
  ]
}
```

**Expected result:** Entering a recipient phone number and message text, then clicking Send, successfully routes a message through Sinch's Conversation API. The message appears on the recipient's device. The query response includes a message_id and accepted status.

### 4. Query message history and delivery status

Sinch's Conversation API provides a messages listing endpoint for retrieving message history and delivery status. This is useful for building a message history view within your Retool app, showing what was sent, to whom, through which channel, and whether it was delivered.

Create a query with Method GET and URL /v1/projects/{{ environment.variables.SINCH_PROJECT_ID }}/messages. Add query parameters:
- conversation_id: to fetch messages from a specific conversation (optional)
- app_id: your Sinch app ID to filter by channel configuration
- page_size: 50
- channel: filter by specific channel ('SMS', 'RCS', 'WHATSAPP')

The response includes an array of message objects with delivery state information. Create a JavaScript transformer to normalize the response structure for the Table:

Bind the transformed data to a Table component. Configure columns for: message_id, recipient, channel, direction (inbound/outbound), status (delivered, read, failed, pending), created_at, and message text preview.

For real-time delivery monitoring, add a Refresh button that re-runs the messages query and set an auto-refresh interval on the query (configurable in the query's Advanced settings). This gives operations teams visibility into delivery success rates without requiring them to check the Sinch dashboard.

To build a per-contact conversation view, filter the messages query by conversation_id when a contact is selected in your contacts Table. The Sinch Conversation API maintains conversation IDs per contact-channel combination, making it straightforward to show a threaded message history.

```
// JavaScript transformer for Sinch Conversation API messages response
const response = data;
const messages = response.messages || [];

return messages.map(msg => {
  const contact = msg.contact_message || msg.app_message || {};
  const textContent = contact.text_message
    ? contact.text_message.text
    : contact.media_message
      ? '[Media Message]'
      : '[Interactive Message]';

  return {
    message_id: msg.id,
    direction: msg.direction === 'TO_APP' ? 'Inbound' : 'Outbound',
    channel: msg.channel_identity ? msg.channel_identity.channel : 'Unknown',
    recipient: msg.channel_identity ? msg.channel_identity.identity : 'N/A',
    status: msg.delivery_status || msg.state,
    content_preview: textContent ? textContent.substring(0, 100) : 'N/A',
    created_at: msg.accept_time
      ? new Date(msg.accept_time).toLocaleString()
      : 'Unknown'
  };
});
```

**Expected result:** A messages history Table in the Retool app shows recent Sinch messages with delivery status, channel, direction, and content preview. The Table refreshes on demand and shows accurate delivery state for each message.

### 5. Build a bulk messaging Workflow with Sinch

For sending notifications to multiple contacts simultaneously — order status updates, appointment reminders, or operational alerts — use Retool Workflows with a Loop block to send through Sinch without blocking the UI.

Navigate to Workflows in the Retool home page sidebar and click New Workflow. Click Add Trigger and select Webhook (so you can trigger the Workflow from a button in your Retool app by calling its webhook URL with a list of recipients).

Add a Resource Query block to fetch the target contacts from your database. Write a SQL query that returns the recipients and their phone numbers based on a segment or filter criteria.

Add a Loop block. Set the Loop type to 'Sequential' to avoid Sinch rate limits, or 'Parallel (batched)' with a small batch size (5-10) for faster delivery with controlled concurrency. Inside the loop, add a Resource Query block connected to your Sinch Conversation API resource to send the message to each contact.

Add an error handling block that catches failed sends and logs them to a failed_sends database table for retry.

After the loop completes, add a final Resource Query block that generates a summary report: total sent, total failed, and average send time. Store this in a campaign_results table in your database.

In your Retool app, add a 'Send Bulk Message' button that triggers the Workflow via its webhook URL, passing the segment ID and message content as JSON in the request body.

```
// JavaScript Code block in Retool Workflow
// Constructs the Sinch message payload for each contact in the loop
const contact = currentItem; // current loop iteration contact

const messageBody = {
  app_id: 'your-sinch-app-id',
  recipient: {
    identified_by: {
      channel_identities: [
        {
          channel: 'SMS',
          identity: contact.phone_number
        }
      ]
    }
  },
  message: {
    text_message: {
      // Reference the message template from the workflow trigger payload
      text: startTrigger.data.message_template
        .replace('{{name}}', contact.first_name)
        .replace('{{order_id}}', contact.order_id || '')
    }
  },
  channel_priority_order: ['SMS']
};

return messageBody;
```

**Expected result:** The Workflow successfully loops through all target contacts and sends each a Sinch message. Failed sends are logged to the database. A campaign result summary is stored with total sent, failed, and timing data.

## Best practices

- Store Sinch Key ID and Key Secret in Retool configuration variables marked as secret — the Key Secret in particular must never be exposed to the browser.
- Implement OAuth token refresh using a Retool Workflow that runs every 50 minutes to maintain a valid access token — expired tokens cause all Sinch queries to fail with 401 errors.
- Use the channel_priority_order array to specify fallback channels — for example, ['RCS', 'SMS'] sends as RCS where supported and falls back to SMS for devices without RCS capability, maximizing message reach.
- Set all Sinch message send queries to Manual trigger mode — messages should only send when an operator explicitly clicks Send, not on every component change or app load.
- Include confirmation dialogs with a preview of the recipient and message content before triggering send queries — SMS and messaging credits are consumed on send and cannot be recovered for messages already delivered.
- Log all outbound messages to your own database immediately after successful send, including the Sinch message_id, recipient, channel, and timestamp — this creates a queryable history independent of Sinch's API pagination.
- For bulk messaging campaigns, use sequential Loop blocks in Retool Workflows rather than parallel execution — this respects Sinch's rate limits and provides cleaner per-contact error handling.

## Use cases

### Build an omnichannel customer notification panel

Create a Retool dashboard that allows support agents to send messages to customers across SMS, WhatsApp, and RCS from a single interface. When an agent selects a customer record and chooses a channel, the message is routed through Sinch's Conversation API to the appropriate channel. Show message history across all channels for each contact in a unified timeline view. Include templates for common notification types (order updates, appointment reminders, account alerts).

Prompt example:

```
Build a Retool customer messaging panel. Fetch customer records from the PostgreSQL database and show them in a left Table. When a customer is selected, show their contact info and a message history Table populated from the messages table. Add a Form with a Text Area for message content, a Select for channel (sms, rcs, whatsapp), and a Send button that calls Sinch's Conversation API. On send success, write the message to the messages table and refresh the history.
```

### Create an RCS campaign dashboard with delivery tracking

Build a Retool campaign management tool for sending RCS business messages with rich content (images, buttons, carousels) to customer segments. Allow marketing managers to select a customer segment from the database, compose or select an RCS message template, preview the rich content, and send to the segment. Show delivery reports broken down by status (delivered, read, failed) and by RCS vs. SMS fallback ratio. Track engagement metrics for messages with interactive elements.

Prompt example:

```
Create a Retool RCS campaign panel. Show customer segments from the segments table in a Select. Add a Template Select with predefined RCS message templates stored in a templates table. Include a preview panel showing the rich message content. A 'Send Campaign' button triggers a Retool Workflow that loops through customers in the segment and sends each one a Sinch Conversation API message. Show a results Table with per-contact delivery status refreshed every 30 seconds.
```

### Build a Sinch message delivery monitoring dashboard

Create an operational dashboard that monitors Sinch message delivery status across all channels and SMS routes. Show delivery rates, failure rates, and average delivery latency broken down by channel and country. Alert when delivery failure rates exceed thresholds. Include a drill-down view that shows individual messages in the failed or pending status so operators can identify patterns and troubleshoot delivery issues.

Prompt example:

```
Build a Retool Sinch monitoring dashboard. Query the Sinch Conversation API messages endpoint filtered to the last 24 hours. Show overall stats: total messages, delivery rate percentage, failure count, and average latency as Stat components. Below, show a Bar Chart of message volume by channel (sms, rcs, whatsapp). Show a Table of failed messages with recipient, channel, error code, and timestamp. Add a Refresh button and auto-refresh every 5 minutes.
```

## Troubleshooting

### Sinch API returns 401 Unauthorized on Conversation API requests

Cause: The OAuth access token has expired (tokens are typically valid for 1 hour), the token was not correctly obtained from the auth endpoint, or the Authorization header format is incorrect.

Solution: Re-run your token fetch query to obtain a fresh access token. Verify the Authorization header is formatted as 'Bearer ' followed by the token (with a space between Bearer and the token). If using Custom Auth in the resource, check the token extraction path — Sinch returns the token in the access_token field of the JSON response. For long-running Retool apps, implement automatic token refresh using a Retool Workflow that runs every 50 minutes.

### Message send returns 404 with 'App not found' or 'Project not found'

Cause: The project ID or app ID in the request URL or body is incorrect, or the resource base URL uses the wrong Sinch region (US vs. EU).

Solution: Verify the project ID in your Sinch dashboard matches the SINCH_PROJECT_ID configuration variable. Check that the app_id in the message body matches a Conversation API app configured in your Sinch project. Confirm the base URL region (us.conversation.api.sinch.com vs. eu.conversation.api.sinch.com) matches your project's configured region.

### SMS messages are sent but recipient receives nothing or a generic SMS sender ID

Cause: Your Sinch account may not have an approved sender ID for the destination country, or the 'from' number in the app configuration is not set up for the destination country's regulatory requirements.

Solution: Check your Sinch Conversation API app's channel configuration in the dashboard. SMS sender IDs require country-specific registration in many regions. For unregistered sender IDs, Sinch falls back to a shared short code, which may be blocked by carriers in some countries. Register a dedicated long code or toll-free number in your Sinch account for countries where dedicated sender IDs are required.

### RCS messages fall back to SMS for all recipients even on Android devices

Cause: RCS Business Messaging requires carrier network support and RCS capability registration. If your Sinch app's RCS configuration is not fully approved or the sender is not RCS-enabled, all messages fall back to SMS.

Solution: Check your Sinch dashboard for the RCS channel status in your Conversation API app. RCS Business Messaging requires a separate approval process and sender verification through Sinch. Contact Sinch support to verify your RCS sender registration status. During the approval period, test RCS functionality using Sinch's test mode with approved test device numbers.

## Frequently asked questions

### Does Sinch have a native Retool connector?

No. Sinch connects to Retool via a generic REST API Resource. You configure the resource with the Sinch Conversation API base URL and OAuth 2.0 Bearer token authentication. The Conversation API provides a unified endpoint for all Sinch channels — SMS, RCS, WhatsApp, MMS — so a single Retool resource handles all message types.

### What is the difference between Sinch's SMS API and Conversation API?

Sinch offers multiple API products. The SMS API is a simpler, older API specifically for SMS sending with basic API key authentication. The Conversation API is a newer, unified API that supports SMS, RCS, WhatsApp, MMS, Telegram, and other channels through a single endpoint, with contact management, conversation threading, and channel fallback logic. For new Retool integrations, the Conversation API is recommended as it provides all channels through one resource configuration.

### Can Retool receive incoming Sinch messages?

Retool cannot directly receive incoming webhooks, but you can configure Sinch to send incoming message webhooks to a Retool Workflow webhook endpoint. Set up a Retool Workflow with a Webhook trigger, copy the generated webhook URL, and register it as your Sinch webhook endpoint in the Conversation API app settings. Incoming messages from customers will then trigger the Workflow, which can process the message, save it to your database, and optionally send a notification to your team.

### How does Sinch's RCS compare to SMS for Retool messaging use cases?

RCS (Rich Communication Services) allows Sinch messages to include images, carousels, quick-reply buttons, and branded sender IDs on compatible Android devices, appearing in the native Messages app without requiring a separate app installation. For Retool operational use cases like appointment reminders or order updates, RCS provides significantly better user experience — recipients can tap quick-reply buttons instead of typing responses. SMS falls back automatically for recipients without RCS capability. The Sinch Conversation API handles this routing transparently when you specify ['RCS', 'SMS'] in channel_priority_order.

---

Source: https://www.rapidevelopers.com/retool-integrations/sinch
© RapidDev — https://www.rapidevelopers.com/retool-integrations/sinch