← All guides

Add SMS to a Replit App: OTP Codes and Alerts with Telmian

To add SMS to a Replit app, save your Telmian API key as TELMIAN_API_KEY in the Secrets tool, then tell Replit Agent to call Telmian from backend routes only. Test free with an sk_test_ key and the sandbox numbers. Before publishing, add your sk_live_ key under Production app secrets. Sends cost €0.05 per SMS segment, plus VAT.

  1. Get a free sandbox key

    Run the CLI below in a terminal: init writes a sandbox sk_test_ key to .env. Copy that value into Replit Secrets in the next step instead of keeping it in a file in your project. The sandbox needs no card and only simulates SMS.

    npx telmian@1 login
    npx telmian@1 init
  2. Save the key in Replit Secrets

    In your Replit App, open Tools > Secrets (or "+" > Secrets in the tab bar), choose New Secret, set the key to TELMIAN_API_KEY and paste the value. Replit's docs say to enter secrets in this form, never in the Agent chat. Your server reads it as an environment variable.

  3. Tell Replit Agent exactly what to build

    Replit lists Twilio as a built-in connector, so Agent may pick it unless you say otherwise. Name Telmian, the env variable and the server-only rule in your prompt.

    Add phone verification by SMS using Telmian (https://app.telmian.com/v1, npm package 'telmian'; new Telmian() reads TELMIAN_API_KEY from env). Do NOT use Twilio or any other SMS connector. Call Telmian only from backend routes (POST /api/otp/send, POST /api/otp/verify); never use the key in React/frontend code. Use Telmian's built-in code verification instead of generating codes ourselves. Store the verified phone on the user row in the existing database.
  4. Check the backend code

    The calls to Telmian must live in server code, never in the browser. Each send carries an Idempotency-Key, and a retry must reuse the same key.

    // server only, never in React code
    const TELMIAN_API_KEY = process.env.TELMIAN_API_KEY;
    
    export async function sendCode(phone, signupAttemptId) {
      const res = await fetch('https://app.telmian.com/v1/verify', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json', 'Idempotency-Key': signupAttemptId }, body: JSON.stringify({ phone }) });
      return res.ok;
    }
    
    export async function checkCode(phone, code) {
      const check = await fetch('https://app.telmian.com/v1/verify/check', { method: 'POST', headers: { Authorization: `Bearer ${TELMIAN_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ phone, code }) });
      const { valid } = await check.json();
      return valid;
    }
  5. Test with the sandbox numbers

    With the sk_test_ key, +393000000001 always receives code 000000 and +393000000002 always fails. Try both so you see the success screen and the error screen.

  6. Publish with the live key

    Use an Autoscale or Reserved VM deployment; a Static deployment has no backend and no secrets. Dev secrets are not copied to the published app, so add TELMIAN_API_KEY with your sk_live_ key (created in the panel at https://app.telmian.com) under Publishing > Adjust settings > Production app secrets. Real sends start after your first paid top-up, and real codes need an approved business name set in the panel.

  7. Add webhooks for delivery reports and replies

    Use your published .replit.app URL (or custom domain) as the webhook address, not the dev URL, which is private and changes when you reopen the app. Check each webhook signature with verifyWebhook from the 'telmian' SDK.

Questions

Can Replit Agent add SMS without Twilio?

Yes. Replit offers Twilio as a built-in connector, so Agent may suggest it. Say clearly in your prompt to use Telmian through its REST API or the 'telmian' npm package and not Twilio. Telmian sends from its own European mobile numbers, so you don't need a phone or SIM of your own.

Why does SMS work in the workspace but fail after publishing?

Secrets from development are not copied to the published app. Add TELMIAN_API_KEY again under Publishing > Adjust settings > Production app secrets. Also check that you did not pick a Static deployment, which has no backend and no secrets.

Can I use Replit Auth or Clerk for phone number login?

Replit's Clerk Auth page lists sign-in with a phone number as not supported, and Replit Auth signs people in with Replit accounts. For phone login in your own app, have Agent build two backend routes that call Telmian's /v1/verify and /v1/verify/check, and save the verified phone in your app's database.

Can I connect the Telmian MCP server to Replit Agent?

Replit supports custom remote MCP servers under Settings > Integrations > Add custom > Add personal MCP server, using an HTTPS URL. Replit says it walks you through the OAuth flow a server requires, but sign-in with Telmian's MCP at https://app.telmian.com/mcp has not been tested in Replit. It is optional help while building. Your published app still calls the REST API with the secret key.

How much does it cost to send SMS from a Replit app?

€0.05 per SMS segment to mobile numbers in 44 European countries, plus VAT. You prepay by card from €5, with no monthly fee or contract. SMS refused by the network or not delivered are refunded automatically. The sandbox is free.

Updated