No-code docs

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

Create message conversion

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
typestring · enumRequired

Type of conversion

Possible values:
statusstring · enumRequired

Status of the conversion

Possible values:
methodstring · enumOptional

Method of entering the code

Default: unknownPossible values:
timestampstring · date-timeOptional

Timestamp of when the conversion was recorded

Responses
204
OK
post
POST /workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/conversions HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "type": "otp",
  "status": "converted",
  "method": "unknown",
  "timestamp": "2025-07-12T00:38:34.487Z"
}
No content

Create a navigator message conversion

post

Create a navigator message conversion

Authorizations
Path parameters
workspaceIdstring · uuidRequired

The ID of the workspace

navigatorIdstring · uuidRequired

The ID for a navigator

messageIdstring · uuidRequired

The ID for a message

Body
typestring · enumRequired

Type of conversion

Possible values:
statusstring · enumRequired

Status of the conversion

Possible values:
methodstring · enumOptional

Method of entering the code

Default: unknownPossible values:
timestampstring · date-timeOptional

Timestamp of when the conversion was recorded

Responses
204
OK
post
POST /workspaces/{workspaceId}/navigators/{navigatorId}/messages/{messageId}/conversions HTTP/1.1
Host: 
Authorization: Bearer jwt
Content-Type: application/json
Accept: */*
Content-Length: 93

{
  "type": "otp",
  "status": "converted",
  "method": "unknown",
  "timestamp": "2025-07-12T00:38:34.487Z"
}
No content

Last updated

Was this helpful?