Create pre-signed upload

This API generates a pre-signed URL for media uploads. It responds with information required to build a subsequent form data request to upload the media to an S3 bucket. Please refer to Examples below on how to use it.

Create a presigned media upload

post

Creates a pre-signed URL to upload media that can be used when sending messages in a conversation. The maximum fize size is 100MiB.

Authorizations

MessageBird_userMessageBird_accessKey

Path parameters

workspaceIdstring · uuidRequired

The workspace ID

Example: b4e02c85-c6d2-4b15-8885-e09671799c61

conversationIdstring · uuidRequired

The conversation ID

Example: 67e4d358-ca94-421e-98b7-448860df9d33

Body

contentTypestring · min: 1Required

The MIME type of the media being uploaded.

Example: image/png

Responses

200

OK

application/json

404

The resource specified in the URL was not found

application/json

422

The request body did not pass validation

application/json

post

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/conversations/{conversationId}/presigned-upload HTTP/1.1
Host: api.bird.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 27

{
  "contentType": "image/png"
}

{
  "mediaUrl": "https://media.api.bird.com/workspaces/f08a0fa2-5597-43af-9afb-9cf1015e5c7f/conversations/60c179e7-7e43-423b-bef2-14f4d0132b71/media/0c5e5552-fe12-4c4c-a39d-3604bb30aa81",
  "uploadUrl": "https://example-bucket.s3.eu-west-1.amazonaws.com",
  "uploadMethod": "POST",
  "uploadFormData": {}
}

Examples

In the following example, we'll generate a pre-signed upload URL, then use it to upload media, and finally send a message with it:

1. Generate URL

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/presigned-upload" \
-H "Authorization: AccessKey abcd"

Response (200 - OK)

{
  "mediaUrl": "https://media.api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/media/e867a2ac-2df5-40be-a5d4-e452d7156048",
  "uploadUrl": "https://channels--message-media--151603429280--euw1.s3.eu-west-1.amazonaws.com",
  "uploadMethod": "POST",
  "uploadFormData": {
    "Content-Type": "image/png",
    "acl": "private",
    "bucket": "channels--message-media--151603429280--euw1",
    "key": "a1405560-c8d3-4b1a-877d-3f449ad95352/e867a2ac-2df5-40be-a5d4-e452d7156048",
    "policy": "c29tZSByYW5kb20gYmFzZTY0IHNvbWUgcmFuZG9tIGJhc2U2NCBzb21lIHJhbmRvbSBiYXNlNjQ=",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "ASIAZIY3TY7LKB5VSROM/20241202/us-west-1/s3/aws4_request",
    "x-amz-date": "20241202T151755Z",
    "x-amz-meta-allowed-paths": "/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/media/e867a2ac-2df5-40be-a5d4-e452d7156048",
    "x-amz-meta-channel-id": "cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f",
    "x-amz-meta-conversation-id": "02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418",
    "x-amz-security-token": "dmJ0h6xCpr/DysEQmSWORwF7HggMJq6GSSAXUCA0lDY=",
    "x-amz-signature": "22986b67e42558bc2f44b970d8a8c0357832540245a5c80df1229f4166c9d73c"
  }
}

1. Upload media to pre-signed URL

All of the fields in uploadFormData from the previous response need to be passed as form data string fields. Additionally, the field file must contain the media file you'd like to upload.

The response status is 204 (No Content).

Request

curl 'https://channels--message-media--151603429280--euw1.s3.eu-west-1.amazonaws.com' \
-F 'Content-Type="image/png"' \
-F 'acl="private"' \
-F 'bucket="channels--message-media--151603429280--euw1"' \
-F 'key="a1405560-c8d3-4b1a-877d-3f449ad95352/e867a2ac-2df5-40be-a5d4-e452d7156048"' \
-F 'policy="c29tZSByYW5kb20gYmFzZTY0IHNvbWUgcmFuZG9tIGJhc2U2NCBzb21lIHJhbmRvbSBiYXNlNjQ="' \
-F 'x-amz-algorithm="AWS4-HMAC-SHA256"' \
-F 'x-amz-credential="ASIAZIY3TY7LKB5VSROM/20241202/us-east-2/s3/aws4_request"' \
-F 'x-amz-date="20241202T151755Z"' \
-F 'x-amz-meta-allowed-paths="/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/media/e867a2ac-2df5-40be-a5d4-e452d7156048"' \
-F 'x-amz-meta-channel-id="cb4b1ebc-34e6-5a7a-a375-f6f2f131d88f"' \
-F 'x-amz-meta-conversation-id="02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418"' \
-F 'x-amz-security-token="dmJ0h6xCpr/DysEQmSWORwF7HggMJq6GSSAXUCA0lDY="' \
-F 'x-amz-signature="22986b67e42558bc2f44b970d8a8c0357832540245a5c80df1229f4166c9d73c"' \
-F 'file=@"./bird.png"'

1. Send message with media

Request

curl -X POST "https://api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/messages" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
  "participantType": "accessKey",
  "participantId": "0c0defe3-c98d-46d9-a9bf-febc1e08aa0c",
  "addMissingParticipants": true,
  "recipients": [
    {
      "type": "to",
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]"
    }
  ],
  "body": {
    "type": "html",
    "html": {
      "attachments": [
        {
          "inline": true,
          "filename": "my_file",
          "mediaUrl": "https://media.api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/media/e867a2ac-2df5-40be-a5d4-e452d7156048"
        }
      ],
      "html": "<!doctype html><body><img src=\"cid:my_file\"></img></body></html>"
    }
  }
}'

Response (201 - Created)

{
  "id": "fec68d3d-bd43-4e73-8ef9-15d7b078b20e",
  "conversationId": "02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418",
  "reference": "",
  "sender": {
    "id": "68b80b8d-8060-42df-bda3-73505a8fdb84",
    "type": "accessKey",
    "status": "active",
    "displayName": "My first email key",
    "avatarUrl": ""
  },
  "draft": false,
  "recipients": [
    {
      "type": "to",
      "id": "8f0b5377-2edc-4116-a8e8-6a475f245a04",
      "identifierKey": "emailaddress",
      "identifierValue": "[e-mail]",
      "platformAddress": "[e-mail]",
      "contactAnnotation": {
        "name": "John Doe"
      }
    }
  ],
  "status": "accepted",
  "source": "conversations",
  "body": {
    "type": "html",
    "html": {
      "html": "<!doctype html><body><img src=\"cid:my_file\"></img></body></html>",
      "attachments": [
        {
          "mediaUrl": "https://media.api.bird.com/workspaces/a1405560-c8d3-4b1a-877d-3f449ad95352/conversations/02ec2ac2-ebec-42d3-a5f4-e6f3a9edf418/media/e867a2ac-2df5-40be-a5d4-e452d7156048",
          "filename": "my_file",
          "inline": true
        }
      ]
    }
  },
  "interactions": null,
  "createdAt": "2024-12-02T17:17:24.419Z",
  "updatedAt": "2024-12-02T17:17:24.419Z"
}