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
Send a message to a channel
The ID of the workspace
The ID for a channel
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: 2682
{
"sender": {
"connector": {
"identifierValue": "[email protected]",
"annotations": {
"name": "text"
}
}
},
"receiver": {
"contacts": [
{
"id": "a1405560-c8d3-4b1a-877d-3f449ad95352",
"identifierKey": "emailaddress",
"identifierValue": "[email protected]",
"type": "cc",
"identifiers": [
{
"identifierKey": "emailaddress",
"identifierValue": "[email protected]"
}
],
"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"
},
"variables": {
"default": "text",
"ANY_ADDITIONAL_PROPERTY": "text"
},
"utmParameters": [
{
"key": "text",
"value": "text"
}
],
"parameters": [
{
"type": "string",
"key": "text",
"value": "text"
}
],
"settings": {
"useMmLite": 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"
}
},
"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"
}
}
}
},
"notification": {
"url": "text"
},
"capFrequency": true,
"enableLinkTracking": true,
"ignoreQuietHours": true,
"ignoreGlobalHoldout": true,
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-10T00:47:06.478Z",
"validity": 1
}
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"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"
}
},
"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"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-07-10T00:47:06.478Z",
"createdAt": "2025-07-10T00:47:06.478Z",
"updatedAt": "2025-07-10T00:47:06.478Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-10T00:47:06.478Z",
"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",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}
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 template
field.
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": "+31612345678"
}
]
},
"body": {...},
}
Template
{
"receiver": {
"contacts": [
{
"identifierValue": "+31612345678"
}
]
},
"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.
The ID of the workspace
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": {}
}
The ID of the workspace
The ID for a channel
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.
curl -X POST \
# uploadFormData
-F Content-Type='...' \
-F acl='private' \
-F bucket='channels..' \
-F key='b2d..b123' \
-F policy='eyJle...dfQ==' \
-F x-amz-algorithm='AWS4-HMAC-SHA256' \
-F x-amz-credential='ASIA..' \
-F x-amz-date='20230501T192504Z' \
-F x-amz-meta-allowed-paths='workspace\b2..' \
-F x-amz-meta-channel-id='ac0..f19e' \
-F x-amz-security-token='IQoo..qqq' \
-F x-amz-signature='RcU9...XLw=' \
# the file to upload
-F [email protected] \
# the URL
https://channels...s3.amazonaws.com/
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
It retrieves a list of messages from a given channel ID
The ID of the workspace
The ID for a channel
Limits the number of results to return
10
Pagination token that keeps of track of the current position in the list
Order in which to retrieve the results
false
Filter based on platform name
^[A-Za-z0-9-]+$
Start date for the query
End date for the query
sender identifier for the message
recipient identifier for the message
Filter based on tag
Full text search on email subject
The ID for a batch
GET /workspaces/{workspaceId}/channels/{channelId}/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*
{
"startAt": "2025-07-10T00:47:06.478Z",
"endAt": "2025-07-10T00:47:06.478Z",
"nextPageToken": "text",
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"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"
}
},
"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"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-07-10T00:47:06.478Z",
"createdAt": "2025-07-10T00:47:06.478Z",
"updatedAt": "2025-07-10T00:47:06.478Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-10T00:47:06.478Z",
"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",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}
]
}
Retrieve list of messages of a workspace
It retrieves a list of messages from a given workspace ID
The ID of the workspace
Limits the number of results to return
10
The ID for a channel
Pagination token that keeps of track of the current position in the list
Order in which to retrieve the results
false
Filter based on platform name
^[A-Za-z0-9-]+$
Start date for the query
End date for the query
sender identifier for the message
recipient identifier for the message
Filter based on tag
Full text search on email subject
The ID for a batch
GET /workspaces/{workspaceId}/channels/messages HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*
{
"startAt": "2025-07-10T00:47:06.478Z",
"endAt": "2025-07-10T00:47:06.478Z",
"nextPageToken": "text",
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"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"
}
},
"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"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-07-10T00:47:06.478Z",
"createdAt": "2025-07-10T00:47:06.478Z",
"updatedAt": "2025-07-10T00:47:06.478Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-10T00:47:06.478Z",
"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",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}
]
}
Retrieve a single message
Get a channel message
The ID of the workspace
The ID for a message
The ID for a channel
GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"sender": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"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"
}
},
"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"
}
},
"reference": "my-own-identifier",
"parts": [
{
"platformReference": "text"
}
],
"status": "accepted",
"reason": "text",
"direction": "incoming",
"origin": {
"type": "text",
"id": "text"
},
"replyTo": {
"id": "text",
"order": 1,
"type": "message"
},
"lastStatusAt": "2025-07-10T00:47:06.478Z",
"createdAt": "2025-07-10T00:47:06.478Z",
"updatedAt": "2025-07-10T00:47:06.478Z",
"details": "text",
"failure": {
"code": 1,
"description": "Unsupported media type",
"source": {
"code": "text",
"name": "text"
}
},
"tags": [
"text"
],
"shortLinks": {
"domain": "text"
},
"scheduledFor": "2025-07-10T00:47:06.478Z",
"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",
"length": 1
}
]
}
},
"telegram": {
"parseMode": "Markdown"
}
}
}
}
}
Retrieve all message interactions on a message
List message interactions
The ID of the workspace
The ID for a message
The ID for a channel
GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/interactions HTTP/1.1
Host: api.bird.com
Authorization: AccessKey YOUR_SECRET_TOKEN
Accept: */*
{
"results": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"messageId": "123e4567-e89b-12d3-a456-426614174000",
"channelId": "123e4567-e89b-12d3-a456-426614174000",
"platformId": "text",
"type": "clicked",
"messageReference": "text",
"messagePartsCount": 1,
"messageTags": [
"text"
],
"receiver": {
"connector": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"identifierValue": "text",
"annotations": {
"name": "text"
},
"types": [
"text"
]
}
},
"createdAt": "2025-07-10T00:47:06.478Z",
"details": "text",
"context": {
"id": "text",
"type": "text",
"tags": [
"text"
]
},
"metadata": {
"link": {
"name": "text",
"url": "text"
},
"button": {
"payload": "text"
},
"reaction": {
"emoji": "text",
"action": "text"
},
"conversion": {
"type": "text",
"status": "text",
"method": "text",
"timestamp": "2025-07-10T00:47:06.478Z"
},
"prefetched": true,
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}
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
Retrieve media from incoming messages
For media sent to your channel you can download this media from the following endpoint
Last updated
Was this helpful?