WA.cr APP - API v2
  1. Authentication (OTP Verification)
WA.cr APP - API v2
  • API v2 Documentation
    • Account
      • Get Account Info
      • Get Usage Statistics
      • Get Plan Limits
    • Authentication (OTP Verification)
      • Send OTP/Verification Code
        POST
      • Resend OTP
        POST
      • Verify OTP
        POST
      • Check OTP Status
        POST
      • List Authentication Templates
        GET
    • Comments
      • Get Comments
      • Add Comment
    • Contacts
      • List Contacts
      • Create Contact
      • Get Contact
      • Update Contact
      • Delete Contact
      • Batch Create Contacts
      • Batch Delete Contacts
    • Groups
      • List Groups
      • Create Group
      • Get Group
      • Update Group
      • Delete Group
      • Add Contacts to Group
      • Remove Contacts from Group
    • Messages
      • Send Text Message
      • Send Template Message
      • Send Media Message
      • Send Interactive Message
      • List Messages
      • Get Message
    • Sources
      • List Sources
      • Create Source
      • Get Source
      • Update Source
      • Delete Source
    • Statuses
      • List Statuses
      • Create Status
      • Get Status
      • Update Status
      • Delete Status
    • Templates
      • List Templates
      • Sync Templates from WhatsApp
      • Get Template
  1. Authentication (OTP Verification)

Send OTP/Verification Code

POST
/auth/send-otp
Send a WhatsApp authentication template for OTP, verification codes, or two-factor authentication.
This endpoint sends an OTP code via a pre-approved AUTHENTICATION category WhatsApp template. It handles contact auto-creation if the phone number doesn't exist in your contacts, and stores the OTP for subsequent verification via /auth/verify.
Required Scope: messages:send

Request Body#

FieldTypeRequiredValidationDescription
phonestringYesmin:10, max:20, regex: digits/+/-/spaces/()Recipient phone number with country code
template_namestringYesMust exist as APPROVED AUTHENTICATION templateName of the authentication template
codestringYesThe OTP/verification code to send
languagestringNomax:10Template language code (default: en)
expiry_minutesintegerNomin:1, max:60Code expiry time in minutes (default: 10)
contact_idintegerNoMust exist in contacts tableExisting contact ID (skips auto-creation)
purposestringNoOTP purpose identifier (default: authentication)
additional_paramsarrayNoAdditional template body parameters beyond code and expiry

Template Requirements#

Template must be APPROVED status
Template must be AUTHENTICATION category
First body parameter ({{1}}) receives the OTP code
Second body parameter ({{2}}), if present, receives the expiry minutes
URL buttons containing otp{{1}} will automatically receive the OTP code

Auto-Contact Creation#

If no contact_id is provided and the phone number doesn't match an existing contact:
A new contact is auto-created with the phone number
Requires default lead status and source to be configured in WhatsApp settings
Subject to the tenant's contact limit (returns FEATURE_LIMIT_EXCEEDED if exceeded)

Response Fields#

FieldTypeDescription
message_idstringWhatsApp message ID
contact_idintegerContact ID (existing or auto-created)
phonestringCleaned phone number
template_namestringTemplate name used
languagestringTemplate language
code_sentbooleanAlways true on success
expiry_minutesintegerCode expiry time in minutes
expires_atstringISO 8601 expiry timestamp
statusstringMessage status (sent)
sent_atstringISO 8601 send timestamp

Error Responses#

StatusError CodeDescription
401UNAUTHORIZEDInvalid or missing API token
403INSUFFICIENT_SCOPEToken missing messages:send scope
403FEATURE_LIMIT_EXCEEDEDContact limit reached (auto-creation)
403CONTACT_OPTED_OUTContact has opted out of messages
403FEATURE_NOT_AVAILABLEWhatsApp templates not available in plan
403FEATURE_LIMIT_EXCEEDEDConversation limit reached
404RESOURCE_NOT_FOUNDTemplate not found or not approved
404NOT_FOUNDContact not found (when contact_id provided)
422VALIDATION_ERRORRequest validation failed or template is not AUTHENTICATION category
422WHATSAPP_NOT_CONFIGUREDWhatsApp not configured for this account
429RATE_LIMIT_EXCEEDEDToo many requests
500MESSAGE_SEND_FAILEDFailed to send WhatsApp message
500INTERNAL_ERRORUnexpected server error

Validation Error Messages#

FieldMessage
phonePhone number is required / Phone number must be at least 10 digits / Phone number can only contain digits, +, -, spaces, and parentheses
template_nameTemplate name is required
codeAuthentication code is required

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Header Params

Body Params application/json

Examples

Responses

🟢200
application/json
Successful response
Body

Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST '/auth/send-otp' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "phone": "+919999999999",
    "template_name": "otp_verification",
    "language": "en",
    "code": "123456",
    "expiry_minutes": 10,
    "purpose": "authentication"
}'
Response Response Example
{}
Modified at 2026-02-25 01:30:04
Previous
Get Plan Limits
Next
Resend OTP
Built with