Skip to main content
Back to blog

QR Code API for SMS, WhatsApp, and Links: Generate Deep-Link QRs Server-Side

Generate PNG QR codes over the API — sms: deep links, prefilled wa.me WhatsApp links, and arbitrary URLs — server-side, 50 to 1024 pixels, with the payload never leaving the platform.

Orbit Editorial Team

Quick answer: Devotel Orbit's QR Code API turns a phone number, a prefilled message, or a plain URL into a scannable image with one authenticated GET. Three routes under /api/v1/qr cover the surface: /qr/generate for arbitrary text or URLs, /qr/whatsapp for a WhatsApp click-to-chat deep link (https://wa.me/<number>?text=…), and /qr/sms for a native SMS deep link (sms:<number>?body=…). Every call returns raw image/png bytes by default, or a base64 data URL inside the standard JSON envelope when you pass format=json. The image renders on the platform itself — the payload you encode (a customer's phone number, a campaign URL, a message body) never goes to a third-party QR service.

What the QR capability does

The routes are ordinary GET requests authenticated with your API key, so a QR image is something you can generate on demand (each print run, each agent, each receipt), not a file you pre-make and store. The QR API reference lists all three endpoints; the shapes below show the contract a first call uses.

A WhatsApp click-to-chat QR, defaulting to PNG bytes:

curl "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&message=Hi%2C%20I%27d%20like%20a%20quote" \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -o whatsapp-chat.png

The equivalent JSON response, when an embed or a template wants the image inline:

curl "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&message=Hi&format=json" \
  -H "X-API-Key: dv_live_sk_your_key_here"
{
  "data": {
    "qr_data_url": "data:image/png;base64,iVBORw0KGgo…",
    "whatsapp_link": "https://wa.me/14155552671?text=Hi",
    "phone": "14155552671",
    "size": 300
  }
}

The envelope echoes the exact deep link the image encodes, so a pipeline can log or audit what it printed without decoding pixels.

Payload surfaces — SMS, WhatsApp, links, and more

The four shapes a scanned phone actually opens. The WhatsApp pattern ships first in every worked example because it is the thinnest-friction entry point from paper into a two-way conversation.

WhatsApp click-to-chat. GET /api/v1/qr/whatsapp encodes a https://wa.me/<digits> URL, with an optional ?text= prefill from the message parameter (up to 1024 characters). Scanning opens WhatsApp addressed to your business number with the first message already typed — the customer taps send. The phone validates as a dialable international number before encode, and the digits-only form wa.me requires is derived after that validation:

curl "https://api.orbit.devotel.io/api/v1/qr/whatsapp?phone=%2B14155552671&message=Scan%20from%20the%20counter%20poster" \
  -H "X-API-Key: $ORBIT_API_KEY" -o poster.png

SMS deep link. GET /api/v1/qr/sms encodes an sms:<E.164>?body=… URI. Scanning opens the device's native SMS composer addressed to the number, body prefilled — useful where texting a keyword is the entry action ("Text JOIN to …"). The encoded recipient is the normalized E.164 form, so the image payload carries only a plus sign and digits:

curl "https://api.orbit.devotel.io/api/v1/qr/sms?phone=%2B14155552671&message=JOIN" \
  -H "X-API-Key: $ORBIT_API_KEY" -o sms-join.png

Arbitrary URLs or text. GET /api/v1/qr/generate takes a data parameter (max 2048 characters) and encodes it verbatim — https:// links, mailto: addresses, tel: numbers, Wi-Fi credentials, check-in codes. http(s), mailto, tel, sms, and wa.me payloads all ride this route:

curl "https://api.orbit.devotel.io/api/v1/qr/generate?data=https%3A%2F%2Fyourbrand.com%2Fcheck-in&size=600" \
  -H "X-API-Key: $ORBIT_API_KEY" -o check-in.png

No-login preview. A Developer → QR Code Tools page in the dashboard renders the same three shapes live as you type, with Download PNG and Copy Link actions, so you can verify the encoded deep link before it goes to print.

Reply channels behind the deep links — the WhatsApp conversation, the SMS thread, the voice number — run on the tenant's own connected channels. A QR is the door into a conversation, not a send in itself; it never routes outbound traffic, and it composes with the SMS API, WhatsApp Business API, and Verify API surfaces an implementation already uses.

Safety: what the API refuses to encode

These controls belong to each tenant's account credentials, and the platform enforces them identically on every call — document them the way your team judges them:

  • Script-execution schemes are rejected with 400. A payload beginning javascript:, data:, vbscript:, file:, about:, or blob: never reaches an image. Some QR-scanner apps preview the encoded URL as tappable, and a fraction of them execute javascript: URIs in a hosted webview — refusing those payloads server-side means a tenant-issued QR cannot smuggle an executable scheme into somebody's scanner.
  • The phone path validates, then normalizes. phone first passes a character floor that admits only what legitimately appears in a human-typed phone number (+, digits, spaces, parentheses, dashes, dots), then the platform's phone-number library confirms the input dials a real destination. Undialable shapes — +12, all-zero, country code with no subscriber digits — come back as 400 before anything is encoded, and the SMS route encodes the normalized E.164 form only, so the sms: URI carries + and digits and nothing else.
  • Rendering stays on the platform. The PNG renders server-side from the payload you sent; there is no third-party QR-image service in the path, so raw phone numbers and message bodies never leave the platform to produce an image.

The result for a buyer evaluating posture: a QR from this API can open a chat, a composer, or a page — it cannot execute a script.

Sizing, formats, and limits

  • Size: 50–1024 pixels on the square edge, default 300. Print collateral typically wants 600+; a favicon-adjacent web embed lives at the small end.
  • Payload ceiling: 2048 characters of data, which matches the practical ceiling of a QR version-40 symbol — a longer buffer is a 422, not a degraded image. Prefilled message bodies cap at 1024 characters.
  • Formats: png (default, raw image/png bytes, cacheable for five minutes as a private response) or json (base64 data URL plus the echo fields above).
  • Rate class: the authenticated-read rate limit — the same class as the rest of the read surface, so misconfiguration harms only the tenant's own application, per the rate-limit guide.

Where teams use it

  • Receipts and post-purchase. Print a WhatsApp QR on the receipt; the scan opens a thread with the store, body prefilled with the order reference.
  • Paper onboarding. A postcard or letter carries an sms: QR with the keyword prefilled; the scan lands the customer in the Verify API loop without anyone typing a short code.
  • Postcard and direct-mail campaigns. The custom-URL route encodes the campaign landing page; one print run, one measurable scan-through.
  • Retail counters and floor signage. Click-to-chat WhatsApp from the poster on the counter — the thinnest possible step from offline to a conversation your team answers in the inbox.
  • Agent-link sharing. A rep generates a personal QR that opens a chat addressed to their own queue, then shares it in email footers and badges.

The full parameter-by-parameter walkthrough — multipart examples, the SDK's generic request helper, and the dashboard preview — lives in the QR codes guide, with the endpoint contract in the QR API reference.

Frequently asked questions

Does the QR API send the SMS or WhatsApp message for me?

No. A QR code encodes a deep link; scanning it opens the device's SMS composer or a WhatsApp chat addressed to your number, with the message body prefilled. The customer sends from their own device — outbound sends still run through your messaging API calls and their own consent and quiet-hours controls.

What phone number format do the sms and whatsapp routes accept?

International format — + followed by digits, or a human-typed shape like (415) 555-2671 that the platform can normalize. The input must resolve to a dialable international number; anything else returns a 400 with INVALID_PHONE before any image is rendered.

Can the QR encode a vCard, a PDF, or a data: URI?

No. Script-execution schemes — javascript:, data:, vbscript:, file:, about:, blob: — are rejected with a 400. Plain text, http(s), mailto:, tel:, sms:, and wa.me shapes encode. A vCard fits within the plain-text allowance as long as it stays under the 2048-character ceiling.

PNG or JSON — which response format should an implementation pick?

Default png when you write the image to a file or stream it to a browser img tag. Pick format=json when your system wants the base64 data URL inline (a hosted document template, an email compose surface) or when you want the exact encoded deep link echoed back for logging.

Does generating a QR consume messaging credits?

No. QR generation is an authenticated read-class API call that renders an image; nothing is sent. Credits apply only when a scan turns into an actual message on one of your channels — the SMS reply, the WhatsApp session — under your existing per-channel pricing.

Keep reading

QR Code API for SMS, WhatsApp, and Links: Generate Deep-Link QRs Server-Side — Orbit by Devotel