Send Files to CRM: Receiving-System Integration

Connect Mediabriz to your system so it can receive file submissions, download the files and save them against the correct customer or case.

Before you begin: complete General webhook requirements for connection security, shared fields, responses and duplicate prevention.

1. Understand the delivery

A SEND_FILES delivery contains file details and download links. Your system downloads the files separately. File contents and conversation messages are not included.

• Files: 1 to 10 successfully prepared files, up to 15 MB (15,728,640 bytes) each.
• Unavailable files: expired, oversized, unavailable or Guard-blocked files are omitted and reported to the agent. If none can be prepared, no delivery is sent.
• Do not assume file order. File-sharing time, a separate media-type field and link-expiry timestamp are not supplied.
• No order fields: items, requestedDeliveryDate, metadata.agentModifiedFields, purchaseOrderNumber and notes are absent.

2. Read the fields and identify the customer

The shared guide defines the envelope, agent, customer, queue and custom fields. These rules are specific to file deliveries:

Customer matching: on email, the name and address belong to the sender, or the recipient if your organization started the thread. Anonymous Web Messaging may have no address. WhatsApp may provide a business-scoped identifier instead of a phone number.

File information included in the delivery

Fields below are present; nullable values remain present as null. Within schema version 1, ignore additional fields you do not recognize.

Generated filenames: unnamed files use their kind (image, audio, video, document or file), UTC sending date and minute, and MIME extension, for example image-2026-10-06-1120.jpg. Unknown extensions are omitted. Repeated generated names receive -2, -3, etc. Original names may repeat.

Example: one file

{
  "schemaVersion": 1,
  "eventId": "7d1f0c3a-2b4e-4c5d-9e8f-0a1b2c3d4e5f",
  "action": {
    "type": "SEND_FILES",
    "actionId": "act_8a1e2f3c",
    "label": "Save to CRM"
  },
  "organizationId": "your-genesys-org-guid",
  "conversationId": "c0ffee00-1111-2222-3333-444455556666",
  "metadata": {
    "agent": {
      "id": "agent-user-guid",
      "name": "Dana Levi",
      "email": "dana.levi@example.com"
    },
    "submittedAt": "2026-10-06T11:20:33.000Z",
    "source": "mediabriz-agent"
  },
  "customer": {
    "externalContactId": null,
    "name": "David Cohen",
    "channelType": "whatsapp",
    "channelAddress": "15551234567",
    "customerReference": null
  },
  "queue": {
    "id": "q-guid",
    "name": "Support"
  },
  "customFields": {
    "case_number": "CS-20931",
    "document_type": "invoice"
  },
  "files": [
    {
      "mediaId": "a1b2c3d4-0000-4000-8000-000000000001",
      "fileName": "invoice-0915.pdf",
      "contentType": "application/pdf",
      "sizeBytes": 184320,
      "sourceMessageId": "msg-guid-1",
      "senderParty": "customer",
      "downloadUrl": "https://api.mediabriz.com/prod/actions/files/<token>"
    }
  ]
}

Here, case_number is agent-entered and document_type is a Dropdown option key. Each file has its own secret download token.

3. Download and store the files

1. Save the delivery details.
2. Respond to Mediabriz within the configured timeout (3 to 20 seconds). Do not wait for the downloads.
3. Download each file using HTTPS GET and its downloadUrl. Do not send an Authorization header, API key or cookies. The link itself gives access.
4. Follow the 302 redirect immediately. The address in Location works for only 60 seconds. Do not save that address or send an Authorization header to it.
5. Save the file in your system. The filename is included in Content-Disposition.

Note: 
- Download links expire 24 hours after file preparation.
- Keep download links private. Anyone with a valid link can download the file. Do not share full links or include them in logs. Each link gives access to one file in your organization.

If a download fails

Download example

curl -L -o invoice-0915.pdf "https://api.mediabriz.com/prod/actions/files/<token>"

4. Respond and handle retries

Send a response

Return 2xx with JSON: {"success":true,"referenceId":"CS-20931"}. Agents see Files sent and the reference returned by your system.

Limits: First 64 KB read; referenceId 200 characters; message 300.

On failure, the agent sees Your system did not accept the files or could not be reached. Try again.

Handle retries and repeated sends

Mediabriz does not retry automatically. Use eventId for agent retries and new sends:

5. Allow outbound downloads

If outbound traffic is restricted, allow HTTPS port 443 to both hosts for your region:

6. Next step

Follow the next step in the setup guide.