# 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

## Create message conversion

> Create message conversion

```json
{"openapi":"3.0.3","info":{"title":"Channels","version":"v1"},"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"MessageConversion":{"title":"ChannelMessageConversion","type":"object","additionalProperties":false,"required":["type","status"],"properties":{"type":{"type":"string","description":"Type of conversion","enum":["otp","url","promo_code"]},"status":{"type":"string","description":"Status of the conversion","enum":["converted","canceled","not_converted","incorrect_code","resent","received_after_expiration"]},"method":{"type":"string","description":"Method of entering the code","default":"unknown","enum":["unknown","manual","auto"]},"timestamp":{"type":"string","description":"Timestamp of when the conversion was recorded","format":"date-time"}}},"RequestError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"}},"required":["code","message"]},"ValidationError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"]}},"responses":{"requestError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}}},"validationError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/channels/{channelId}/messages/{messageId}/conversions":{"post":{"summary":"Create message conversion","operationId":"createMessageConversion","description":"Create message conversion","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageConversion"}}}},"responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/requestError"},"422":{"$ref":"#/components/responses/validationError"}}}}}}
```

## Create a navigator message conversion

> Create a navigator message conversion

```json
{"openapi":"3.0.3","info":{"title":"Channels","version":"v1"},"tags":[{"name":"channel_message","description":"Messages are the data sent and received through channels."}],"servers":[{"url":"https://api.bird.com","description":"Production API"}],"security":[{"accessKey":[]}],"components":{"securitySchemes":{"accessKey":{"description":"Uses the Authorization header: 'AccessKey ' followed by your access key token (e.g., 'Authorization: AccessKey AbCdEfGhIjKlMnOpQrStUvWxYzAbCdEfGhIj')","scheme":"AccessKey","type":"http"}},"schemas":{"MessageConversion":{"title":"ChannelMessageConversion","type":"object","additionalProperties":false,"required":["type","status"],"properties":{"type":{"type":"string","description":"Type of conversion","enum":["otp","url","promo_code"]},"status":{"type":"string","description":"Status of the conversion","enum":["converted","canceled","not_converted","incorrect_code","resent","received_after_expiration"]},"method":{"type":"string","description":"Method of entering the code","default":"unknown","enum":["unknown","manual","auto"]},"timestamp":{"type":"string","description":"Timestamp of when the conversion was recorded","format":"date-time"}}},"RequestError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"}},"required":["code","message"]},"ValidationError":{"type":"object","properties":{"code":{"type":"string","description":"A unique code that identifies the error. This code can be used to programmatically identify the error.\n"},"message":{"type":"string","description":"A human-readable message that describes the error. An example is 'The requested resource does not exist: channel not found'.\n"},"details":{"type":"object","description":"Additional details about the error. This object can contain any additional information that may be useful for debugging.\n","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"]}},"responses":{"requestError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RequestError"}}}},"validationError":{"description":"The request did not pass validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"paths":{"/workspaces/{workspaceId}/navigators/{navigatorId}/messages/{messageId}/conversions":{"post":{"summary":"Create a navigator message conversion","operationId":"createNavigatorMessageConversion","description":"Create a navigator message conversion","tags":["channel_message"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageConversion"}}}},"responses":{"204":{"description":"OK"},"404":{"$ref":"#/components/responses/requestError"},"422":{"$ref":"#/components/responses/validationError"}}}}}}
```