# 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"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bird.com/api/channels-api/api-reference/conversions-sharing.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.