Messaging

Sending messages

In order to send a message you must have an active channel and perform an HTTP request to the following endpoint with a valid access key

When you send a message, a contact is automatically created with a contactId matching the receiver's identifier if one doesn't already exist. For instance, sending an email generates a contact with an email identifier, while sending an SMS creates one with a phone number identifier.

Send a message

post

Send a message to a channel

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

channelIdstring · uuidRequired

The ID for a channel

Body

application/json

and

anyOptional

object · ChannelMessageCreateWithTemplateOptional

or

object · ChannelMessageCreateWithBodyOptional

Responses

202

Message was accepted for processing

application/json

400

An error

application/json

404

An error

application/json

409

The request conflicts with the current state of the resource.

application/json

413

The request body exceeded the 200 KB size limit.

application/json

422

The request contains invalid parameters or body fields.

application/json

post

/workspaces/{workspaceId}/channels/{channelId}/messages

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2728

{
  "sender": {
    "connector": {
      "identifierValue": "[e-mail]",
      "annotations": {
        "name": "text"
      }
    }
  },
  "receiver": {
    "contacts": [
      {
        "id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "identifierKey": "emailaddress",
        "identifierValue": "[e-mail]",
        "type": "cc",
        "identifiers": [
          {
            "identifierKey": "emailaddress",
            "identifierValue": "[e-mail]"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text"
      }
    ]
  },
  "reference": "my-own-identifier",
  "template": {
    "name": "text",
    "projectId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "version": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "locale": "text",
    "attachments": [
      {
        "mediaUrl": "https://example.com",
        "filename": "text",
        "inline": true
      }
    ],
    "shortLinks": {
      "enabled": true,
      "domain": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "parameters": [
      {
        "type": "string",
        "key": "text",
        "value": "text"
      }
    ],
    "settings": {
      "disallowMmLite": true
    }
  },
  "meta": {
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "referral": {
      "source": "text",
      "title": "text",
      "text": "text",
      "group": "text",
      "metadata": {
        "source_id": "text",
        "source_url": "text",
        "media_url": "text",
        "tracking_id": "text"
      }
    },
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "quantity": 1,
          "price": {
            "amount": 1,
            "exponent": 1,
            "currencyCode": "text"
          }
        }
      ]
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "email": {
      "subject": "text",
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "from": {
        "username": "text",
        "displayName": "text"
      }
    },
    "sms": {
      "smartEncoding": true
    },
    "pushNotifications": {
      "gatewayTypeOverride": "apns"
    },
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "stepId": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000"
    },
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  },
  "replyTo": {
    "id": "text",
    "order": 1,
    "type": "message"
  },
  "body": {
    "type": "text",
    "text": {
      "text": "text",
      "attachments": [
        {
          "mediaUrl": "https://example.com",
          "filename": "text",
          "inline": true,
          "contentId": "text"
        }
      ],
      "actions": [
        {
          "type": "link",
          "link": {
            "text": "text",
            "url": "text"
          }
        }
      ],
      "metadata": {
        "subject": "text",
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "whatsapp": {
          "previewUrl": true
        },
        "line": {
          "emoji": {
            "items": [
              {
                "index": 1,
                "productId": "text",
                "emojiId": "text"
              }
            ]
          }
        },
        "telegram": {
          "parseMode": "Markdown"
        },
        "apple": {
          "summaryText": "text",
          "appClipPreview": true,
          "appClipRegion": "text"
        }
      }
    }
  },
  "notification": {
    "url": "text"
  },
  "capFrequency": true,
  "enableLinkTracking": true,
  "ignoreQuietHours": true,
  "ignoreGlobalHoldout": true,
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2026-06-15T14:21:42.857Z",
  "validity": 1
}

{
  "body": {
    "text": {
      "actions": [
        {
          "link": {
            "metadata": {
              "description": {
                "label": "text"
              }
            },
            "text": "text",
            "url": "text"
          },
          "type": "link"
        }
      ],
      "attachments": [
        {
          "content": "text",
          "contentId": "text",
          "contentType": "text",
          "filename": "text",
          "inline": true,
          "mediaUrl": "text"
        }
      ],
      "metadata": {
        "apple": {
          "appClipPreview": true,
          "appClipRegion": "text",
          "summaryText": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "line": {
          "emoji": {
            "items": [
              {
                "emojiId": "text",
                "index": 1,
                "length": 1,
                "productId": "text"
              }
            ]
          }
        },
        "paymentDetails": {
          "amount": "text",
          "currency": "text",
          "sessionIdentifier": "text",
          "state": "text"
        },
        "subject": "text",
        "telegram": {
          "parseMode": "text"
        },
        "whatsapp": {
          "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
          "callPermissionResponse": "accept",
          "previewUrl": true
        }
      },
      "text": "text"
    },
    "type": "text"
  },
  "bodyId": "123e4567-e89b-12d3-a456-426614174000",
  "bodyStorage": {
    "type": "s3",
    "s3": {
      "bucketArn": "text",
      "encryptionKey": "text",
      "key": "text"
    }
  },
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "chargeableUnits": 1,
  "context": {
    "id": "text",
    "tagIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "type": "text"
  },
  "createdAt": "2026-06-15T14:21:42.857Z",
  "details": "text",
  "direction": "incoming",
  "failure": {
    "code": 1,
    "description": "text",
    "source": {
      "code": "text",
      "name": "pre-processing"
    }
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ignorePersistedEventhooks": true,
  "lastStatusAt": "2026-06-15T14:21:42.857Z",
  "meta": {
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    },
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "chargeOnceDelivered": true,
    "email": {
      "from": {
        "displayName": "text",
        "username": "text"
      },
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "subject": "text"
    },
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "formResponse": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "jsonResponse": "text",
      "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "selections": [
        {
          "items": [
            {
              "identifier": "text",
              "title": "text",
              "type": "text",
              "value": "text"
            }
          ],
          "pageIdentifier": "text",
          "subtitle": "text",
          "title": "text"
        }
      ],
      "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "template": "text",
      "version": "text"
    },
    "ignoreGlobalHoldout": true,
    "ignoreQuietHours": true,
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "longToShortLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metaThreadId": "text",
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "amount": 1,
            "currencyCode": "text",
            "exponent": 1
          },
          "quantity": 1
        }
      ]
    },
    "pushNotifications": {
      "gatewayTypeOverride": "firebase"
    },
    "referral": {
      "group": "text",
      "metadata": {
        "caption": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "sourceId": "text",
        "sourceUrl": "text",
        "timestamp": "2026-06-15T14:21:42.857Z",
        "trackingId": "text",
        "username": "text"
      },
      "source": "text",
      "text": "text",
      "title": "text"
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "renderedContentBlocks": [
      "text"
    ],
    "shortToLongLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "skipThisMessage": "campaignHoldout",
    "sms": {
      "gatewayId": 1,
      "registeredDelivery": "final",
      "smartEncoding": true,
      "smpp": {
        "segments": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "registeredDelivery": "final"
          }
        ],
        "userId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "validity": "2026-06-15T14:21:42.857Z"
    },
    "useFallback": true
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": 1,
      "platformReferenceId": "text",
      "platformStatusAt": "2026-06-15T14:21:42.857Z",
      "rawBody": "text",
      "reason": "text",
      "status": "accepted",
      "statusAt": "2026-06-15T14:21:42.857Z"
    }
  ],
  "platformId": "text",
  "platformReferenceId": "text",
  "previousMessages": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "useCaseType": "unspecified"
    }
  ],
  "reason": "text",
  "receiver": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contacts": [
      {
        "contactAnnotation": {
          "name": "text"
        },
        "countryCode": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "identifiers": [
          {
            "identifierKey": "text",
            "identifierValue": "text"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text",
        "receiverExpression": "text",
        "receiverValue": "text",
        "type": "text"
      }
    ],
    "device": {
      "gateway": "firebase",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContacts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "type": "text"
      }
    ]
  },
  "reference": "text",
  "replyTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order": 1,
    "platformReference": "text",
    "type": "message"
  },
  "schedule": {
    "reason": "text",
    "scheduledAt": "2026-06-15T14:21:42.857Z"
  },
  "scheduledFor": "2026-06-15T14:21:42.857Z",
  "sendAt": "2026-06-15T14:21:42.857Z",
  "sender": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contact": {
      "contactAnnotation": {
        "name": "text"
      },
      "countryCode": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "identifiers": [
        {
          "identifierKey": "text",
          "identifierValue": "text"
        }
      ],
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "receiverExpression": "text",
      "receiverValue": "text",
      "type": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "text"
    }
  },
  "shortLinks": {
    "domain": "text"
  },
  "status": "accepted",
  "tagIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "tags": [
    "text"
  ],
  "template": {
    "attachments": [
      {
        "content": "text",
        "contentType": "text",
        "filename": "text",
        "inline": true,
        "mediaUrl": "text"
      }
    ],
    "deployment": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "locale": "text",
    "name": "text",
    "parameters": [
      {
        "key": "text",
        "sourceUrl": {
          "fullyReplaced": true,
          "value": "text"
        },
        "type": "string",
        "value": {}
      }
    ],
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "settings": {
      "disallowMmLite": true
    },
    "shortLinks": {
      "domain": "text",
      "enabled": true
    },
    "templateBody": {
      "text": {
        "actions": [
          {
            "link": {
              "metadata": {
                "description": {
                  "label": "text"
                }
              },
              "text": "text",
              "url": "text"
            },
            "type": "link"
          }
        ],
        "attachments": [
          {
            "content": "text",
            "contentId": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "metadata": {
          "apple": {
            "appClipPreview": true,
            "appClipRegion": "text",
            "summaryText": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "emojiId": "text",
                  "index": 1,
                  "length": 1,
                  "productId": "text"
                }
              ]
            }
          },
          "paymentDetails": {
            "amount": "text",
            "currency": "text",
            "sessionIdentifier": "text",
            "state": "text"
          },
          "subject": "text",
          "telegram": {
            "parseMode": "text"
          },
          "whatsapp": {
            "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "updatedAt": "2026-06-15T14:21:42.857Z"
}

When sending outbound messages as well as setting the receiver information you must set the message body field in all cases except for sending a message template when you must only set the templatefield.

Multiple recipient messages are only possible through the Email platform. For other platforms, a message with multiple reciever entries will be rejected.

Body

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[phone]"
     }
   ]
 },
 "body": {...},
}

Template

{
 "receiver": {
   "contacts": [
     {
       "identifierValue": "[phone]"
     }
   ]
 },
 "template": {...},
}

Uploading media

When sending messages that contain media links these must be publicly accessible. Otherwise you can upload media by creating requesting a pre-signed media URL. Firstly make a POST request to the following endpoint with the content type of the media you will be uploading set in the request body.

There are two methods for generating a presigned URL: one is channel-independent, allowing it to be used across any channel, while the other restricts usage to a specified channel ID.

Create a presigned media upload

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

Body

application/json

contentTypestring · min: 1Required

Responses

200

OK

application/json

mediaUrlstring · uriRequired

uploadUrlstring · uriRequired

uploadMethodstringRequired

uploadFormDataobjectRequired

404

An error

application/json

422

The request contains invalid parameters or body fields.

application/json

post

/workspaces/{workspaceId}/channel-media/presigned-upload

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/channel-media/presigned-upload HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "contentType": "text"
}

{
  "mediaUrl": "https://example.com",
  "uploadUrl": "https://example.com",
  "uploadMethod": "text",
  "uploadFormData": {}
}

Example

Request

curl -X POST "https://api.bird.com/workspaces/42263973-4f1c-40db-bf0e-cea7e4bfa1a2/channel-media/presigned-upload" \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey abcd" \
-d '{
"contentType": "image/jpeg"
}'

Response

"image/gif", 
"image/jpeg", 
"image/png",  
"image/webp", 
"image/svg+xml",

Create a presigned media upload

post

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

channelIdstring · uuidRequired

The ID for a channel

Body

application/json

contentTypestring · min: 1Required

Responses

200

OK

application/json

mediaUrlstring · uriRequired

uploadUrlstring · uriRequired

uploadMethodstringRequired

uploadFormDataobjectRequired

404

An error

application/json

422

The request contains invalid parameters or body fields.

application/json

post

/workspaces/{workspaceId}/channels/{channelId}/presigned-upload

HTTPcURLJavaScriptPython

POST /workspaces/{workspaceId}/channels/{channelId}/presigned-upload HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "contentType": "text"
}

{
  "mediaUrl": "https://example.com",
  "uploadUrl": "https://example.com",
  "uploadMethod": "text",
  "uploadFormData": {}
}

From the response you will get the following details:

mediaUrl: This will be the URL you set in any message bodies where you send the uploaded media

uploadUrl: This is the URL you will need to make a request to to upload your media file

uploadMethod: This is the HTTP method to make an upload i.e. POST

uploadFormData: Set this as the fields in form-data of your POST request along with an additional field called file. This should include your file data. An example using CURL

No need to specify any AccessKey on the below call as all the required data is provided in the form data.

Example

Request

  curl -L -X POST "https://channels--message-media--151603429280--euw1.s3.eu-west-1.amazonaws.com" \
  -F Content-Type='image/jpeg' \
  -F acl='private' \
  -F bucket='text' \
  -F key='text' \
  -F policy='text' \
  -F x-amz-algorithm='AWS4-HMAC-SHA256' \
  -F x-amz-credential='text' \
  -F x-amz-date='text' \
  -F x-amz-meta-allowed-paths='text' \
  -F x-amz-security-token='text' \
  -F x-amz-signature='text' \
  -F file=@image.jpeg

Once you have uploaded the file using the mediaUrl, this should be used as the URL when sending messages with media.

Retrieving messages

Retrieve a list of messages of a channel

List messages by channel ID

get

It retrieves a list of messages from a given channel ID

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

channelIdstring · uuidRequired

The ID for a channel

Query parameters

limitinteger · min: 1 · max: 1000Optional

Limits the number of results to return.

Default: 25

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

reversebooleanOptional

Reverses the order in which the results are returned.

Default: false

platformany ofOptional

Filter based on platform name

string · min: 3 · max: 60OptionalPattern: ^[A-Za-z0-9-]+$

or

string[]Optional

directionstring · enumOptionalPossible values:

idstring · uuid[]Optional

navigatorIdstring · uuidOptional

startAtstring · date-timeOptional

Start date for the query

endAtstring · date-timeOptional

End date for the query

fromstring[]Optional

sender identifier for the message

tostring[]Optional

recipient identifier for the message

failureCodeinteger[]Optional

failureSourceCodestring[]Optional

failureSourceNamestring[]Optional

countryCodestring[]Optional

tagstring[]Optional

Filter based on tag

emailSubjectstringOptional

Full text search on email subject

batchIdstring · uuidOptional

The ID for a batch

Responses

200

OK

application/jsontext/csv

A list of channel messages

startAtstring · date-time · nullableOptional

endAtstring · date-time · nullableOptional

nextPageTokenstringOptional

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

404

An error

application/json

422

The request contains invalid parameters or body fields.

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/messages

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "startAt": "2026-06-15T14:21:42.857Z",
  "endAt": "2026-06-15T14:21:42.857Z",
  "nextPageToken": "text",
  "results": [
    {
      "body": {
        "text": {
          "actions": [
            {
              "link": {
                "metadata": {
                  "description": {
                    "label": "text"
                  }
                },
                "text": "text",
                "url": "text"
              },
              "type": "link"
            }
          ],
          "attachments": [
            {
              "content": "text",
              "contentId": "text",
              "contentType": "text",
              "filename": "text",
              "inline": true,
              "mediaUrl": "text"
            }
          ],
          "metadata": {
            "apple": {
              "appClipPreview": true,
              "appClipRegion": "text",
              "summaryText": "text"
            },
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "emojiId": "text",
                    "index": 1,
                    "length": 1,
                    "productId": "text"
                  }
                ]
              }
            },
            "paymentDetails": {
              "amount": "text",
              "currency": "text",
              "sessionIdentifier": "text",
              "state": "text"
            },
            "subject": "text",
            "telegram": {
              "parseMode": "text"
            },
            "whatsapp": {
              "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
              "callPermissionResponse": "accept",
              "previewUrl": true
            }
          },
          "text": "text"
        },
        "type": "text"
      },
      "bodyId": "123e4567-e89b-12d3-a456-426614174000",
      "bodyStorage": {
        "type": "s3",
        "s3": {
          "bucketArn": "text",
          "encryptionKey": "text",
          "key": "text"
        }
      },
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "chargeableUnits": 1,
      "context": {
        "id": "text",
        "tagIds": [
          "123e4567-e89b-12d3-a456-426614174000"
        ],
        "type": "text"
      },
      "createdAt": "2026-06-15T14:21:42.857Z",
      "details": "text",
      "direction": "incoming",
      "failure": {
        "code": 1,
        "description": "text",
        "source": {
          "code": "text",
          "name": "pre-processing"
        }
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "ignorePersistedEventhooks": true,
      "lastStatusAt": "2026-06-15T14:21:42.857Z",
      "meta": {
        "campaign": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text"
        },
        "campaignId": "123e4567-e89b-12d3-a456-426614174000",
        "chargeOnceDelivered": true,
        "email": {
          "from": {
            "displayName": "text",
            "username": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "subject": "text"
        },
        "extraInformation": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "flow": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "runId": "123e4567-e89b-12d3-a456-426614174000",
          "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
          "stepId": "text"
        },
        "formResponse": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "jsonResponse": "text",
          "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
          "selections": [
            {
              "items": [
                {
                  "identifier": "text",
                  "title": "text",
                  "type": "text",
                  "value": "text"
                }
              ],
              "pageIdentifier": "text",
              "subtitle": "text",
              "title": "text"
            }
          ],
          "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
          "template": "text",
          "version": "text"
        },
        "ignoreGlobalHoldout": true,
        "ignoreQuietHours": true,
        "journey": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "runId": "123e4567-e89b-12d3-a456-426614174000",
          "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
          "stepId": "text"
        },
        "longToShortLinks": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "metaThreadId": "text",
        "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
        "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
        "order": {
          "products": [
            {
              "externalCatalogId": "text",
              "externalProductId": "text",
              "price": {
                "amount": 1,
                "currencyCode": "text",
                "exponent": 1
              },
              "quantity": 1
            }
          ]
        },
        "pushNotifications": {
          "gatewayTypeOverride": "firebase"
        },
        "referral": {
          "group": "text",
          "metadata": {
            "caption": "text",
            "mediaType": "text",
            "mediaUrl": "text",
            "sourceId": "text",
            "sourceUrl": "text",
            "timestamp": "2026-06-15T14:21:42.857Z",
            "trackingId": "text",
            "username": "text"
          },
          "source": "text",
          "text": "text",
          "title": "text"
        },
        "referredProduct": {
          "externalCatalogId": "text",
          "externalProductId": "text"
        },
        "renderedContentBlocks": [
          "text"
        ],
        "shortToLongLinks": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "skipThisMessage": "campaignHoldout",
        "sms": {
          "gatewayId": 1,
          "registeredDelivery": "final",
          "smartEncoding": true,
          "smpp": {
            "segments": [
              {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "registeredDelivery": "final"
              }
            ],
            "userId": "123e4567-e89b-12d3-a456-426614174000"
          },
          "validity": "2026-06-15T14:21:42.857Z"
        },
        "useFallback": true
      },
      "parts": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "order": 1,
          "platformReferenceId": "text",
          "platformStatusAt": "2026-06-15T14:21:42.857Z",
          "rawBody": "text",
          "reason": "text",
          "status": "accepted",
          "statusAt": "2026-06-15T14:21:42.857Z"
        }
      ],
      "platformId": "text",
      "platformReferenceId": "text",
      "previousMessages": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "useCaseType": "unspecified"
        }
      ],
      "reason": "text",
      "receiver": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contacts": [
          {
            "contactAnnotation": {
              "name": "text"
            },
            "countryCode": "text",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "identifiers": [
              {
                "identifierKey": "text",
                "identifierValue": "text"
              }
            ],
            "platformAddress": "text",
            "platformAddressSelector": "text",
            "receiverExpression": "text",
            "receiverValue": "text",
            "type": "text"
          }
        ],
        "device": {
          "gateway": "firebase",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContacts": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "type": "text"
          }
        ]
      },
      "reference": "text",
      "replyTo": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "order": 1,
        "platformReference": "text",
        "type": "message"
      },
      "schedule": {
        "reason": "text",
        "scheduledAt": "2026-06-15T14:21:42.857Z"
      },
      "scheduledFor": "2026-06-15T14:21:42.857Z",
      "sendAt": "2026-06-15T14:21:42.857Z",
      "sender": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contact": {
          "contactAnnotation": {
            "name": "text"
          },
          "countryCode": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "identifiers": [
            {
              "identifierKey": "text",
              "identifierValue": "text"
            }
          ],
          "platformAddress": "text",
          "platformAddressSelector": "text",
          "receiverExpression": "text",
          "receiverValue": "text",
          "type": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContact": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "text"
        }
      },
      "shortLinks": {
        "domain": "text"
      },
      "status": "accepted",
      "tagIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "tags": [
        "text"
      ],
      "template": {
        "attachments": [
          {
            "content": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "deployment": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "locale": "text",
        "name": "text",
        "parameters": [
          {
            "key": "text",
            "sourceUrl": {
              "fullyReplaced": true,
              "value": "text"
            },
            "type": "string",
            "value": {}
          }
        ],
        "projectId": "123e4567-e89b-12d3-a456-426614174000",
        "settings": {
          "disallowMmLite": true
        },
        "shortLinks": {
          "domain": "text",
          "enabled": true
        },
        "templateBody": {
          "text": {
            "actions": [
              {
                "link": {
                  "metadata": {
                    "description": {
                      "label": "text"
                    }
                  },
                  "text": "text",
                  "url": "text"
                },
                "type": "link"
              }
            ],
            "attachments": [
              {
                "content": "text",
                "contentId": "text",
                "contentType": "text",
                "filename": "text",
                "inline": true,
                "mediaUrl": "text"
              }
            ],
            "metadata": {
              "apple": {
                "appClipPreview": true,
                "appClipRegion": "text",
                "summaryText": "text"
              },
              "headers": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "line": {
                "emoji": {
                  "items": [
                    {
                      "emojiId": "text",
                      "index": 1,
                      "length": 1,
                      "productId": "text"
                    }
                  ]
                }
              },
              "paymentDetails": {
                "amount": "text",
                "currency": "text",
                "sessionIdentifier": "text",
                "state": "text"
              },
              "subject": "text",
              "telegram": {
                "parseMode": "text"
              },
              "whatsapp": {
                "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
                "callPermissionResponse": "accept",
                "previewUrl": true
              }
            },
            "text": "text"
          },
          "type": "text"
        },
        "utmParameters": [
          {
            "key": "text",
            "value": "text"
          }
        ],
        "variables": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "version": "text"
      },
      "updatedAt": "2026-06-15T14:21:42.857Z"
    }
  ]
}

Retrieve list of messages of a workspace

List messages by workspace ID

get

It retrieves a list of messages from a given workspace ID

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

Query parameters

limitinteger · min: 1 · max: 1000Optional

Limits the number of results to return.

Default: 25

channelIdstring[]Optional

The ID for a channel

pageTokenstringOptional

The cursor that keeps track of the current position in the results.

reversebooleanOptional

Reverses the order in which the results are returned.

Default: false

platformany ofOptional

Filter based on platform name

string · min: 3 · max: 60OptionalPattern: ^[A-Za-z0-9-]+$

or

string[]Optional

directionstring · enumOptionalPossible values:

idstring · uuid[]Optional

startAtstring · date-timeOptional

Start date for the query

endAtstring · date-timeOptional

End date for the query

fromstring[]Optional

sender identifier for the message

tostring[]Optional

recipient identifier for the message

failureCodeinteger[]Optional

failureSourceCodestring[]Optional

failureSourceNamestring[]Optional

countryCodestring[]Optional

tagstring[]Optional

Filter based on tag

emailSubjectstringOptional

Full text search on email subject

batchIdstring · uuidOptional

The ID for a batch

Responses

200

OK

application/jsontext/csv

A list of channel messages

startAtstring · date-time · nullableOptional

endAtstring · date-time · nullableOptional

nextPageTokenstringOptional

The token that can be passed as pageToken in URL to retrieve the next set of results. If missing, no more results to display.

404

An error

application/json

422

The request contains invalid parameters or body fields.

application/json

get

/workspaces/{workspaceId}/channels/messages

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "startAt": "2026-06-15T14:21:42.857Z",
  "endAt": "2026-06-15T14:21:42.857Z",
  "nextPageToken": "text",
  "results": [
    {
      "body": {
        "text": {
          "actions": [
            {
              "link": {
                "metadata": {
                  "description": {
                    "label": "text"
                  }
                },
                "text": "text",
                "url": "text"
              },
              "type": "link"
            }
          ],
          "attachments": [
            {
              "content": "text",
              "contentId": "text",
              "contentType": "text",
              "filename": "text",
              "inline": true,
              "mediaUrl": "text"
            }
          ],
          "metadata": {
            "apple": {
              "appClipPreview": true,
              "appClipRegion": "text",
              "summaryText": "text"
            },
            "headers": {
              "ANY_ADDITIONAL_PROPERTY": "text"
            },
            "line": {
              "emoji": {
                "items": [
                  {
                    "emojiId": "text",
                    "index": 1,
                    "length": 1,
                    "productId": "text"
                  }
                ]
              }
            },
            "paymentDetails": {
              "amount": "text",
              "currency": "text",
              "sessionIdentifier": "text",
              "state": "text"
            },
            "subject": "text",
            "telegram": {
              "parseMode": "text"
            },
            "whatsapp": {
              "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
              "callPermissionResponse": "accept",
              "previewUrl": true
            }
          },
          "text": "text"
        },
        "type": "text"
      },
      "bodyId": "123e4567-e89b-12d3-a456-426614174000",
      "bodyStorage": {
        "type": "s3",
        "s3": {
          "bucketArn": "text",
          "encryptionKey": "text",
          "key": "text"
        }
      },
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "chargeableUnits": 1,
      "context": {
        "id": "text",
        "tagIds": [
          "123e4567-e89b-12d3-a456-426614174000"
        ],
        "type": "text"
      },
      "createdAt": "2026-06-15T14:21:42.857Z",
      "details": "text",
      "direction": "incoming",
      "failure": {
        "code": 1,
        "description": "text",
        "source": {
          "code": "text",
          "name": "pre-processing"
        }
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "ignorePersistedEventhooks": true,
      "lastStatusAt": "2026-06-15T14:21:42.857Z",
      "meta": {
        "campaign": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text"
        },
        "campaignId": "123e4567-e89b-12d3-a456-426614174000",
        "chargeOnceDelivered": true,
        "email": {
          "from": {
            "displayName": "text",
            "username": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "subject": "text"
        },
        "extraInformation": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "flow": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "runId": "123e4567-e89b-12d3-a456-426614174000",
          "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
          "stepId": "text"
        },
        "formResponse": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "jsonResponse": "text",
          "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
          "selections": [
            {
              "items": [
                {
                  "identifier": "text",
                  "title": "text",
                  "type": "text",
                  "value": "text"
                }
              ],
              "pageIdentifier": "text",
              "subtitle": "text",
              "title": "text"
            }
          ],
          "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
          "template": "text",
          "version": "text"
        },
        "ignoreGlobalHoldout": true,
        "ignoreQuietHours": true,
        "journey": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text",
          "runId": "123e4567-e89b-12d3-a456-426614174000",
          "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
          "stepId": "text"
        },
        "longToShortLinks": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "metaThreadId": "text",
        "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
        "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
        "order": {
          "products": [
            {
              "externalCatalogId": "text",
              "externalProductId": "text",
              "price": {
                "amount": 1,
                "currencyCode": "text",
                "exponent": 1
              },
              "quantity": 1
            }
          ]
        },
        "pushNotifications": {
          "gatewayTypeOverride": "firebase"
        },
        "referral": {
          "group": "text",
          "metadata": {
            "caption": "text",
            "mediaType": "text",
            "mediaUrl": "text",
            "sourceId": "text",
            "sourceUrl": "text",
            "timestamp": "2026-06-15T14:21:42.857Z",
            "trackingId": "text",
            "username": "text"
          },
          "source": "text",
          "text": "text",
          "title": "text"
        },
        "referredProduct": {
          "externalCatalogId": "text",
          "externalProductId": "text"
        },
        "renderedContentBlocks": [
          "text"
        ],
        "shortToLongLinks": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "skipThisMessage": "campaignHoldout",
        "sms": {
          "gatewayId": 1,
          "registeredDelivery": "final",
          "smartEncoding": true,
          "smpp": {
            "segments": [
              {
                "id": "123e4567-e89b-12d3-a456-426614174000",
                "registeredDelivery": "final"
              }
            ],
            "userId": "123e4567-e89b-12d3-a456-426614174000"
          },
          "validity": "2026-06-15T14:21:42.857Z"
        },
        "useFallback": true
      },
      "parts": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "order": 1,
          "platformReferenceId": "text",
          "platformStatusAt": "2026-06-15T14:21:42.857Z",
          "rawBody": "text",
          "reason": "text",
          "status": "accepted",
          "statusAt": "2026-06-15T14:21:42.857Z"
        }
      ],
      "platformId": "text",
      "platformReferenceId": "text",
      "previousMessages": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "useCaseType": "unspecified"
        }
      ],
      "reason": "text",
      "receiver": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contacts": [
          {
            "contactAnnotation": {
              "name": "text"
            },
            "countryCode": "text",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "identifiers": [
              {
                "identifierKey": "text",
                "identifierValue": "text"
              }
            ],
            "platformAddress": "text",
            "platformAddressSelector": "text",
            "receiverExpression": "text",
            "receiverValue": "text",
            "type": "text"
          }
        ],
        "device": {
          "gateway": "firebase",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContacts": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "type": "text"
          }
        ]
      },
      "reference": "text",
      "replyTo": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "order": 1,
        "platformReference": "text",
        "type": "message"
      },
      "schedule": {
        "reason": "text",
        "scheduledAt": "2026-06-15T14:21:42.857Z"
      },
      "scheduledFor": "2026-06-15T14:21:42.857Z",
      "sendAt": "2026-06-15T14:21:42.857Z",
      "sender": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contact": {
          "contactAnnotation": {
            "name": "text"
          },
          "countryCode": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "identifiers": [
            {
              "identifierKey": "text",
              "identifierValue": "text"
            }
          ],
          "platformAddress": "text",
          "platformAddressSelector": "text",
          "receiverExpression": "text",
          "receiverValue": "text",
          "type": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContact": {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "text"
        }
      },
      "shortLinks": {
        "domain": "text"
      },
      "status": "accepted",
      "tagIds": [
        "123e4567-e89b-12d3-a456-426614174000"
      ],
      "tags": [
        "text"
      ],
      "template": {
        "attachments": [
          {
            "content": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "deployment": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "locale": "text",
        "name": "text",
        "parameters": [
          {
            "key": "text",
            "sourceUrl": {
              "fullyReplaced": true,
              "value": "text"
            },
            "type": "string",
            "value": {}
          }
        ],
        "projectId": "123e4567-e89b-12d3-a456-426614174000",
        "settings": {
          "disallowMmLite": true
        },
        "shortLinks": {
          "domain": "text",
          "enabled": true
        },
        "templateBody": {
          "text": {
            "actions": [
              {
                "link": {
                  "metadata": {
                    "description": {
                      "label": "text"
                    }
                  },
                  "text": "text",
                  "url": "text"
                },
                "type": "link"
              }
            ],
            "attachments": [
              {
                "content": "text",
                "contentId": "text",
                "contentType": "text",
                "filename": "text",
                "inline": true,
                "mediaUrl": "text"
              }
            ],
            "metadata": {
              "apple": {
                "appClipPreview": true,
                "appClipRegion": "text",
                "summaryText": "text"
              },
              "headers": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              },
              "line": {
                "emoji": {
                  "items": [
                    {
                      "emojiId": "text",
                      "index": 1,
                      "length": 1,
                      "productId": "text"
                    }
                  ]
                }
              },
              "paymentDetails": {
                "amount": "text",
                "currency": "text",
                "sessionIdentifier": "text",
                "state": "text"
              },
              "subject": "text",
              "telegram": {
                "parseMode": "text"
              },
              "whatsapp": {
                "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
                "callPermissionResponse": "accept",
                "previewUrl": true
              }
            },
            "text": "text"
          },
          "type": "text"
        },
        "utmParameters": [
          {
            "key": "text",
            "value": "text"
          }
        ],
        "variables": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "version": "text"
      },
      "updatedAt": "2026-06-15T14:21:42.857Z"
    }
  ]
}

Retrieve a single message

Get message by message ID

get

Get a channel message

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

messageIdstring · uuidRequired

The ID for a message

channelIdstring · uuidRequired

The ID for a channel

Responses

200

OK

application/json

bodyone ofOptional

or

or

or

or

or

or

or

or

or

or

bodyIdstring · uuidOptional

channelIdstring · uuidRequired

chargeableUnitsinteger · uint32Optional

createdAtstring · date-timeRequired

detailsstringOptional

This field is used to store additional information related to the message status.

directionstring · enumOptionalPossible values:

idstring · uuidRequired

ignorePersistedEventhooksbooleanOptional

lastStatusAtstring · date-timeRequired

platformIdstringOptional

platformReferenceIdstringOptional

reasonstringOptional

referencestringOptional

A reference to the message. This can be used to identify the message in the channel.

scheduledForstring · date-timeOptional

Scheduled message send time (RFC3339). Messages scheduled within 10 minutes may be sent immediately; messages scheduled more than 35 days out will be rejected.

sendAtstring · date-timeOptional

statusstring · enumRequiredPossible values:

tagIdsstring · uuid[]Optional

tagsstring[]Optional

Tags to associate with the message. Tags are converted to lower case and automatically created if they don't exist. Up to 10 tags per message.

updatedAtstring · date-timeRequired

404

An error

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "body": {
    "text": {
      "actions": [
        {
          "link": {
            "metadata": {
              "description": {
                "label": "text"
              }
            },
            "text": "text",
            "url": "text"
          },
          "type": "link"
        }
      ],
      "attachments": [
        {
          "content": "text",
          "contentId": "text",
          "contentType": "text",
          "filename": "text",
          "inline": true,
          "mediaUrl": "text"
        }
      ],
      "metadata": {
        "apple": {
          "appClipPreview": true,
          "appClipRegion": "text",
          "summaryText": "text"
        },
        "headers": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "line": {
          "emoji": {
            "items": [
              {
                "emojiId": "text",
                "index": 1,
                "length": 1,
                "productId": "text"
              }
            ]
          }
        },
        "paymentDetails": {
          "amount": "text",
          "currency": "text",
          "sessionIdentifier": "text",
          "state": "text"
        },
        "subject": "text",
        "telegram": {
          "parseMode": "text"
        },
        "whatsapp": {
          "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
          "callPermissionResponse": "accept",
          "previewUrl": true
        }
      },
      "text": "text"
    },
    "type": "text"
  },
  "bodyId": "123e4567-e89b-12d3-a456-426614174000",
  "bodyStorage": {
    "type": "s3",
    "s3": {
      "bucketArn": "text",
      "encryptionKey": "text",
      "key": "text"
    }
  },
  "channelId": "123e4567-e89b-12d3-a456-426614174000",
  "chargeableUnits": 1,
  "context": {
    "id": "text",
    "tagIds": [
      "123e4567-e89b-12d3-a456-426614174000"
    ],
    "type": "text"
  },
  "createdAt": "2026-06-15T14:21:42.857Z",
  "details": "text",
  "direction": "incoming",
  "failure": {
    "code": 1,
    "description": "text",
    "source": {
      "code": "text",
      "name": "pre-processing"
    }
  },
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "ignorePersistedEventhooks": true,
  "lastStatusAt": "2026-06-15T14:21:42.857Z",
  "meta": {
    "campaign": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    },
    "campaignId": "123e4567-e89b-12d3-a456-426614174000",
    "chargeOnceDelivered": true,
    "email": {
      "from": {
        "displayName": "text",
        "username": "text"
      },
      "headers": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "subject": "text"
    },
    "extraInformation": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "flow": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "formResponse": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "jsonResponse": "text",
      "requestIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "selections": [
        {
          "items": [
            {
              "identifier": "text",
              "title": "text",
              "type": "text",
              "value": "text"
            }
          ],
          "pageIdentifier": "text",
          "subtitle": "text",
          "title": "text"
        }
      ],
      "sessionIdentifier": "123e4567-e89b-12d3-a456-426614174000",
      "template": "text",
      "version": "text"
    },
    "ignoreGlobalHoldout": true,
    "ignoreQuietHours": true,
    "journey": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "runId": "123e4567-e89b-12d3-a456-426614174000",
      "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
      "stepId": "text"
    },
    "longToShortLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "metaThreadId": "text",
    "navigatorId": "123e4567-e89b-12d3-a456-426614174000",
    "navigatorMessageId": "123e4567-e89b-12d3-a456-426614174000",
    "order": {
      "products": [
        {
          "externalCatalogId": "text",
          "externalProductId": "text",
          "price": {
            "amount": 1,
            "currencyCode": "text",
            "exponent": 1
          },
          "quantity": 1
        }
      ]
    },
    "pushNotifications": {
      "gatewayTypeOverride": "firebase"
    },
    "referral": {
      "group": "text",
      "metadata": {
        "caption": "text",
        "mediaType": "text",
        "mediaUrl": "text",
        "sourceId": "text",
        "sourceUrl": "text",
        "timestamp": "2026-06-15T14:21:42.857Z",
        "trackingId": "text",
        "username": "text"
      },
      "source": "text",
      "text": "text",
      "title": "text"
    },
    "referredProduct": {
      "externalCatalogId": "text",
      "externalProductId": "text"
    },
    "renderedContentBlocks": [
      "text"
    ],
    "shortToLongLinks": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "skipThisMessage": "campaignHoldout",
    "sms": {
      "gatewayId": 1,
      "registeredDelivery": "final",
      "smartEncoding": true,
      "smpp": {
        "segments": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "registeredDelivery": "final"
          }
        ],
        "userId": "123e4567-e89b-12d3-a456-426614174000"
      },
      "validity": "2026-06-15T14:21:42.857Z"
    },
    "useFallback": true
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": 1,
      "platformReferenceId": "text",
      "platformStatusAt": "2026-06-15T14:21:42.857Z",
      "rawBody": "text",
      "reason": "text",
      "status": "accepted",
      "statusAt": "2026-06-15T14:21:42.857Z"
    }
  ],
  "platformId": "text",
  "platformReferenceId": "text",
  "previousMessages": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "useCaseType": "unspecified"
    }
  ],
  "reason": "text",
  "receiver": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contacts": [
      {
        "contactAnnotation": {
          "name": "text"
        },
        "countryCode": "text",
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "identifiers": [
          {
            "identifierKey": "text",
            "identifierValue": "text"
          }
        ],
        "platformAddress": "text",
        "platformAddressSelector": "text",
        "receiverExpression": "text",
        "receiverValue": "text",
        "type": "text"
      }
    ],
    "device": {
      "gateway": "firebase",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContacts": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "identifierKey": "text",
        "identifierValue": "text",
        "type": "text"
      }
    ]
  },
  "reference": "text",
  "replyTo": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "order": 1,
    "platformReference": "text",
    "type": "message"
  },
  "schedule": {
    "reason": "text",
    "scheduledAt": "2026-06-15T14:21:42.857Z"
  },
  "scheduledFor": "2026-06-15T14:21:42.857Z",
  "sendAt": "2026-06-15T14:21:42.857Z",
  "sender": {
    "connector": {
      "annotations": {
        "name": "text"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierValue": "text",
      "types": [
        "text"
      ]
    },
    "contact": {
      "contactAnnotation": {
        "name": "text"
      },
      "countryCode": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "identifiers": [
        {
          "identifierKey": "text",
          "identifierValue": "text"
        }
      ],
      "platformAddress": "text",
      "platformAddressSelector": "text",
      "receiverExpression": "text",
      "receiverValue": "text",
      "type": "text"
    },
    "inbox": {
      "emailRecipientType": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "user"
    },
    "userContact": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "identifierKey": "text",
      "identifierValue": "text",
      "type": "text"
    }
  },
  "shortLinks": {
    "domain": "text"
  },
  "status": "accepted",
  "tagIds": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "tags": [
    "text"
  ],
  "template": {
    "attachments": [
      {
        "content": "text",
        "contentType": "text",
        "filename": "text",
        "inline": true,
        "mediaUrl": "text"
      }
    ],
    "deployment": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "locale": "text",
    "name": "text",
    "parameters": [
      {
        "key": "text",
        "sourceUrl": {
          "fullyReplaced": true,
          "value": "text"
        },
        "type": "string",
        "value": {}
      }
    ],
    "projectId": "123e4567-e89b-12d3-a456-426614174000",
    "settings": {
      "disallowMmLite": true
    },
    "shortLinks": {
      "domain": "text",
      "enabled": true
    },
    "templateBody": {
      "text": {
        "actions": [
          {
            "link": {
              "metadata": {
                "description": {
                  "label": "text"
                }
              },
              "text": "text",
              "url": "text"
            },
            "type": "link"
          }
        ],
        "attachments": [
          {
            "content": "text",
            "contentId": "text",
            "contentType": "text",
            "filename": "text",
            "inline": true,
            "mediaUrl": "text"
          }
        ],
        "metadata": {
          "apple": {
            "appClipPreview": true,
            "appClipRegion": "text",
            "summaryText": "text"
          },
          "headers": {
            "ANY_ADDITIONAL_PROPERTY": "text"
          },
          "line": {
            "emoji": {
              "items": [
                {
                  "emojiId": "text",
                  "index": 1,
                  "length": 1,
                  "productId": "text"
                }
              ]
            }
          },
          "paymentDetails": {
            "amount": "text",
            "currency": "text",
            "sessionIdentifier": "text",
            "state": "text"
          },
          "subject": "text",
          "telegram": {
            "parseMode": "text"
          },
          "whatsapp": {
            "callPermissionExpiration": "2026-06-15T14:21:42.857Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "updatedAt": "2026-06-15T14:21:42.857Z"
}

Retrieve all message interactions on a message

List message interactions

get

List message interactions

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token

Path parameters

workspaceIdstring · uuidRequired

The unique identifier of the workspace.

messageIdstring · uuidRequired

The ID for a message

channelIdstring · uuidRequired

The ID for a channel

Responses

200

OK

application/json

A list of channel messages interactions

404

An error

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions

HTTPcURLJavaScriptPython

GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*

{
  "results": [
    {
      "bodyTemplateProjectId": "123e4567-e89b-12d3-a456-426614174000",
      "channelId": "123e4567-e89b-12d3-a456-426614174000",
      "context": {
        "id": "text",
        "tagIds": [
          "123e4567-e89b-12d3-a456-426614174000"
        ],
        "type": "text"
      },
      "createdAt": "2026-06-15T14:21:42.857Z",
      "details": "text",
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "isFirstInteraction": true,
      "isFirstInteractionIncludingBots": true,
      "journey": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "text",
        "runId": "123e4567-e89b-12d3-a456-426614174000",
        "scheduleExecutionId": "123e4567-e89b-12d3-a456-426614174000",
        "stepId": "text"
      },
      "messageCreatedAt": "2026-06-15T14:21:42.857Z",
      "messageId": "123e4567-e89b-12d3-a456-426614174000",
      "messagePartsCount": 1,
      "messageReference": "text",
      "messageTags": [
        "text"
      ],
      "metadata": {
        "button": {
          "payload": "text"
        },
        "conversion": {
          "method": "unknown",
          "status": "converted",
          "timestamp": "2026-06-15T14:21:42.857Z",
          "type": "otp"
        },
        "extraInformation": {
          "ANY_ADDITIONAL_PROPERTY": "text"
        },
        "link": {
          "clickType": "link",
          "name": "text",
          "url": "text"
        },
        "prefetched": true,
        "reaction": {
          "action": "react",
          "emoji": "text"
        },
        "renderedContentBlocks": [
          "text"
        ],
        "subscriptionList": {
          "subscriptionListId": "123e4567-e89b-12d3-a456-426614174000"
        }
      },
      "notification": {
        "template": "text",
        "url": "text"
      },
      "platformId": "text",
      "platformReferenceId": "text",
      "receiver": {
        "connector": {
          "annotations": {
            "name": "text"
          },
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text",
          "types": [
            "text"
          ]
        },
        "contacts": [
          {
            "contactAnnotation": {
              "name": "text"
            },
            "countryCode": "text",
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "identifiers": [
              {
                "identifierKey": "text",
                "identifierValue": "text"
              }
            ],
            "platformAddress": "text",
            "platformAddressSelector": "text",
            "receiverExpression": "text",
            "receiverValue": "text",
            "type": "text"
          }
        ],
        "device": {
          "gateway": "firebase",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierValue": "text"
        },
        "inbox": {
          "emailRecipientType": "text",
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "identifierKey": "text",
          "identifierValue": "text",
          "type": "user"
        },
        "userContacts": [
          {
            "id": "123e4567-e89b-12d3-a456-426614174000",
            "identifierKey": "text",
            "identifierValue": "text",
            "type": "text"
          }
        ]
      },
      "type": "invalid",
      "useCaseType": "unspecified"
    }
  ]
}

Retrieving media

Retrieve pre-signed media uploads

For media that you have uploaded to be sent in a channels message you can retrieve this as follows

Example

Request

curl -L -X GET "https://media.api.bird.com/workspaces/42263973-4f1c-40db-bf0e-cea7e4bfa1a2/media/d30aee15-6ac6-408c-89b6-2906df15ca7b" \
-H "Authorization: AccessKey abcd" \
--output downloadimage.jpeg

Retrieve media from incoming messages

For media sent to your channel you can download this media from the following endpoint

The endpoint is in the message under mediaUrl.

Request

curl -L -X GET "https://media.api.bird.com/workspaces/{workspaceId}/messages/{messageID}/media/{fileId}" \
-H "Authorization: AccessKey abcd" \
--output downloadimage.jpeg