Providing Conversion Feedback For 2FA/OTP Messages

The Conversion Feedback API enables you to update Plivo on conversions for your critical 2FA/OTP SMS messages.

This feedback plays an important role in ensuring consistently high delivery rates for your 2FA/OTP SMS messages to countries where carrier networks are generally unstable. Feedback

Plivo’s dynamic routing engine ensures that your messages are delivered over the best performing carrier route to the destination mobile network at any given point in time.

Integration Steps

Marking Messages As Trackable

Set the trackable request parameter of the Send SMS API request to True for your 2FA/OTP SMS messages.

Setting trackable to True implies that you intend to report conversion feedback for the SMS.

1
2
3
4
curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"src": "1111111111","dst": "2222222222", "text": "Hi, text from Plivo", “trackable”: true}' \
    https://api.plivo.com/v1/Account/{auth_id}/Message/

In your authentication system, map the Plivo message_uuid returned for the SMS to the verification request by your end user.

Reporting Successful Conversion To Plivo

When the end user successfully authenticates themself using the verification code sent to them via Plivo, make a POST request to the following API endpoint to report the Conversion to Plivo.

POST https://api.labs.plivo.com/v01/account/{auth_id}/message/{MESSAGE_UUID}/conversion/

Required headers

The API only accepts input of the type application/json. All POST requests must be passed as JSON with the Content-Type header set to application/json.

Request Parameters

  • status mandatory, string

    The status of conversion. This can be one of CONVERTED , NOT_CONVERTED or CONVERTED_WITH_OTHERS. Those trackable messages that for which a conversion API request is not received are considered ‘NOT_CONVERTED’ by default.

  • timestamp mandatory, string

    The timestamp of when the status changed - this usually will be different from the timestamp at which the Message had been sent. This has to be in RFC 8601 format. Example: 2017-08-01T11:32:26Z

Example request

1
2
3
4
5
6
7
8
9
curl -X POST \
  https://api.labs.plivo.com/v01/account/{auth_id}/message/{MESSAGE_UUID}/conversion \
  -H 'authorization: Basic <base64 encoded AUTH_ID:AUTH_TOKEN>' \
  -H 'content-type: application/json' \
  -d '{
        "timestamp" : "2018-05-16T09:00:43.511Z",
        "status": "CONVERTED"
    }
'

Example response

1
2
3
4
5
{
        "message": "successfully recorded.",
        "conversion_uuid": "conv-<message-uuid>",
        "message_uuid": "<message-uuid>"
    }