--- url: >- https://docs.corbitaltech.dev/products/whatsmark-saas/api/send-auth-templates.md description: >- Learn how to send authentication templates via API including auto-generate OTP, manual OTP, and contact creation functionality. --- # Send Auth Templates API ::: info Complete API Documentation For the complete API documentation including authentication, rate limits, and all available endpoints, visit the [WhatsMark SaaS API Documentation](/products/whatsmark-saas/api/index.md). ::: ::: warning 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 ``` ::: tip Getting Your API Token You can generate and manage API tokens from the [API Management](/products/whatsmark-saas/tenant/api-management.md) 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:** | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | --------------------------------------------- | | `phone_number` | string | Yes | Recipient's WhatsApp number with country code | | `template_name` | string | Yes | Name of the approved template | | `template_language` | string | Yes | Language code of the template (e.g., en, hi) | | `auto_generate_otp` | boolean | Yes | Set 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:** | Parameter | Type | Required | Description | | ------------------- | ------ | -------- | --------------------------------------------- | | `phone_number` | string | Yes | Recipient's WhatsApp number with country code | | `template_name` | string | Yes | Name of the approved template | | `template_language` | string | Yes | Language code of the template | | `field_1` | string | Yes | Your 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 ::: info 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": "test@example.com" } }' ``` **Parameters:** | Parameter | Type | Required | Description | | ------------------- | ------- | -------- | --------------------------------------------- | | `phone_number` | string | Yes | Recipient's WhatsApp number with country code | | `template_name` | string | Yes | Name of the approved template | | `template_language` | string | Yes | Language code of the template | | `auto_generate_otp` | boolean | Yes | Set to `true` to auto-generate OTP | | `contact` | object | Yes | Contact information object | | `contact.firstname` | string | Yes | Contact's first name | | `contact.lastname` | string | No | Contact's last name | | `contact.email` | string | No | Contact'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 ::: tip 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 Code | Description | | ----------- | ------------------------------------------- | | `400` | Bad Request - Invalid parameters | | `401` | Unauthorized - Invalid or missing API token | | `404` | Not Found - Template or tenant not found | | `422` | Unprocessable Entity - Validation errors | | `500` | Internal 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 ## Related Documentation * [API Management](/products/whatsmark-saas/tenant/api-management.md) - Generate and manage API tokens * [Template Library](/products/whatsmark-saas/tenant/templates-library.md) - Manage your WhatsApp templates * [Contact Management](/products/whatsmark-saas/tenant/contact-management.md) - Understanding contact records ## Support If you encounter any issues or have questions about the API: * Visit our [FAQ page](/products/whatsmark-saas/faq.md) * Contact our support team at [support.corbitaltech.dev](https://support.corbitaltech.dev/) * Check our [Release Notes](/products/whatsmark-saas/releases.md) for the latest updates