Messaging - Get transaction status after auto-generating an OTP code

📘

NOTE:

To add this product to your account, contact a Telesign expert. This product is available for full-service accounts only.

This page explains how to use an auto-generated one-time passcode (OTP) in a Telesign Messaging transaction and how to retrieve the processing status using get transaction status.

The auto-generated OTP code feature

The auto-generated OTP feature for Messaging allows you to have multiple use cases (including OTP), with only one integration point. You can extend the use cases by defining different templates in your request for each. The OTP code generation is Telesign's responsibility, you do not need generate and provide the code when using this feature. The auto-generated OTP is a number that is between four and nine digits long, the default is seven digits. You can use the OTP auto-generation feature with these channels: WhatsApp, Viber, RCS, SMS, and email. The same OTP code is used by all channels so that the fallback channels can continue the verification process when needed.

Templates for auto-generated OTP codes

The templates that use OTP as a variable are auto-generated based on the features set in your account. Contact our Customer Support Team can help you set up templates. For those channels that support Template Management Service, any parameters that would be mandatory for Template Management Service, need to be empty.

Viber and RCS

A predefined template for these channels is available for use.

• Template name: telesign_otp
• Content: "<otp_code> is your verification code"

For these channels, the template must be named telesign_otp. If any other template name is used, the 3110 status code will be returned ("Invalid request").

SMS templates

For SMS, you can either create a template or use the predefined telesign_otp template. If you want to Telesign to auto-generate an OTP code, please contact Contact our Customer Support Team for assistance.

WhatsApp and email templates

Unlike other channels, WhatsApp and email templates are not predefined templates but are unique for each customer. The templates for the WhatsApp and email channels need to be verified before use and will be created for you with a name that contains "telesign_otp" somewhere in the name such as such as "viatu_telesign_otp_wa_template." Contact our Customer Support Team for assistance.

When to use get transaction status

Get transaction status can be used for all Messaging transactions. You can use get transaction status to retrieve the status of a transaction for up to 12 hours after you send your request. Telesign recommends that you wait 3-5 minutes after a transaction occurs before querying the API to request status.

Get transaction status is one of two methods available for obtaining final delivery status for Messaging transactions. The second method is Messaging - Callback service.

Before you begin

Make sure you have the following before you start

• Messaging: Contact our Customer Support team to request that Messaging is enabled in your account.
• Enable OTP code auto-generation feature: The feature for OTP code auto-generation must also be enabled in your account. Contact our Customer Support Team for assistance.
• Authentication credentials: Your Customer ID and API Key. If you need help finding these items, go to the support article How do I find my Customer ID and API Key.
• Integration with Messaging: You will only be able to use get transaction status if you've made a Messaging request. See Messaging - Overview to learn how to code its integration.
• Reference pages: Keep the Messing - Send a message with advanced features and the Messaging - Get transaction status reference pages handy.

Generate a message with an auto-generated OTP code

1. Send a POST /v1/omnichannel request. Include the param values listed in this chart. Adjust the param values to match the specific channels you want to use for the primary and backup channels - this example uses Viber as the primary channel with two backup channels. See Messaging - Overview for more information about using Messaging.

Because the sub-properties for message.parameters are not used, the message object will look the example below for Viber and RCS. WhatsApp and email will also require telesign_otp as part of the template name but can include additional text as long as the text uses only lowercase letters, numbers and underscores. Maximum length is 512 characters.

 {
  "message": {
    "viber": {
      "template": "telesign_otp"
    }
  }
}

📘

NOTE:

If the feature for OTP code auto-generation is disabled, and you send a request that uses the dedicated template name, template_otp, the transaction is rejected with error code 3112 ("Specified template does not exist for selected channel").

2. After you have sent your request, check the response. Save the value of the property reference_idfrom the response. You will need it to complete the verification flow and get the delivery status.
3. If your request was successful, the end user receives a message on their device. If the send for the specified channel fails, the service tries to send the next specified backup channel (if any).

Complete verification and get delivery status

Once your end user has submitted a potential code through your application, complete the verification flow with a second API call.

1. Send a Get transaction status request.
   • Include the reference_id for the transaction in the reference_id path parameter.
   • Include the end-user's potential code in the verify_code query parameter.

Get transaction status request

An example of a get transaction status request without verify_code as a query parameter:

GET /v1/omnichannel/0123456789ABCDEF0123456789ABCDEF HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

An example of a get transaction status request with verify_code as a query parameter:

GET /v1/omnichannel/0123456789ABCDEF0123456789ABCDEF?verify_code=57244 HTTP/1.1
Authorization: Basic 12345678-9ABC-DEF0-1234-56789ABCDEF0:Uak4fcLTTH/Tv8c/Q6QMwl5t4ck=
Host: rest-ww.telesign.com

2. In the response, check the value of the verify.code_state property to determine if verification is successfully completed. Theverify.code_state property indicates whether the verification code you provided in your request matches that sent by Telesign to the end user. Possible values are:
   • VALID - The codes match. The offered code is valid. Used for get transaction status by reference ID and OTP code.
   • INVALID - The codes do not match and the offered code is not valid. Used for get transaction status by reference ID and OTP code.
   • UNKNOWN - Any other state. Used for get transaction status by reference ID.

The status.code and status.description properties in the payload of that response indicate the delivery status all the way to the end user.

Get transaction status response - by reference ID and OTP code when OTP code is auto-generated

See the Get transaction status reference page for its schema, status codes, and additional response examples.

HTTP/1.1 200 OK  
Content-Type: application/json  
{  
    "status": {  
        "updated_on": "2024-11-12T13:08:37.000000Z",  
        "code": 3000,  
        "description": "Delivered",  
        "last_channel": "whatsapp"  
    },  
    "reference_id": "364C81F5F3D0020C91E7A731DE93A777",  
    "additional_info": {  
        "mcc": "220",  
        "mnc": "05;09;20;11"  
    },  
    "channel_status": [  
        {  
            "viber": {  
                "code": 3112,  
                "description": "Specified template does not exist for selected channel",  
                "reference_id": "364C81F5F40C0120923096EEAF73053E",  
                "updated_on": "2024-11-12T13:08:35.212526Z"  
            }  
        },  
        {  
            "whatsapp": {  
                "code": 3000,  
                "description": "Delivered",  
                "reference_id": "364C81F5F46402189211BDE408330A86",  
                "updated_on": "2024-11-12T13:08:37.000000Z"  
            }  
        }  
    ],  
    "verify": {  
        "code_entered": "50361",  
        "code_state": "VALID"  
    }  
}

📘

NOTE:

The verify object is only returned in the get transaction status response when an OTP code is auto-generated by Telesign. verify.code_enteredand verify.code_state will not appear in the response when you use get transaction status for a request when the OTP wasn't auto-generated by Telesign.