# 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","scheme":"AccessKey","type":"http"}},"schemas":{"channels.messages.interactions.metadata.conversion":{"properties":{"method":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_method"},"status":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_status"},"timestamp":{"description":"Timestamp of when the conversion was recorded","format":"date-time","type":"string"},"type":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_type"}},"title":"Channel Message Conversion","type":"object"},"channels.messages.interactions.metadata.conversion_method":{"description":"Method of entering the code","enum":["unknown","manual","auto"],"title":"Message Interaction Conversion Method","type":"string"},"channels.messages.interactions.metadata.conversion_status":{"description":"Status of the conversion","enum":["converted","canceled","not_converted","incorrect_code","resent","received_after_expiration"],"title":"Message Interaction Conversion Status","type":"string"},"channels.messages.interactions.metadata.conversion_type":{"description":"Type of conversion","enum":["otp","url","promo_code"],"title":"Message Interaction Conversion Type","type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"requestError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"An error"},"validationError":{"$ref":"#/components/responses/error.response.invalid_request"},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"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/channels.messages.interactions.metadata.conversion"}}}},"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","scheme":"AccessKey","type":"http"}},"schemas":{"channels.messages.interactions.metadata.conversion":{"properties":{"method":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_method"},"status":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_status"},"timestamp":{"description":"Timestamp of when the conversion was recorded","format":"date-time","type":"string"},"type":{"$ref":"#/components/schemas/channels.messages.interactions.metadata.conversion_type"}},"title":"Channel Message Conversion","type":"object"},"channels.messages.interactions.metadata.conversion_method":{"description":"Method of entering the code","enum":["unknown","manual","auto"],"title":"Message Interaction Conversion Method","type":"string"},"channels.messages.interactions.metadata.conversion_status":{"description":"Status of the conversion","enum":["converted","canceled","not_converted","incorrect_code","resent","received_after_expiration"],"title":"Message Interaction Conversion Status","type":"string"},"channels.messages.interactions.metadata.conversion_type":{"description":"Type of conversion","enum":["otp","url","promo_code"],"title":"Message Interaction Conversion Type","type":"string"},"error.detailed":{"additionalProperties":false,"description":"An error returned from the API that includes additional details about the error. The `details` property can contain any additional information about the error that may be helpful for debugging or understanding the error.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":true,"description":"Any additional information about the error that may be helpful for debugging or understanding the error.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"DetailedError","type":"object"},"error.validation":{"additionalProperties":false,"description":"A validation error returned from the API. The `details` map keys are JSON paths\npointing into the request body / parameters; values are arrays of human-readable\nmessages describing each problem with that path.\n","properties":{"code":{"description":"A unique code that identifies the error. This code can be used to programmatically identify the error.","minLength":3,"type":"string"},"details":{"additionalProperties":{"items":{"type":"string"},"type":"array"},"description":"Per-field validation messages keyed by JSON path.","type":"object"},"message":{"description":"A human-readable message that describes the error.","minLength":1,"type":"string"}},"required":["code","message"],"title":"ValidationError","type":"object"}},"responses":{"requestError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.detailed"}}},"description":"An error"},"validationError":{"$ref":"#/components/responses/error.response.invalid_request"},"error.response.invalid_request":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/error.validation"}}},"description":"The request contains invalid parameters or body fields."}}},"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/channels.messages.interactions.metadata.conversion"}}}},"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.