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

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

POSThttps://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/presigned-upload

Path parameters

workspaceId*string (uuid)

The workspace ID

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

conversationId*string (uuid)

The conversation ID

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

Body

application/json

contentType*string

The MIME type of the media being uploaded.

Example: "image/png"

Response

200404422

OK

Body

application/json

mediaUrl*string (uri)

The URL to use when sending messages with this media. Must be passed in the attachments object.

Example: "https://media.api.bird.com/workspaces/f08a0fa2-5597-43af-9afb-9cf1015e5c7f/conversations/60c179e7-7e43-423b-bef2-14f4d0132b71/media/0c5e5552-fe12-4c4c-a39d-3604bb30aa81"

uploadUrl*string (uri)

The URL to upload the media using form data encoding. The media must be sent with the field name file in addition to fields in uploadFormData.

Example: "https://example-bucket.s3.eu-west-1.amazonaws.com"

uploadMethod*string

The method to use when uploading the media, will always be POST.

Example: "POST"

uploadFormData*object

Form data fields that must be passed in addition to the field file when uploading the media to uploadUrl.

Request

JavaScriptCurlPython

const response = await fetch('https://api.bird.com/workspaces/{workspaceId}/conversations/{conversationId}/presigned-upload', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "contentType": "image/png"
    }),
});
const data = await response.json();

Response

200404422

{
  "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"
}

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"
}