Programmable Push Notifications

Sending push notifications

In order to send a push notification, you must have an active Push Notifications channel installed in your workspace with valid credentials for the gateway(s) you intend to use (Firebase Cloud Messaging for Android, APNs for iOS, or VAPID for Web Push). Send a push by performing an HTTP request to the channel's messages endpoint with a valid access key.

Send a message

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

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

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 was rejected for exceeding a size limit: the total request body must not exceed 200 KB, and a single attachment's inline content must not exceed 100 KB.

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-08-10T23:41:11.238Z",
  "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-08-10T23:41:11.238Z",
          "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-08-10T23:41:11.238Z",
  "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-08-10T23:41:11.238Z",
  "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-08-10T23:41:11.238Z",
        "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-08-10T23:41:11.238Z"
    },
    "useFallback": true
  },
  "parts": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "order": 1,
      "platformReferenceId": "text",
      "platformStatusAt": "2026-08-10T23:41:11.238Z",
      "rawBody": "text",
      "reason": "text",
      "status": "accepted",
      "statusAt": "2026-08-10T23:41:11.238Z"
    }
  ],
  "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-08-10T23:41:11.238Z"
  },
  "scheduledFor": "2026-08-10T23:41:11.238Z",
  "sendAt": "2026-08-10T23:41:11.238Z",
  "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-08-10T23:41:11.238Z",
            "callPermissionResponse": "accept",
            "previewUrl": true
          }
        },
        "text": "text"
      },
      "type": "text"
    },
    "utmParameters": [
      {
        "key": "text",
        "value": "text"
      }
    ],
    "variables": {
      "ANY_ADDITIONAL_PROPERTY": "text"
    },
    "version": "text"
  },
  "updatedAt": "2026-08-10T23:41:11.238Z"
}

---

Receiver identifier

Push notifications use a channel-scoped identifier key and a gateway-prefixed identifier value. This differs from SMS/WhatsApp where the identifier key is phonenumber and the value is a raw E.164 number.

• identifierKey must be push-{channelId} — the literal string push- followed by the UUID of the push channel you are sending through. This is the same channel UUID that appears in the request URL.

• identifierValue must be {gateway}:{deviceToken} where {gateway} is one of:

  • firebase — for Android devices registered with Firebase Cloud Messaging (FCM v1)

  • apns — for iOS devices registered with Apple Push Notification service

  • web — for browsers registered with the Web Push protocol via VAPID

A bare device token without the gateway prefix is rejected.

Example receiver block:

{
  "receiver": {
    "contacts": [
      {
        "identifierKey":   "push-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "identifierValue": "firebase:fK3xLp9aQ8m...:APA91bF..."
      }
    ]
  }
}

Note: FCM tokens contain : characters internally — only the first colon (separating the gateway from the token) is parsed by Bird. The rest of the value is treated as one opaque token string.

---

Push notification body

Push messages use body.type: "list" with title and text fields. The text body type used by SMS, WhatsApp, and email is not supported by the push platform.

Field	Description
body.type	Must be "list".
body.list.title	The notification title that appears in bold at the top of the system notification.
body.list.text	The notification body text below the title.

Example:

{
  "body": {
    "type": "list",
    "list": {
      "title": "New message",
      "text":  "Hello from your app"
    }
  }
}

Full request examples

Send to an Android device (Firebase)

{
  "receiver": {
    "contacts": [
      {
        "identifierKey":   "push-{channelId}",
        "identifierValue": "firebase:{fcm_device_token}"
      }
    ]
  },
  "body": {
    "type": "list",
    "list": {
      "title": "New message",
      "text":  "Hello from your app"
    }
  }
}

Send to an iOS device (APNs)

{
  "receiver": {
    "contacts": [
      {
        "identifierKey":   "push-{channelId}",
        "identifierValue": "apns:{apns_device_token}"
      }
    ]
  },
  "body": {
    "type": "list",
    "list": {
      "title": "New message",
      "text":  "Hello from your app"
    }
  }
}

Send to a browser (Web Push)

{
  "receiver": {
    "contacts": [
      {
        "identifierKey":   "push-{channelId}",
        "identifierValue": "web:{web_push_subscription_token}"
      }
    ]
  },
  "body": {
    "type": "list",
    "list": {
      "title": "New message",
      "text":  "Hello from your app"
    }
  }
}

---

Troubleshooting

If a send fails, the failure.reason field on the message contains the underlying error. Fetch the message via GET /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId} and check that field.

The three most common failure modes are payload-shape mismatches. Match the symptom to the fix:

failure.reason contains	Fix
invalid identifier value format, missing gateway type prefix	The identifierValue is missing the gateway prefix. Prepend firebase:, apns:, or web: to the device token.
PlatformAddress does not match any selector (visible in worker logs) / message stuck in sending_failed with no token-shaped value	The identifierKey is wrong. It must be push-{channelId}, not pushtoken, user_id, emailaddress, etc.
message body is empty	The body.type is something other than list (most commonly text). Switch to list with list.title and list.text.

Other failures (expired device tokens, FCM/APNs auth errors, throttling) are surfaced from the gateway response and should be self-explanatory.