API Reference

Many message types of multiple platforms require media files stored in a public URL, so they can be used for sending messages, however, media files may contain sensitive customer information and keeping them in public accessible URLs is not safe. The File Storage API enables you to safely upload, fetch and delete files to be used when sending Whatsapp and Email messages through Conversations API.

Fetching files stored in the File Storage API requires authentication, which means the sensitive data of your customers won't be available publicly. MessageBird's WhatsApp and Email platforms identify when a file is stored in the File Storage API, and safely retrieves them for message processing.

Authorization

You need to set an access key to authenticate your HTTP requests. You can create, manage, and retrieve your access keys using the MessageBird Dashboard.

To provide the access key, set the Authorization HTTP header in the form of AccessKey {accessKey}.

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of API requests.

HTTP response codes in the 2xx range indicate the request was successfully processed
HTTP response codes in the 4xx range indicate that there was a client error - for example: authentication error, not enough balance or wrong/missing parameters. Don't worry, the HTTP response body includes a JSON-formatted response that tells you exactly what went wrong. If you're stuck, feel free to contact support, we're happy to help you out
HTTP response codes in the 5xx range indicate a server error. It's considered safe to retry the same request, preferably with a delay

Error object

{
  "errors": [
    {
      "code": 1001,
      "description": "You are requesting with an invalid credential.",
      "parameter": null
    }
  ]
}

Attributes

Parameter	Type	Description
errors[].code	integer	An integer that represents the error type.
errors[].description	string	A human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameter	string	The parameter in your request related to the error if the error is parameter specific.

Upload file

Upload a file of any type/format with a maximum size of 100 MB.

POST https://messaging.messagebird.com/v1/files

Request

The following HTTP headers are required/supported along with the Authorization header.

Header	Description	Required
Content-Type	Indicates the media type of the resource	Yes
Content-Disposition	Indicates how the resource should be displayed by a browser (inline or attachment) and also the filename.	No

curl -X POST https://messaging.messagebird.com/v1/files \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -H 'Content-Disposition: attachment; filename="contract.pdf"' \
  -H 'Content-Type: application/pdf' \
  --data-binary @contract.pdf

Response

Parameter	Type	Description
id	string	The unique ID generated by MessageBird that identifies the file.
name	string	File name (if provided).

{"id":"99449497-535c-46c1-b57c-ddd193edfc5b","name":"contract.pdf"}

Response codes

Code	Description
200	File successfully uploaded.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
5xx	Unexpected internal server error. Please retry the request with standard exponential backoff.

Fetch file

Fetch a file previously uploaded based on its ID.

GET https://messaging.messagebird.com/v1/files/{id}

Request

Parameter	Type	Description	Required
id	string	The unique ID generated by MessageBird that identifies the file.	Yes

curl -X GET https://messaging.messagebird.com/v1/files/98415197-535d-46c1-b57c-ddd193eefc5b -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Response

The HTTP response includes the file binary along with the following HTTP headers.

Header	Description
Content-Type	Indicates the media type of the resource
Content-Disposition	Indicates how the resource should be displayed by a browser (inline or attachment) and also the filename.
Content-Length	Indicates the file size in bytes

Response codes

Code	Description
200	File successfully fetched.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
403	Access forbidden.
404	File not found.
5xx	Unexpected internal server error. Please retry the request with standard exponential backoff.

Delete file

Delete a file previously uploaded based on its ID.

DELETE https://messaging.messagebird.com/v1/files/{id}

Request

Parameter	Type	Description	Required
id	string	The unique ID generated by MessageBird that identifies the file.	Yes

curl -X DELETE https://messaging.messagebird.com/v1/files/98415197-535d-46c1-b57c-ddd193eefc5b -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Response

A successful HTTP response (204 No Content) doesn't have response body.

Response codes

Code	Description
204	File successfully deleted.
400	Invalid HTTP request. The HTTP response should include details about the error.
401	Unauthorized.
403	Access forbidden.
404	File not found.
5xx	Unexpected internal server error. Please retry the request with standard exponential backoff.

Is this page useful?

Next upOmnichannel Widget

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings