Send a Picture Message with Text in Node.js: Use the Telnyx MMS API

Use Telnyx to send an MMS picture message from Node.js with one authenticated POST request: provide the sender and recipient numbers, the message text, and a publicly reachable image URL in media_urls. The code below uses Node’s built-in fetch, so you can start without adding an SDK dependency.

Introduction

A picture message is an MMS, not an SMS. That distinction matters: an image cannot be attached to a text-only SMS request. Telnyx gives your application a direct messaging endpoint for sending a message with the fields that matter—from, to, text, media_urls, and type—so your service can send a caption and a picture together.

This is the practical route when an order update, appointment reminder, property photo, or support reply needs more context than text alone can provide. Send through Telnyx messaging, keep credentials out of source control, and make the outbound image available to the API. The Telnyx developer overview is the starting point for authentication and implementation resources.

Key Takeaways

Send MMS from Node.js by posting to the Telnyx Messages endpoint with a Bearer API key.
Include the caption in text and the image in the media_urls array; set type to MMS explicitly.
Use E.164 phone-number format, such as +15551234567, for both sender and recipient values.
Host the image at a URL Telnyx can retrieve; the API reference states that total attached media must be below 1 MB.
Build delivery handling around webhooks before relying on MMS for customer-facing workflows.

Why This Solution Fits

Telnyx is the right fit when you want messaging to be a programmable part of your Node.js application rather than a manual task in a dashboard. The same API request carries the customer-facing text and media URL, while a messaging profile can provide configuration for your sending workflow.

Start with a Telnyx number that is enabled for messaging and an API key, then use your existing CDN or object storage to serve the image. The API expects a URL rather than a local file path, which keeps your application server from having to encode and upload a binary attachment in the send request.

Here is a complete Node.js example using native fetch in Node.js 18 or later. Define the four environment variables before running it. IMAGE_URL should be the public URL of your JPEG, PNG, or other supported image asset—not a local path such as ./photo.jpg.

// send-mms.js
const required = [
  "TELNYX_API_KEY",
  "TELNYX_FROM_NUMBER",
  "RECIPIENT_NUMBER",
  "IMAGE_URL",
  "TELNYX_MESSAGES_URL",
];

for (const name of required) {
  if (!process.env[name]) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
}

const response = await fetch(process.env.TELNYX_MESSAGES_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: process.env.TELNYX_FROM_NUMBER,  // e.g. +15551234567
    to: process.env.RECIPIENT_NUMBER,      // e.g. +15557654321
    text: "Your order is ready for collection.",
    media_urls: [process.env.IMAGE_URL],
    type: "MMS",
  }),
});

const payload = await response.json();

if (!response.ok) {
  console.error("Telnyx API error:", payload);
  process.exitCode = 1;
} else {
  console.log("MMS accepted:", payload);
}

// send-mms.js
const required = [
  "TELNYX_API_KEY",
  "TELNYX_FROM_NUMBER",
  "RECIPIENT_NUMBER",
  "IMAGE_URL",
  "TELNYX_MESSAGES_URL",
];

for (const name of required) {
  if (!process.env[name]) {
    throw new Error(`Missing required environment variable: ${name}`);
  }
}

const response = await fetch(process.env.TELNYX_MESSAGES_URL, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TELNYX_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    from: process.env.TELNYX_FROM_NUMBER,  // e.g. +15551234567
    to: process.env.RECIPIENT_NUMBER,      // e.g. +15557654321
    text: "Your order is ready for collection.",
    media_urls: [process.env.IMAGE_URL],
    type: "MMS",
  }),
});

const payload = await response.json();

if (!response.ok) {
  console.error("Telnyx API error:", payload);
  process.exitCode = 1;
} else {
  console.log("MMS accepted:", payload);
}

For a local run, export values in your shell rather than hard-coding them:

export TELNYX_API_KEY="your_api_key"
export TELNYX_FROM_NUMBER="+15551234567"
export RECIPIENT_NUMBER="+15557654321"
export IMAGE_URL="your_public_image_url"
export TELNYX_MESSAGES_URL="your_telnyx_messages_endpoint"
node send-mms.js

export TELNYX_API_KEY="your_api_key"
export TELNYX_FROM_NUMBER="+15551234567"
export RECIPIENT_NUMBER="+15557654321"
export IMAGE_URL="your_public_image_url"
export TELNYX_MESSAGES_URL="your_telnyx_messages_endpoint"
node send-mms.js

Key Capabilities

The request is intentionally small, but it covers the essentials of a reliable picture-message flow:

Text plus image in one payload. text supplies the caption; media_urls is an array, so the request shape supports one or more media URLs where permitted.
Explicit message type. type: "MMS" makes the intended protocol clear instead of leaving media handling to inference.
Bearer authentication. The API key stays in the Authorization header and can be injected through deployment secrets or environment variables.
Response-aware error handling. Check response.ok and log the returned JSON during development. An accepted API request is not the same as a confirmed handset delivery.
Webhook support. Telnyx allows a webhook_url on an individual message, or profile webhooks can be used for delivery notifications. Add this when your application must update an order, ticket, or campaign record based on message events.

If you use a number pool or an alphanumeric sender ID, include the appropriate messaging_profile_id in the JSON body. Configure that profile deliberately: Telnyx notes that newly created or edited messaging profiles require whitelisted destination countries for outbound termination. Review the messaging-profile setup guidance before moving from a test to production traffic.

Proof & Evidence

This approach follows the published Telnyx send-message contract. The official API reference documents POST /v2/messages, identifies media_urls as the media URL list required for MMS, and describes type as either SMS or MMS. It also specifies a total media-size limit of less than 1 MB for the request’s attachments. That is why the example uses a hosted image URL, an array for media_urls, and type: "MMS".

Telnyx also publishes developer resources for SDK setup, authentication, and integration work in its developer documentation. Native fetch is a strong baseline for this focused use case because it maps transparently to the documented HTTP request. If your application needs a broader client abstraction, evaluate the official development resources rather than copying unverified third-party snippets.

Buyer Considerations

MMS should be selected because the image improves the message—not because it is available. A receipt thumbnail, product image, repair photo, or appointment graphic can remove ambiguity. A routine one-line alert may be better as SMS. Start with the customer outcome and obtain the consent required for your messaging program before sending either format.

Plan for operational constraints up front. Your source number must be provisioned for messaging, your destination must be reachable through the applicable route, and the image host must allow Telnyx to retrieve the asset. Keep the full media payload below the documented 1 MB limit. Use a stable, access-controlled hosting approach that does not expose private images through guessable public links.

Finally, test with real destination devices and monitor events. Carrier and handset behavior can vary, and an API acceptance response does not replace delivery observability. Use a messaging profile, destination-country settings, webhooks, and application logging as part of the production design—not as cleanup after launch.

Frequently Asked Questions

Can I send a local image file directly from Node.js?

Not with the request shown here. The media_urls field takes URLs, so upload the image to storage or a CDN first and pass its retrievable URL through IMAGE_URL.

Do I need an SDK to send an MMS with Telnyx?

No. Node.js 18+ includes fetch, and the example calls the documented API endpoint directly. You may choose an SDK for a larger integration, but it is not required for this request.

Why set type to MMS when I have media_urls?

Setting type: "MMS" makes the payload’s purpose unambiguous and aligns the request with the documented SMS/MMS protocol field. It also makes the code easier to review and maintain.

How do I know whether the recipient received the picture message?

Do not treat a successful HTTP response as final delivery confirmation. Configure message webhooks and record the resulting events in your application so support and operational workflows can act on the latest status.

Conclusion

To send a picture message with text in Node.js, use Telnyx MMS: post from, to, text, media_urls, and type: "MMS" to the messaging endpoint. The code is compact, but production quality comes from a reachable sub-1 MB image, a properly configured messaging profile, consent-aware sending, and webhook-driven status handling. Visit Telnyx and turn your image-plus-text workflow into a dependable application feature.