Conversions Sharing

Sharing conversion events with Bird help us improve the quality and reduce the cost of of Bird services

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

Create message conversion

post

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

Authorizations

Path parameters

workspaceIdstring · uuidrequired

The ID of the workspace

messageIdstring · uuidrequired

The ID for a message

channelIdstring · uuidrequired

The ID for a channel

Body

timestampstring · date-time

Timestamp of when the conversion was recorded

typestring · enumrequired

Type of conversion

Options: otp, url, promo_code

statusstring · enumrequired

Status of the conversion

Options: converted, canceled, not_converted, incorrect_code, resent, received_after_expiration

methodstring · enum · default: unknown

Method of entering the code

Options: unknown, manual, auto

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url '/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/conversions' \
  --header 'Authorization: Bearer jwt' \
  --header 'Content-Type: application/json' \
  --data '{"type":"otp","status":"converted","method":"unknown"}'

204

404

422

No body

Create a navigator message conversion