How to Integrate Retool with Vonage (Nexmo) API

Vonage authentication uses an API Key and API Secret pair for most endpoints. These credentials are found in the Vonage API Dashboard at dashboard.nexmo.com — log in and look for the API Key and API Secret fields on the Getting Started or API Settings page. Both values are alphanumeric strings: the API Key is shorter (6-8 characters) and the API Secret is longer (16+ characters). Copy both values. In Retool, navigate to Resources in the left sidebar and click Add Resource. Select REST API. Name the resource 'Vonage SMS API'. Set Base URL to https://api.nexmo.com. For authentication, Vonage's SMS API accepts credentials as request body parameters rather than HTTP headers — select No Auth in the authentication dropdown, as you will pass api_key and api_secret in each query's body or URL parameters instead. Add a default header Content-Type: application/x-www-form-urlencoded for the SMS API (which uses form-encoded POST bodies). Store your Vonage API Key and Secret in Retool Configuration Variables (Settings → Configuration Variables): VONAGE_API_KEY and VONAGE_API_SECRET, with the secret marked as a Retool secret. For the Messages API (WhatsApp/Viber), a separate resource with Bearer token JWT authentication will be needed — covered in Step 3.

Create the first functional query to send SMS messages via Vonage's SMS API. In any Retool app, open the Code panel and click Create new query. Select the Vonage SMS API Resource. Set Method to POST and Path to /sms/json. The SMS API uses JSON request bodies (despite the /sms/json path suggesting otherwise for URL-encoded forms — the API accepts both). Set Body Type to JSON and configure the body: api_key → {{ retoolContext.configVars.VONAGE_API_KEY }}, api_secret → {{ retoolContext.configVars.VONAGE_API_SECRET }}, to → a test phone number in E.164 format (e.g., 14155551234 without the + prefix, or with it — Vonage accepts both), from → your Vonage virtual number (also in E.164 format), text → {{ smsTextInput.value || 'Test message from Retool' }}. Click Run to send a test SMS to your own phone number. A successful response returns a JSON object with messages[0].status equal to '0' (success), a message-id, and remaining-balance. Vonage uses status code '0' for success (not HTTP 200-level status codes) — status codes 1-9 indicate specific error conditions. Create a Transformer on the query to extract the relevant fields: status, message-id, remaining-balance, and a human-readable status label based on the numeric status code.

1// Vonage SMS API query body
2{
3  "api_key": "{{ retoolContext.configVars.VONAGE_API_KEY }}",
4  "api_secret": "{{ retoolContext.configVars.VONAGE_API_SECRET }}",
5  "to": "{{ recipientPhone.value }}",
6  "from": "{{ retoolContext.configVars.VONAGE_FROM_NUMBER }}",
7  "text": "{{ smsMessageText.value }}"
8}
9
10// Transformer: normalize Vonage SMS response
11const STATUS_LABELS = {
12  '0': 'Delivered', '1': 'Throttled', '2': 'Missing param',
13  '3': 'Invalid param', '4': 'Invalid credentials', '5': 'Internal error',
14  '6': 'Invalid message', '7': 'Number barred', '9': 'Partner quota exceeded'
15};
16const msg = data?.messages?.[0] || {};
17return {
18  status: msg.status,
19  status_label: STATUS_LABELS[msg.status] || `Unknown (${msg.status})`,
20  message_id: msg['message-id'],
21  to: msg.to,
22  remaining_balance: msg['remaining-balance'],
23  success: msg.status === '0'
24};

Vonage's unified Messages API (v1) uses a different authentication method than the SMS API — it requires a JWT (JSON Web Token) signed with an application private key. To set this up, first create a Vonage Application in the Vonage Dashboard: navigate to Your Applications → Create a new application. Enable the Messages capability and provide webhook URLs for inbound and status callbacks (you can use a temporary placeholder URL like https://example.com/inbound for now). Generate a public/private key pair — the Dashboard will download the private key as a .pem file. Note the Application ID. JWT generation for Vonage requires signing a payload with the private key using RS256 algorithm. For Retool, the most practical approach is to generate a long-lived JWT (maximum 24 hours) using Vonage's online JWT generator tool at developer.vonage.com/jwt-generator, paste the JWT into a Retool Configuration Variable VONAGE_MESSAGES_JWT, and use a Retool Workflow to refresh it daily. Create a second Retool Resource named 'Vonage Messages API'. Set Base URL to https://api.nexmo.com/v1. Under Authentication, select Bearer Token and enter {{ retoolContext.configVars.VONAGE_MESSAGES_JWT }}. Add headers: Content-Type: application/json and Accept: application/json.

1// Vonage Messages API query body for WhatsApp message
2{
3  "message_type": "text",
4  "text": "{{ messageTextInput.value }}",
5  "to": "{{ recipientPhone.value }}",
6  "from": "{{ retoolContext.configVars.VONAGE_WHATSAPP_NUMBER }}",
7  "channel": "whatsapp"
8}
9
10// For SMS via Messages API:
11// "channel": "sms"
12// For Viber:
13// "channel": "viber_service", "from": "{{ retoolContext.configVars.VONAGE_VIBER_ID }}"

With both the SMS API and Messages API Resources configured, build the main communications dashboard. Start with a Table component named 'contactsTable' connected to a SQL query that lists customers from your CRM or contacts database, showing name, phone, email, preferred channel (WhatsApp/SMS/Viber), and last_contacted date. Add a search Text Input above the table to filter by name or phone. To the right of the table, add a message composition panel: a Select component for Message Template (if you maintain pre-approved templates in a database), a Text Area for the message body with a character counter for SMS (160 chars per segment), and a channel indicator (showing which channel will be used based on the selected contact's preference). Add a Send Message button that checks the selected contact's preferred channel and triggers the appropriate Retool query — sendSMS (using the SMS API resource) or sendWhatsApp (using the Messages API resource). Below the composition panel, add an Activity Log Table showing the last 50 messages sent (retrieved from a message_log table in your database where each successful send is recorded with: contact_phone, channel, message_text, status, vonage_message_id, sent_at). Add event handlers to the Send button: on success → insert a log entry into message_log, update the contactsTable selectedRow's last_contacted field, show a success notification, and clear the message text area.

1-- Insert message log entry after successful send
2INSERT INTO message_log (
3  contact_phone,
4  channel,
5  message_text,
6  vonage_message_id,
7  status,
8  sent_by,
9  sent_at
10) VALUES (
11  {{ contactsTable.selectedRow.phone }},
12  {{ channelSelect.value }},
13  {{ messageTextArea.value }},
14  {{ sendMessage.data.message_id || sendMessage.data.message_uuid }},
15  'sent',
16  {{ current_user.email }},
17  NOW()
18);

To handle campaign-scale communications, add bulk messaging capabilities to the dashboard. Add a checkbox column to the contactsTable using Retool's Table multi-select feature (enable 'Allow multiple row selection' in the Table settings). When multiple contacts are selected (contactsTable.selectedRows.length > 1), show a Bulk Send panel instead of the single-contact composition panel. In the Bulk Send panel, include a message template Text Area, a preview showing the number of recipients selected, a Select for the sending channel, and a Confirm & Send button. The bulk send logic uses a JavaScript query that iterates over contactsTable.selectedRows and calls the SMS or Messages API query sequentially using await loops with a 100ms delay between calls to respect Vonage's throughput limits (approximately 30 SMS per second on standard accounts). Display a progress Modal showing sent/total/failed counts as the batch progresses. For delivery tracking, if you have configured a Vonage status webhook to post to a Retool Workflow, the Workflow updates the message_log table with delivery receipts. Add a Delivery Status column to the Activity Log Table that shows the latest status (accepted, delivered, failed) and auto-refreshes every 30 seconds using Retool's query polling feature.

1// JavaScript query: bulk send SMS with rate limiting
2const recipients = contactsTable.selectedRows;
3const messageText = bulkMessageText.value;
4const results = [];
5
6for (const contact of recipients) {
7  try {
8    const response = await sendSMS.trigger({
9      additionalScope: {
10        recipientPhone: { value: contact.phone },
11        smsMessageText: { value: messageText }
12      }
13    });
14    results.push({ phone: contact.phone, status: 'sent', message_id: response.message_id });
15  } catch (err) {
16    results.push({ phone: contact.phone, status: 'failed', error: err.message });
17  }
18  // Respect Vonage throughput limit: ~30 SMS/second
19  await new Promise(resolve => setTimeout(resolve, 100));
20}
21
22return results;