Taqnyat Whatsapp

Taqnyat Ready Template – Overview

The taqnyat.ready.template model is designed to build, validate, and send pre-configured WhatsApp message templates to the Taqnyat API for approval and use. It supports various WhatsApp message types, including general templates, marketing, utility, and authentication messages.

Key Features:

1. Template Fields & Structure

• name: The internal name of the template. It must be lowercase and contain no spaces, as enforced by the constraint _check_name_no_spaces_and_lowercase.
• language: Selected from the system's active languages via res.lang.
• category: Must be one of UTILITY, MARKETING, or AUTHENTICATION.

2. Dynamic Component Support

The WhatsApp template is composed of several optional components:

• Header: TEXT, IMAGE, VIDEO, or DOCUMENT
• Body: Text or authentication placeholder
• Footer: Text or expiration code
• Buttons: URL, PHONE_NUMBER, or OTP

Boolean flags (has_body, has_header, has_footer, has_buttons) control whether each component is included in the payload.

Special Case: AUTHENTICATION Templates

When category == 'AUTHENTICATION', the structure is fixed and controlled by WhatsApp:

• BODY includes add_security_recommendation
• FOOTER includes code_expiration_minutes
• BUTTONS is always an OTP with type "COPY_CODE" and text "Copy Code"

These constraints are hardcoded in build_components_dict().

build_components_dict() Method

This method generates the final JSON payload that matches Taqnyat’s API schema for WhatsApp template registration.

Example for Utility/Marketing:

{
                  "name": "order_confirmation",
                  "language": "en",
                  "category": "UTILITY",
                  "components": [
                    { "type": "HEADER", "format": "TEXT", "text": "Order Confirmation" },
                    { "type": "BODY", "text": "Hi {{1}}, your order {{2}} has been shipped." },
                    { "type": "FOOTER", "text": "Thanks for shopping with us!" },
                    { "type": "BUTTONS", "buttons": [{ "type": "URL", "text": "Track Order", "url": "https://..." }] }
                  ]
                }
                

Example for AUTHENTICATION:

{
                  "name": "login_code",
                  "language": "en",
                  "category": "AUTHENTICATION",
                  "components": [
                    { "type": "BODY", "add_security_recommendation": true },
                    { "type": "FOOTER", "code_expiration_minutes": 3 },
                    { "type": "BUTTONS", "buttons": [{ "type": "OTP", "otp_type": "COPY_CODE", "text": "Copy Code" }] }
                  ]
                }
                

Sending to Taqnyat API

Calling action_send_to_taqnyat() performs the following:

• Validates the API token from config.
• Builds the payload using build_components_dict().
• Sends the payload to https://api.taqnyat.sa/wa/v2/templates/ via POST.
• If successful (HTTP 201), stores the returned external_id from Taqnyat.
• Displays a success notification and reloads the view.

Supports a special context flag view_payload to preview the payload as JSON for testing/debugging.

Field Validation Highlights:

• name: Must be all lowercase and contain no spaces.
• code_expiration_minutes: Must be greater than or equal to 1.
• language: Must be selected from the system’s active languages.
• Required fields: Vary depending on the selected category.

Summary

This model acts as a template builder and dispatcher for Taqnyat WhatsApp templates. It abstracts all the complexity of formatting, validating, and delivering WhatsApp template components into a user-friendly and API-compliant process — especially helpful for multi-category templates and dynamic field injection.