DocumentatieEngagement Platform API
Sign inGet started
Guides
API

Conversions Sharing

Bird allows users to track conversion events to monitor traffic quality and detect network or carrier anomalies.

Requirements

Each conversion event must be associated with either:
  • A channel's messageId
  • A navigator's messageId
This association is mandatory to enable Bird to track metrics for each message path.

Conversion Properties

Type

The type field is mandatory and helps categorize different conversion actions. Conversion rates vary significantly by type - for example, OTP and PIN codes used in 2FA typically convert at 80-90%, while link clicks have lower conversion rates.
Available types:
  • otp: User completed a 2FA step using a one-time password sent via Bird
  • url: User clicked on a URL embedded in a message sent via Bird (applies only to URLs on domains you host; clicks on Bird's URL shortener domains are tracked automatically)
  • promo_code: User activated a promotional code sent via message

Status

The status field indicates the outcome of the conversion event:
Final Statuses:
  • converted: User successfully performed the required action (e.g., entered correct OTP in signup form)
  • canceled: the request that triggered sending a message was canceled and you are not waiting for a receiver action anymore
  • not_converted: User did not complete the expected action
  • resent: User requested a new message or code
  • received_after_expiration: User performed the action after code/URL validity period expired
Temporary Status:
  • incorrect_code: The user attempted the action but provided the wrong code (OTP or promo code only, not applicable to URLs). This status may change if the user retries.

Timestamp

POST
/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/conversions
Create message conversion
Verzoek-payload
method
string
Method of entering the code
Possible values: unknown, manual, auto
status
string
Status of the conversion
Possible values: converted, canceled, not_converted, incorrect_code, resent, received_after_expiration
timestamp
string
Timestamp of when the conversion was recorded
type
string
Type of conversion
Possible values: otp, url, promo_code
Codevoorbeeld
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/conversions' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'
POST
/workspaces/{workspaceId}/navigators/{navigatorId}/messages/{messageId}/conversions
Create a navigator message conversion
Verzoek-payload
method
string
Method of entering the code
Possible values: unknown, manual, auto
status
string
Status of the conversion
Possible values: converted, canceled, not_converted, incorrect_code, resent, received_after_expiration
timestamp
string
Timestamp of when the conversion was recorded
type
string
Type of conversion
Possible values: otp, url, promo_code
Codevoorbeeld
curl -X POST 'https://api.bird.com/workspaces/{workspaceId}/navigators/{navigatorId}/messages/{messageId}/conversions' \
  -H 'Authorization: AccessKey YOUR_ACCESS_KEY'