API Reference

OverviewSMSVoice CallingVoice MessagingConversations APIIntegrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroups

File Storage API

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

ParameterTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can use this to let the user know what they can do about the error.
errors[].parameterstringThe 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.

HeaderDescriptionRequired
Content-TypeIndicates the media type of the resourceYes
Content-DispositionIndicates 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

ParameterTypeDescription
idstringThe unique ID generated by MessageBird that identifies the file.
namestringFile name (if provided).
{"id":"99449497-535c-46c1-b57c-ddd193edfc5b","name":"contract.pdf"}

Response codes

CodeDescription
200File successfully uploaded.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
5xxUnexpected 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

ParameterTypeDescriptionRequired
idstringThe 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.

HeaderDescription
Content-TypeIndicates the media type of the resource
Content-DispositionIndicates how the resource should be displayed by a browser (inline or attachment) and also the filename.
Content-LengthIndicates the file size in bytes

Response codes

CodeDescription
200File successfully fetched.
400Invalid HTTP request. The HTTP response should include details about the error.
401Unauthorized.
403Access forbidden.
404File not found.
5xxUnexpected 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

ParameterTypeDescriptionRequired
idstringThe 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

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

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