corbitaltech

Appearance

Send Auth Templates API ​

Complete API Documentation

For the complete API documentation including authentication, rate limits, and all available endpoints, visit the WhatsMark SaaS API Documentation.

API Version Notice

These APIs are currently version v1. Please note that v1 will be deprecated after the release of v2. We recommend staying updated with our release notes for v2 migration guides.

Overview ​

The Send Auth Templates API allows you to send WhatsApp authentication templates programmatically. This is particularly useful for sending OTP (One-Time Password) messages for user verification and authentication flows.

API Endpoint ​

POST https://your-domain.com/api/v1/{tenant-name}/messages/template

Path Parameters:

  • tenant-name - Your tenant identifier in WhatsMark SaaS

Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_TOKEN

Getting Your API Token

You can generate and manage API tokens from the API Management section in your tenant settings.

Use Cases ​

1. Auto-Generate OTP ​

This method allows WhatsMark SaaS to automatically generate the OTP for you and send it to the specified phone number.

Request:

bash
curl -X POST "https://your-domain.com/api/v1/tenant-name/messages/template" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "phone_number": "+919925119284",
    "template_name": "verify_otp",
    "template_language": "en",
    "auto_generate_otp": true
  }'

Parameters:

ParameterTypeRequiredDescription
phone_numberstringYesRecipient's WhatsApp number with country code
template_namestringYesName of the approved template
template_languagestringYesLanguage code of the template (e.g., en, hi)
auto_generate_otpbooleanYesSet to true to auto-generate OTP

How It Works:

  • WhatsMark SaaS generates a random OTP
  • The OTP is automatically inserted into your template
  • The message is sent to the specified phone number
  • You can retrieve the generated OTP from the response

2. Manual OTP ​

Use this method when you want to send an OTP generated by your own system or any third-party platform.

Request:

bash
curl -X POST "https://your-domain.com/api/v1/tenant-name/messages/template" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "phone_number": "+919925119284",
    "template_name": "verify_otp",
    "template_language": "en",
    "field_1": "123456"
  }'

Parameters:

ParameterTypeRequiredDescription
phone_numberstringYesRecipient's WhatsApp number with country code
template_namestringYesName of the approved template
template_languagestringYesLanguage code of the template
field_1stringYesYour custom OTP or template variable value

How It Works:

  • You provide the OTP generated by your system
  • The OTP is passed as field_1 (or field_2, field_3, etc., depending on your template structure)
  • WhatsMark SaaS sends the template with your provided OTP

Template Variables

The field numbers (field_1, field_2, etc.) correspond to the variables in your WhatsApp template. Make sure they match your template's variable order.

3. Send Auth Template with Contact Creation ​

This method sends an authentication template and automatically creates a contact in WhatsMark SaaS if the phone number doesn't already exist.

Request:

bash
curl -X POST "https://your-domain.com/api/v1/tenant-name/messages/template" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "phone_number": "+919925119284",
    "template_name": "verify_otp",
    "template_language": "en",
    "auto_generate_otp": true,
    "contact": {
      "firstname": "Test",
      "lastname": "User",
      "email": "[email protected]"
    }
  }'

Parameters:

ParameterTypeRequiredDescription
phone_numberstringYesRecipient's WhatsApp number with country code
template_namestringYesName of the approved template
template_languagestringYesLanguage code of the template
auto_generate_otpbooleanYesSet to true to auto-generate OTP
contactobjectYesContact information object
contact.firstnamestringYesContact's first name
contact.lastnamestringNoContact's last name
contact.emailstringNoContact's email address

How It Works:

  • The API checks if a contact with the phone number exists
  • If not found, creates a new contact with the provided information
  • Generates OTP (if auto_generate_otp is true)
  • Sends the authentication template
  • Links the message to the contact record

Contact Management

This is useful for integrating signup flows where you want to capture user information while sending verification codes.

Response Format ​

Success Response (200 OK):

json
{
  "success": true,
  "message": "Template sent successfully",
  "data": {
    "message_id": "wamid.HBgLOTE5OTI1MTE5Mjg0FQIAERgSQzg4Q0Y5MTU4QTFFOTgxNzQA",
    "phone_number": "+919925119284",
    "otp": "123456",
    "status": "sent"
  }
}

Error Response (400/401/404/422):

json
{
  "success": false,
  "message": "Error description",
  "errors": {
    "phone_number": ["The phone number field is required."]
  }
}

Common Error Codes ​

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API token
404Not Found - Template or tenant not found
422Unprocessable Entity - Validation errors
500Internal Server Error - Contact support

Best Practices ​

  1. Rate Limiting: Be mindful of WhatsApp's rate limits for template messages
  2. Error Handling: Always implement proper error handling in your integration
  3. Token Security: Keep your API tokens secure and never expose them in client-side code
  4. Phone Number Format: Always include country code with + prefix
  5. Template Approval: Ensure your templates are approved by WhatsApp before using them
  6. Test First: Use test phone numbers during development

Support ​

If you encounter any issues or have questions about the API:

© 2024 - Corbital Technologies. All rights reserved.