> For the complete documentation index, see [llms.txt](https://developer.ecall-messaging.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ecall-messaging.com/api-references/rest-api/media.md).
# Media
Upload and retrieve binary media files (images, documents, audio, video) for use in rich message content types such as RCS or WhatsApp.
## Upload a media file
> Uploads a binary media file (image, document, audio, or video) and returns a\
> \`mediaId\` that can be referenced in rich message content fields such as\
> \`ImageContent.mediaId\`, \`DocumentContent.mediaId\`, etc.
```json
{"openapi":"3.1.0","info":{"title":"eCall REST API","version":"2.0"},"tags":[{"name":"Media","description":"Upload and retrieve binary media files (images, documents, audio, video) for use in\nrich message content types such as RCS or WhatsApp.\n"}],"servers":[{"url":"https://rest.ecall.ch","description":"eCall REST API (Production)"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic Authentication. Encode `username:password` in Base64 and pass as:\n`Authorization: Basic `\n\nUse your eCall account credentials or a dedicated API sub-user created in the\neCall portal (**Interfaces → Overview**).\n"}},"schemas":{"MediaUploadResult":{"type":"object","description":"Result of a successful media upload.","properties":{"mediaId":{"type":["string","null"],"description":"Unique identifier of the uploaded media file. Use this in message content."}},"additionalProperties":false},"Error":{"type":"object","description":"Error response returned for `4xx` and `5xx` HTTP status codes.","properties":{"errorCode":{"$ref":"#/components/schemas/ErrorCode"},"errorMessage":{"type":["string","null"],"description":"High-level human-readable description of the error."},"errorDetails":{"description":"Detailed breakdown of validation errors, if applicable.","oneOf":[{"$ref":"#/components/schemas/ParameterErrorDetails"},{"type":"null"}]}},"additionalProperties":false},"ErrorCode":{"type":"string","description":"Machine-readable error code indicating why the request failed.\n\n| Code | Description |\n|------|-------------|\n| `InvalidContent` | JSON validation failed — bad parameter value. Check `errorDetails`. |\n| `InsufficientPoints` | Account has insufficient points/credits to send this message. |\n| `TooManyMessagesSameReceiver` | Too many messages sent to the same recipient (anti-spam). |\n| `TooManyMessagesSameReceiverAndContent` | Too many identical messages to the same recipient. |\n| `RequestMissing` | Request body is missing or empty. |\n| `UnknownContentType` | The specified `content.type` is not recognised. |\n| `InvalidSenderAccount` | The sender address is not valid for this account. |\n| `CannotConvertMediaBody` | Media file could not be processed. |\n| `PointSubstractionError` | Error deducting points from account balance. |\n| `AdrCountryNotWhitelisted` | Recipient country is not whitelisted for this account. |\n| `AdrCountryWhitelistLimitExceeded` | Country whitelist limit exceeded. |\n","enum":["Error1","Error2","RequestMissing","CannotConvertMediaBody","UnknownContentType","InvalidSenderAccount","InvalidContent","InsufficientPoints","PointSubstractionError","TooManyMessagesSameReceiver","TooManyMessagesSameReceiverAndContent","AdrCountryNotWhitelisted","AdrCountryWhitelistLimitExceeded","AdrCountryWhitelistLimitReachedButNotBlockedCountries"]},"ParameterErrorDetails":{"type":"object","description":"Detailed error information for parameter validation failures.","allOf":[{"$ref":"#/components/schemas/ErrorDetails"}],"properties":{"errors":{"type":["array","null"],"description":"List of individual field validation errors.","items":{"$ref":"#/components/schemas/ParameterErrorDetailsEntry"}}},"additionalProperties":false},"ErrorDetails":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ErrorDetailsType"}},"additionalProperties":false},"ErrorDetailsType":{"type":"string","enum":["Parameter"]},"ParameterErrorDetailsEntry":{"type":"object","description":"A single field-level validation error.","properties":{"parameter":{"type":["string","null"],"description":"Name of the field that caused the error."},"messages":{"type":["array","null"],"description":"Human-readable error messages for this field.","items":{"type":"string"}}},"additionalProperties":false}},"responses":{"BadRequest":{"description":"The request is invalid. This may be caused by a missing required parameter,\nan invalid value, or a constraint violation. Check the `errorCode` and\n`errorDetails` in the response body for specifics.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The `Authorization` header is missing or the credentials are invalid.\nVerify your username, password, and Base64 encoding.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred on the eCall server. Retry after a short delay.\nIf the problem persists, contact eCall support and include the `x-f24-request-id`\nheader value from the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v2/media":{"post":{"tags":["Media"],"summary":"Upload a media file","operationId":"uploadMedia","description":"Uploads a binary media file (image, document, audio, or video) and returns a\n`mediaId` that can be referenced in rich message content fields such as\n`ImageContent.mediaId`, `DocumentContent.mediaId`, etc.\n","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"The file to upload."}}}}}},"responses":{"201":{"description":"File uploaded successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaUploadResult"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
## Retrieve a media file
> Downloads a previously uploaded media file by its \`mediaId\`.
```json
{"openapi":"3.1.0","info":{"title":"eCall REST API","version":"2.0"},"tags":[{"name":"Media","description":"Upload and retrieve binary media files (images, documents, audio, video) for use in\nrich message content types such as RCS or WhatsApp.\n"}],"servers":[{"url":"https://rest.ecall.ch","description":"eCall REST API (Production)"}],"security":[{"BasicAuth":[]}],"components":{"securitySchemes":{"BasicAuth":{"type":"http","scheme":"basic","description":"HTTP Basic Authentication. Encode `username:password` in Base64 and pass as:\n`Authorization: Basic `\n\nUse your eCall account credentials or a dedicated API sub-user created in the\neCall portal (**Interfaces → Overview**).\n"}},"responses":{"BadRequest":{"description":"The request is invalid. This may be caused by a missing required parameter,\nan invalid value, or a constraint violation. Check the `errorCode` and\n`errorDetails` in the response body for specifics.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The `Authorization` header is missing or the credentials are invalid.\nVerify your username, password, and Base64 encoding.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"The requested resource (message ID, media ID, etc.) was not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InternalServerError":{"description":"An unexpected error occurred on the eCall server. Retry after a short delay.\nIf the problem persists, contact eCall support and include the `x-f24-request-id`\nheader value from the response.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","description":"Error response returned for `4xx` and `5xx` HTTP status codes.","properties":{"errorCode":{"$ref":"#/components/schemas/ErrorCode"},"errorMessage":{"type":["string","null"],"description":"High-level human-readable description of the error."},"errorDetails":{"description":"Detailed breakdown of validation errors, if applicable.","oneOf":[{"$ref":"#/components/schemas/ParameterErrorDetails"},{"type":"null"}]}},"additionalProperties":false},"ErrorCode":{"type":"string","description":"Machine-readable error code indicating why the request failed.\n\n| Code | Description |\n|------|-------------|\n| `InvalidContent` | JSON validation failed — bad parameter value. Check `errorDetails`. |\n| `InsufficientPoints` | Account has insufficient points/credits to send this message. |\n| `TooManyMessagesSameReceiver` | Too many messages sent to the same recipient (anti-spam). |\n| `TooManyMessagesSameReceiverAndContent` | Too many identical messages to the same recipient. |\n| `RequestMissing` | Request body is missing or empty. |\n| `UnknownContentType` | The specified `content.type` is not recognised. |\n| `InvalidSenderAccount` | The sender address is not valid for this account. |\n| `CannotConvertMediaBody` | Media file could not be processed. |\n| `PointSubstractionError` | Error deducting points from account balance. |\n| `AdrCountryNotWhitelisted` | Recipient country is not whitelisted for this account. |\n| `AdrCountryWhitelistLimitExceeded` | Country whitelist limit exceeded. |\n","enum":["Error1","Error2","RequestMissing","CannotConvertMediaBody","UnknownContentType","InvalidSenderAccount","InvalidContent","InsufficientPoints","PointSubstractionError","TooManyMessagesSameReceiver","TooManyMessagesSameReceiverAndContent","AdrCountryNotWhitelisted","AdrCountryWhitelistLimitExceeded","AdrCountryWhitelistLimitReachedButNotBlockedCountries"]},"ParameterErrorDetails":{"type":"object","description":"Detailed error information for parameter validation failures.","allOf":[{"$ref":"#/components/schemas/ErrorDetails"}],"properties":{"errors":{"type":["array","null"],"description":"List of individual field validation errors.","items":{"$ref":"#/components/schemas/ParameterErrorDetailsEntry"}}},"additionalProperties":false},"ErrorDetails":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/ErrorDetailsType"}},"additionalProperties":false},"ErrorDetailsType":{"type":"string","enum":["Parameter"]},"ParameterErrorDetailsEntry":{"type":"object","description":"A single field-level validation error.","properties":{"parameter":{"type":["string","null"],"description":"Name of the field that caused the error."},"messages":{"type":["array","null"],"description":"Human-readable error messages for this field.","items":{"type":"string"}}},"additionalProperties":false}}},"paths":{"/api/v2/media/{mediaId}":{"get":{"tags":["Media"],"summary":"Retrieve a media file","operationId":"getMedia","description":"Downloads a previously uploaded media file by its `mediaId`.","parameters":[{"name":"mediaId","in":"path","required":true,"description":"Unique identifier of the media file, as returned by the upload endpoint.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Media file returned as binary.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.ecall-messaging.com/api-references/rest-api/media.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.