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
- 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.
Parameter | Value | Description | Required? |
---|---|---|---|
channels | Array of channel objects | Add channel objects to the array in the order you want the service to try the channels. | yes |
channels[0] | {"channel":"viber"} | Include viber as the first channel. | yes |
channels[0].fallback_time | A time in seconds. | Specify the time to wait before cascading to the next channel. | no |
channels[1] | {"channel":"rcs"} | Include rcs as the backup channel. | yes (if RCS is used for backup) |
channels[2] | `{"channel":"sms"} | Include sms as the third backup channel. | yes (if SMS is used for backup) |
recipient.phone_number | string | The recipient's phone number, as digits without spaces or special characters, beginning with the country dialing code. | yes (if RCS, SMS, WhatsApp, Viber, or MMS is selected as a channel.) |
recipient.email | string | The recipient's email address. | yes (if email is selected as a channel.) |
message.<channel>.template | string WhatsApp must contain telesign_otp in the name. | The name of the template to use for this message. Use only lowercase letters, numbers and underscores. Maximum length is 512 characters. | yes |
message.<channel>.parameters | object | Contains sub-properties with values for variables in the message template. However, for auto-generated OTPs, these properties are not used and should not be included. | no (do not use these sub-properties.) |
message_type | OTP | The purpose for which the message is being sent. Choose OTP from the choices offered. | yes |
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").
- After you have sent your request, check the response. Save the value of the property
reference_id
from the response. You will need it to complete the verification flow and get the delivery status. - 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.
- Send a Get transaction status request.
- Include the
reference_id
for the transaction in thereference_id
path parameter. - Include the end-user's potential code in the
verify_code
query parameter.
- Include the
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
- 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_entered
andverify.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.
Updated 15 days ago