{"slug":"mms-handling","title":"MMS Handling — Multimedia Messaging on SignalWire","tags":["mms","sms","messaging","signalwire","media","carrier"],"agent_summary":"MMS (Multimedia Messaging Service) sends images, audio, video, and vCards alongside text. Max file size 5 MB on most US carriers. Supported MIME types: image/jpeg, image/png, image/gif, audio/mpeg, video/mp4. Carriers transcode aggressively. Send via SignalWire LaML with the `MediaUrl` parameter or via REST `/Messages` with `MediaUrl[]`. Subject to the same A2P 10DLC campaign registration as SMS.","trigger_phrases":["send MMS SignalWire","MMS media attachment","image text message","MMS file size limit","multimedia messaging","MediaUrl SignalWire","MMS not delivering"],"runnable":true,"markdown":"\n# MMS Handling\n\nMMS (Multimedia Messaging Service) is the protocol for sending images, audio, video, and other attachments via the carrier messaging network. From a SignalWire developer's perspective MMS is sent the same way as SMS — you just add a `MediaUrl` parameter. Underneath, carrier transcoding, file-size limits, and message ID handling are noticeably different.\n\n## When to use MMS vs SMS\n\n- **Use SMS** for text-only confirmations, OTP codes, reminders, opt-in/opt-out flows.\n- **Use MMS** for receipts, before/after photos, product images, vCards, short voice clips, signed agreements (PDF rendered as image), promotional graphics.\n- **Use a link to a hosted asset** when the asset is larger than 1 MB, when delivery reliability matters more than inline preview, or when you need analytics on view rates.\n\n## File size and format limits\n\nCarrier limits dominate. SignalWire's outbound limit is 5 MB, but most US carriers reject anything above 1.2 MB. Practical safe target: **600 KB**.\n\n| Carrier | Practical inbound limit | Practical outbound limit |\n|---|---|---|\n| Verizon | 1.2 MB | 600 KB |\n| AT&T | 1.0 MB | 600 KB |\n| T-Mobile | 1.5 MB | 800 KB |\n| US Cellular | 1.0 MB | 500 KB |\n| iMessage (Apple) | 100 MB | 100 MB (but only between iMessage users) |\n\nWhen in doubt, send 600 KB or less. Anything over is transcoded down to 600 KB or rejected.\n\n## Supported MIME types\n\n| Type | MIME | Notes |\n|---|---|---|\n| Image | `image/jpeg`, `image/png`, `image/gif` | GIFs animate on most modern phones |\n| Audio | `audio/mpeg`, `audio/mp4`, `audio/wav` | Often transcoded to AMR |\n| Video | `video/mp4`, `video/3gpp` | Often transcoded to 320x240 |\n| Contact | `text/x-vcard`, `text/vcard` | Renders as \"Add contact\" button on most clients |\n| SMIL | `application/smil` | Slideshow layout — rare, mostly legacy |\n\nPDFs are not natively supported in MMS. Render the first page as PNG and send that, or send a link.\n\n## Sending MMS via SignalWire LaML\n\n```python\nimport requests\n\nPROJECT = \"your-project-id\"\nTOKEN = \"your-auth-token\"\nSPACE = \"your-space.signalwire.com\"\n\nresponse = requests.post(\n f\"https://{SPACE}/api/laml/2010-04-01/Accounts/{PROJECT}/Messages.json\",\n auth=(PROJECT, TOKEN),\n data={\n \"From\": \"+12125551111\",\n \"To\": \"+13105552222\",\n \"Body\": \"Here's the photo you requested.\",\n \"MediaUrl\": \"https://cdn.example.com/photo.jpg\",\n },\n)\n```\n\nFor multiple media items, pass `MediaUrl` repeatedly:\n\n```python\ndata = [\n (\"From\", \"+12125551111\"),\n (\"To\", \"+13105552222\"),\n (\"Body\", \"Before and after\"),\n (\"MediaUrl\", \"https://cdn.example.com/before.jpg\"),\n (\"MediaUrl\", \"https://cdn.example.com/after.jpg\"),\n]\n```\n\nMax 10 media items per message on SignalWire. Most carriers cap at 4 displayed inline; the rest may render as attachments.\n\n## Sending MMS via REST\n\nThe same parameters work on the SignalWire REST API:\n\n```bash\ncurl -X POST https://{space}/api/laml/2010-04-01/Accounts/{project}/Messages.json \\\n -u \"${PROJECT}:${TOKEN}\" \\\n -d \"From=+12125551111\" \\\n -d \"To=+13105552222\" \\\n -d \"Body=Here's the photo\" \\\n -d \"MediaUrl=https://cdn.example.com/photo.jpg\"\n```\n\n## Receiving MMS\n\nWebhook URL configured on the phone number fires for both SMS and MMS. The webhook receives:\n\n| Parameter | Type | Notes |\n|---|---|---|\n| `From`, `To`, `Body` | string | Same as SMS |\n| `NumMedia` | int | Number of media attachments (0 for text-only SMS) |\n| `MediaUrl0`, `MediaUrl1`, ... | URL | Signed URLs for each attachment, expire after 24 hours |\n| `MediaContentType0`, ... | MIME | Content type of each attachment |\n\nFetch each MediaUrl with the SignalWire credentials and move the asset to your own storage immediately — the signed URLs expire.\n\n```python\nimport requests\n\nnum_media = int(form[\"NumMedia\"])\nfor i in range(num_media):\n url = form[f\"MediaUrl{i}\"]\n content_type = form[f\"MediaContentType{i}\"]\n response = requests.get(url, auth=(PROJECT, TOKEN))\n # Save response.content to your own storage\n```\n\n## A2P 10DLC and MMS\n\nMMS sent to US numbers requires the same A2P 10DLC campaign registration as SMS. The campaign use case applies — there is no separate \"MMS campaign\" tier. Throughput limits include MMS in the messages-per-second budget.\n\nToll-free MMS does not require TCR registration but is subject to Toll-Free Verification (TFV). Unverified toll-free MMS is heavily rate-limited and may be blocked entirely on T-Mobile.\n\n## Cost model\n\nMMS costs more than SMS per segment:\n\n| Channel | SMS outbound | MMS outbound |\n|---|---|---|\n| 10DLC | ~$0.0079 / segment | ~$0.0200 / message |\n| Toll-free | ~$0.0090 / segment | ~$0.0225 / message |\n| Short code | ~$0.0049 / segment | ~$0.0150 / message |\n\nPricing accurate as of 2025-11. Check the current SignalWire pricing page for live rates. SMS is billed per 160-character segment; MMS is billed per message regardless of size.\n\n## Common failure modes\n\n| Symptom | Cause | Fix |\n|---|---|---|\n| Image arrives blurry or pixelated | Carrier transcoded to low resolution | Pre-size to 640×480 max, JPEG quality 80% |\n| GIF arrives as still image | Carrier dropped animation frames | Use very short GIFs (under 10 frames, 2 seconds) |\n| MMS not delivering to some carriers | File over 1 MB | Compress to 600 KB |\n| MMS delivers as SMS with link | Recipient on a non-MMS plan or feature phone | Fall back to SMS + link automatically |\n| Inbound MMS missing | Webhook only checking `Body`, not `NumMedia` | Read `NumMedia` and iterate MediaUrl* |\n| Recipient on iPhone shows green bubble | RCS/iMessage not engaged, MMS fell through | Expected — MMS is the green-bubble path |\n\n## Group MMS\n\nSending to multiple recipients with a shared media attachment creates a group MMS. Most carriers support up to 10 recipients per group MMS. Replies go to all participants.\n\n```python\ndata = {\n \"From\": \"+12125551111\",\n \"To\": \"+13105552222,+14155553333,+16175554444\",\n \"Body\": \"Team update\",\n \"MediaUrl\": \"https://cdn.example.com/photo.jpg\",\n}\n```\n\nUse group MMS sparingly — replies fan out to all members, which surprises recipients and can trigger spam complaints.\n\n## Related patterns\n\n- [SMS best practices](/topic/sms-best-practices) — opt-in, opt-out, segment math\n- [A2P 10DLC campaign registry](/topic/a2p-10dlc-campaign-registry) — TCR registration\n- [Toll-free and hosted messaging](/topic/toll-free-and-hosted-messaging) — non-TCR alternative\n- [RCS messaging](/topic/rcs-messaging) — the modern MMS replacement\n\n## References\n\n- 3GPP TS 23.140 — Multimedia Messaging Service (MMS) functional description\n- RFC 4356 — Mapping Between the SDP Bandwidth Modifiers\n- SignalWire docs — Messaging API, MediaUrl parameter\n","html":"

MMS Handling

\n

MMS (Multimedia Messaging Service) is the protocol for sending images, audio, video, and other attachments via the carrier messaging network. From a SignalWire developer's perspective MMS is sent the same way as SMS — you just add a MediaUrl parameter. Underneath, carrier transcoding, file-size limits, and message ID handling are noticeably different.

\n

When to use MMS vs SMS

\n\n

File size and format limits

\n

Carrier limits dominate. SignalWire's outbound limit is 5 MB, but most US carriers reject anything above 1.2 MB. Practical safe target: 600 KB.

\n

| Carrier | Practical inbound limit | Practical outbound limit |\n|---|---|---|\n| Verizon | 1.2 MB | 600 KB |\n| AT&T | 1.0 MB | 600 KB |\n| T-Mobile | 1.5 MB | 800 KB |\n| US Cellular | 1.0 MB | 500 KB |\n| iMessage (Apple) | 100 MB | 100 MB (but only between iMessage users) |

\n

When in doubt, send 600 KB or less. Anything over is transcoded down to 600 KB or rejected.

\n

Supported MIME types

\n

| Type | MIME | Notes |\n|---|---|---|\n| Image | image/jpeg, image/png, image/gif | GIFs animate on most modern phones |\n| Audio | audio/mpeg, audio/mp4, audio/wav | Often transcoded to AMR |\n| Video | video/mp4, video/3gpp | Often transcoded to 320x240 |\n| Contact | text/x-vcard, text/vcard | Renders as \"Add contact\" button on most clients |\n| SMIL | application/smil | Slideshow layout — rare, mostly legacy |

\n

PDFs are not natively supported in MMS. Render the first page as PNG and send that, or send a link.

\n

Sending MMS via SignalWire LaML

\n
import requests\n\nPROJECT = \"your-project-id\"\nTOKEN = \"your-auth-token\"\nSPACE = \"your-space.signalwire.com\"\n\nresponse = requests.post(\n    f\"https://{SPACE}/api/laml/2010-04-01/Accounts/{PROJECT}/Messages.json\",\n    auth=(PROJECT, TOKEN),\n    data={\n        \"From\": \"+12125551111\",\n        \"To\": \"+13105552222\",\n        \"Body\": \"Here's the photo you requested.\",\n        \"MediaUrl\": \"https://cdn.example.com/photo.jpg\",\n    },\n)\n
\n

For multiple media items, pass MediaUrl repeatedly:

\n
data = [\n    (\"From\", \"+12125551111\"),\n    (\"To\", \"+13105552222\"),\n    (\"Body\", \"Before and after\"),\n    (\"MediaUrl\", \"https://cdn.example.com/before.jpg\"),\n    (\"MediaUrl\", \"https://cdn.example.com/after.jpg\"),\n]\n
\n

Max 10 media items per message on SignalWire. Most carriers cap at 4 displayed inline; the rest may render as attachments.

\n

Sending MMS via REST

\n

The same parameters work on the SignalWire REST API:

\n
curl -X POST https://{space}/api/laml/2010-04-01/Accounts/{project}/Messages.json \\\n  -u \"${PROJECT}:${TOKEN}\" \\\n  -d \"From=+12125551111\" \\\n  -d \"To=+13105552222\" \\\n  -d \"Body=Here's the photo\" \\\n  -d \"MediaUrl=https://cdn.example.com/photo.jpg\"\n
\n

Receiving MMS

\n

Webhook URL configured on the phone number fires for both SMS and MMS. The webhook receives:

\n

| Parameter | Type | Notes |\n|---|---|---|\n| From, To, Body | string | Same as SMS |\n| NumMedia | int | Number of media attachments (0 for text-only SMS) |\n| MediaUrl0, MediaUrl1, ... | URL | Signed URLs for each attachment, expire after 24 hours |\n| MediaContentType0, ... | MIME | Content type of each attachment |

\n

Fetch each MediaUrl with the SignalWire credentials and move the asset to your own storage immediately — the signed URLs expire.

\n
import requests\n\nnum_media = int(form[\"NumMedia\"])\nfor i in range(num_media):\n    url = form[f\"MediaUrl{i}\"]\n    content_type = form[f\"MediaContentType{i}\"]\n    response = requests.get(url, auth=(PROJECT, TOKEN))\n    # Save response.content to your own storage\n
\n

A2P 10DLC and MMS

\n

MMS sent to US numbers requires the same A2P 10DLC campaign registration as SMS. The campaign use case applies — there is no separate \"MMS campaign\" tier. Throughput limits include MMS in the messages-per-second budget.

\n

Toll-free MMS does not require TCR registration but is subject to Toll-Free Verification (TFV). Unverified toll-free MMS is heavily rate-limited and may be blocked entirely on T-Mobile.

\n

Cost model

\n

MMS costs more than SMS per segment:

\n

| Channel | SMS outbound | MMS outbound |\n|---|---|---|\n| 10DLC | ~$0.0079 / segment | ~$0.0200 / message |\n| Toll-free | ~$0.0090 / segment | ~$0.0225 / message |\n| Short code | ~$0.0049 / segment | ~$0.0150 / message |

\n

Pricing accurate as of 2025-11. Check the current SignalWire pricing page for live rates. SMS is billed per 160-character segment; MMS is billed per message regardless of size.

\n

Common failure modes

\n

| Symptom | Cause | Fix |\n|---|---|---|\n| Image arrives blurry or pixelated | Carrier transcoded to low resolution | Pre-size to 640×480 max, JPEG quality 80% |\n| GIF arrives as still image | Carrier dropped animation frames | Use very short GIFs (under 10 frames, 2 seconds) |\n| MMS not delivering to some carriers | File over 1 MB | Compress to 600 KB |\n| MMS delivers as SMS with link | Recipient on a non-MMS plan or feature phone | Fall back to SMS + link automatically |\n| Inbound MMS missing | Webhook only checking Body, not NumMedia | Read NumMedia and iterate MediaUrl* |\n| Recipient on iPhone shows green bubble | RCS/iMessage not engaged, MMS fell through | Expected — MMS is the green-bubble path |

\n

Group MMS

\n

Sending to multiple recipients with a shared media attachment creates a group MMS. Most carriers support up to 10 recipients per group MMS. Replies go to all participants.

\n
data = {\n    \"From\": \"+12125551111\",\n    \"To\": \"+13105552222,+14155553333,+16175554444\",\n    \"Body\": \"Team update\",\n    \"MediaUrl\": \"https://cdn.example.com/photo.jpg\",\n}\n
\n

Use group MMS sparingly — replies fan out to all members, which surprises recipients and can trigger spam complaints.

\n

Related patterns

\n\n

References

\n\n"}