Sending messages

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

Send a message

post

Send a message to a channel

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID 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

The request did not pass validation

application/json

404

The request did not pass validation

application/json

409

Creating the message was not possible because of conflicting conditions

application/json

422

The request did not pass validation

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: 2763

{
  "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": {
      "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"
      }
    },
    "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": "2025-12-29T20:08:28.621Z",
  "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-12-29T20:08:28.621Z",
  "createdAt": "2025-12-29T20:08:28.621Z",
  "updatedAt": "2025-12-29T20:08:28.621Z",
  "details": "text",
  "failure": {
    "code": 1,
    "description": "Unsupported media type",
    "source": {
      "code": "text",
      "name": "text"
    }
  },
  "tags": [
    "text"
  ],
  "shortLinks": {
    "domain": "text"
  },
  "scheduledFor": "2025-12-29T20:08:28.621Z",
  "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"
        },
        "apple": {
          "summaryText": "text",
          "appClipPreview": true,
          "appClipRegion": "text"
        }
      }
    }
  }
}

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

Body

{
 "receiver": {
   "contacts": [
     {
       "identifierKey": "applebc-BUSINESS_ACCOUNT_ID",
       "identifierValue": "urn:mbid:EXAMPLE_PARTICIPANT_ID"
     }
   ]
 },
 "body": {...}
}

Template

{
 "receiver": {
   "contacts": [
     {
       "identifierKey": "applebc-BUSINESS_ACCOUNT_ID",
       "identifierValue": "urn:mbid:EXAMPLE_PARTICIPANT_ID"
     }
   ]
 },
 "template": {...}
}

You can send messages to users who have opted in to receiving messages from your Apple Messages business and have not closed the conversation with you. You can check if the conversation is open by making a request as follows. If a 200 is returned it means the conversation window is open. In addition this will return the latest capabilities of the user device (which determines what messages they can receive).

Get channel details for a contact

get

Retrieve channel information for a given contact.

Authorizations

accessKey

HTTPRequired

Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')

Path parameters

workspaceIdstring · uuidRequired

The ID of the workspace

channelIdstring · uuidRequired

The ID for a channel

contactIdstring · uuidRequired

The ID for a contact

Query parameters

contactIdentifierValuestringOptional

The receiver identifier value.

Responses

200

OK

application/json

404

The request did not pass validation

application/json

get

/workspaces/{workspaceId}/channels/{channelId}/contacts/{contactId}

HTTPcURLJavaScriptPython

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

{
  "serviceWindowExpireAt": "2025-12-29T20:08:28.621Z",
  "isPermanentSession": true,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  }
}

The Channels API supports many of the features of Apple Messages; however, due to the omni-channel nature of the API, there may be some differences between the Channels API message and the native Apple API. Here is an overview of the Apple message types and Channels API message types:

Apple Messages API Type	Channels API
Text	Text
Rich link	Text with links
Attachment	Image / File
Apple Maps Link	Location
Quick Reply	Text + actions / Images + actions / File +actions
List Picker	Template
Time Picker	Template
Apple Pay	Template
Authentication	Template
iMessage App	Template
Form	Template

Outbound Messages

Text

Text message

{ "type": "text", "text": { "text": "Single text message" } }

Text with links

Sending a text message containing a link will split the message into a text + rich link and any text after. To ensure the card renders with a visual ensure the URL you are sending has og:image or og:video tags set

{ "type": "text", "text": { "text": "Single text message with a rich link: https://www.apple.com and text after" } }

Text with reply buttons

{ "type": "text", "text": { "text": "Single text message", "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ] } }

Text with postback actions

{ "type": "text", "text": { "text": "Single text message with reply and postback actions", "actions": [ { "type": "postback", "postback": { "text": "Postback action 1", "payload": "postback-payload-1" } }, { "type": "postback", "postback": { "text": "Postback action 2", "payload": "postback-payload-2" } } ] } }

Text with reply actions and summaryText

Setting text.metadata.summaryText will show the Summary Text in the users message list preview

{ "type": "text", "text": { "text": "Single text message", "metadata": { "apple": { "summaryText": "Customised summaryText" } }, "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ] } }

Image

Single image message

{ "type": "image", "image": { "images": [ { "mediaUrl": "https://bird.com/images/image1.jpg" } ] } }

Single image message with text

{ "type": "image", "image": { "images": [ { "mediaUrl": "https://bird.com/images/image1.jpg" } ], "text": "Single image message" } }

Single image message with reply actions

{ "type": "image", "image": { "images": [ { "mediaUrl": "https://bird.com/images/image1.jpg" } ], "text": "Single image message", "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ] } }

Single image message with postback actions

{ "type": "image", "image": { "images": [ { "mediaUrl": "https://bird.com/images/image1.jpg" } ], "text": "Single image message", "actions": [ { "type": "postback", "postback": { "payload": "postback-payload-1", "text": "Postback option 1" } }, { "postback": { "payload": "postback-payload-2", "text": "Postback option 2" }, "type": "postback" } ] } }

File

Single file message

{ "type": "file", "file": { "files": [ { "contentType": "video/mp4", "mediaUrl": "mediaUrl": "https://bird.com/videos/video1.mp4" } ] } }

Single file message with text

{ "type": "file", "file": { "text": "Single file message", "files": [ { "contentType": "video/mp4", "mediaUrl": "https://bird.com/videos/video1.mp4" } ] } }

Single file message with reply actions

{ "type": "file", "file": { "text": "Single file message", "actions": [ { "type": "reply", "reply": { "text": "Reply action 1" } }, { "type": "reply", "reply": { "text": "Reply action 2" } } ], "files": [ { "contentType": "video/mp4", "mediaUrl": "https://bird.com/videos/video1.mp4" } ] } }

Single file message with postback actions

{ "type": "file", "file": { "text": "Single file message", "actions": [ { "type": "postback", "postback": { "payload": "postback-payload-1", "text": "Postback option 1" } }, { "postback": { "payload": "postback-payload-2", "text": "Postback option 2" }, "type": "postback" } ], "files": [ { "contentType": "video/mp4", "mediaUrl": "https://bird.com/videos/video1.mp4" } ] } }

Location

with coordinates

{ "type": "location", "location": { "coordinates": { "latitude": 37.3346438, "longitude": -122.0115469 }, "location": { "label": "Apple Park Way" } } }

with text

{ "type": "text", "text": { "text": "Visit us here: https://maps.apple.com/place?map=explore&address=Apple+Park+Way%2C+Cupertino%2C+CA++95014%2C+United+States&coordinate=37.334644%2C-122.011547&name=Apple+Park+Way" } }

^Template

Basic text template with variable

	{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318", "version":"latest", "locale":"en", "parameters":[ { "type":"string", "key":"name", "value":"Robert" } ] }

List picker template with section list variable

	{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318", "version":"latest", "locale":"en", "parameters":[ { "type":"sectionList", "key":"listpicker", "value": { "sections": [ { "id": "iphone-section", "multipleSelection": false, "title": "iPhone Models", "items": [ { "id": "iphone-pro-item", "type": "reply-action", "replyAction": { "text": "iPhone Pro - Premium performance", "imageUrl": "https://bird.com/images/image1.jpg", "payload": "iphone_pro_selected", "subTitle": "Pro camera system and titanium design" } }, { "id": "iphone-air-item", "type": "reply-action", "replyAction": { "text": "iPhone Air - Ultra lightweight", "imageUrl": "https://bird.com/images/image2.jpg", "payload": "iphone_air_selected", "subTitle": "Sleek design with incredible portability" } }, { "id": "iphone-17-item", "type": "reply-action", "replyAction": { "text": "iPhone 17 - Latest innovation", "imageUrl": "https://bird.com/images/image3.jpg", "payload": "iphone_17_selected", "subTitle": "Next generation features and performance" } } ] } ] } } ] }

Time picker template with time slot list variable

	{ "projectId":"ce6a2fd6-b2fa-4f5a-a2cd-f3bd15883318", "version":"latest", "locale":"en", "parameters":[ { "type":"string", "key":"timeslot", "value": { "timeslots": [ { "id": "slot-1", "startTime": "2025-11-24T09:00:00Z", "duration": 30 }, { "id": "slot-2", "startTime": "2025-11-24T14:00:00Z", "duration": 30 }, { "id": "slot-3", "startTime": "2025-11-25T10:00:00Z", "duration": 30 }, { "id": "slot-4", "startTime": "2025-11-25T15:30:00Z", "duration": 30 }, { "id": "slot-5", "startTime": "2025-11-26T11:00:00Z", "duration": 30 }, { "id": "slot-6", "startTime": "2025-11-27T09:30:00Z", "duration": 30 }, { "id": "slot-7", "startTime": "2025-11-27T16:00:00Z", "duration": 30 }, { "id": "slot-8", "startTime": "2025-11-28T10:00:00Z", "duration": 30 } ] } } ] }