Missing Media Attachments in onMessageAdd and onMessageAdded Webhooks – Twilio Support

Issue

When using the Twilio Conversations SDK to send messages with multiple media attachments, the onMessageAdd or onMessageAdded webhook payloads only display a single media file. Developers notice that additional files attached to the same message are missing from the webhook data, leading to dropped or incomplete media processing in their backend applications.

Product

Conversations Classic

Environment

Twilio Console

Cause

The issue stems from a structural discrepancy in how Twilio processes multiple media files depending on their original source:

Messaging Channels (WhatsApp / MMS): When a user sends multiple media files via WhatsApp or MMS, Twilio’s messaging gateway automatically breaks them apart. It creates a separate, individual message for each file. As a result, your webhook triggers multiple times once for each message and no data is lost.
Conversations SDK: The native Conversations SDK (for Web, iOS, or Android) allows a user to attach multiple media files to the exact same message object. However, the onMessageAdd and onMessageAdded webhook payload structures only expose a single media item per message event.

Because the webhook payload limits the visible media metadata to just one file, your backend remains "blind" to any additional attachments bundled within that single SDK message.

Resolution

To ensure your backend processes all media attachments successfully, do not rely solely on the webhook payload data for SDK-generated messages. Instead, use the webhook as a trigger to query the Twilio REST API for the complete message details.

Follow these steps to resolve the issue:

Intercept the Webhook: Catch the incoming onMessageAdd or onMessageAdded webhook event in your backend application.
Extract the Message SID: Grab the unique Message SID (IMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) from the webhook payload.
Query the Twilio REST API: Make a synchronous HTTP GET request to the Twilio Conversations Message Resource endpoint using the extracted Message SID.
Inspect the Full Media Array: Unlike the webhook payload, the REST API response acts as the single source of truth. It will accurately return an array containing every single media file attached to that message.
Process the Media: Loop through the complete media list returned by the REST API to download, log, or process all user attachments.

Additional Information