> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conversales.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Template Message

> Send WhatsApp template messages with optional dynamic variables

## Authentication

<ParamField header="X-API-Key" type="string" required>
  Your API key for authentication
</ParamField>

## Request Body

<ParamField body="to" type="string" required>
  Recipient's phone number in international format (e.g., +1234567890)
</ParamField>

<ParamField body="templateName" type="string" required>
  Name of the WhatsApp template to use
</ParamField>

<ParamField body="templateLanguage" type="string" required>
  Language code for the template (e.g., `en`, `en_US`)
</ParamField>

<ParamField body="templateVars" type="object">
  Template variable mappings (only required if template has dynamic variables)

  <Expandable title="Template Variables Properties">
    <ParamField body="header" type="object">
      Header parameter bindings (key-value pairs)

      <Expandable title="Variable Binding">
        <ParamField body="mode" type="string" required>
          Either `custom` or `contactfield`
        </ParamField>

        <ParamField body="value" type="string">
          The value to use when mode is `custom`
        </ParamField>

        <ParamField body="field" type="string">
          The contact field name when mode is `contactfield`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="body" type="object">
      Body parameter bindings (key-value pairs)

      <Expandable title="Variable Binding">
        <ParamField body="mode" type="string" required>
          Either `custom` or `contactfield`
        </ParamField>

        <ParamField body="value" type="string">
          The value to use when mode is `custom`
        </ParamField>

        <ParamField body="field" type="string">
          The contact field name when mode is `contactfield`
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="headerMediaUrl" type="string">
      URL for header media (image, video, document). Must be HTTPS and publicly accessible.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="clientId" type="string">
  Optional client reference ID for tracking
</ParamField>

## Response

<ResponseField name="statusCode" type="number">
  HTTP status code (200 for success)
</ResponseField>

<ResponseField name="message" type="string">
  Success or error message
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="messageId" type="string">
      WhatsApp message ID
    </ResponseField>

    <ResponseField name="status" type="string">
      Message status (sent, queued)
    </ResponseField>

    <ResponseField name="recipient" type="string">
      Recipient phone number
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL - Static Template theme={null}
  curl -X POST "https://backend.conversales.in/api/v1/sendTemplateMessage" \
    -H "X-API-Key: 3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+1234567890",
      "templateName": "hello_world",
      "templateLanguage": "en"
    }'
  ```

  ```bash cURL - With Custom Variables theme={null}
  curl -X POST "https://backend.conversales.in/api/v1/sendTemplateMessage" \
    -H "X-API-Key: 3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI" \
    -H "Content-Type: application/json" \
    -d '{
      "to": "+1234567890",
      "templateName": "order_confirmation",
      "templateLanguage": "en",
      "templateVars": {
        "body": {
          "name": {
            "mode": "custom",
            "value": "John Doe"
          },
          "orderId": {
            "mode": "custom",
            "value": "ORD-12345"
          },
          "amount": {
            "mode": "custom",
            "value": "$99.99"
          }
        }
      },
      "clientId": "order-tracking-12345"
    }'
  ```

  ```javascript JavaScript - Static Template theme={null}
  const response = await fetch(
    "https://backend.conversales.in/api/v1/sendTemplateMessage",
    {
      method: "POST",
      headers: {
        "X-API-Key": "3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        to: "+1234567890",
        templateName: "hello_world",
        templateLanguage: "en",
      }),
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```javascript JavaScript - With Variables theme={null}
  const response = await fetch(
    "https://backend.conversales.in/api/v1/sendTemplateMessage",
    {
      method: "POST",
      headers: {
        "X-API-Key": "3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        to: "+1234567890",
        templateName: "order_confirmation",
        templateLanguage: "en",
        templateVars: {
          body: {
            name: { mode: "custom", value: "John Doe" },
            orderId: { mode: "custom", value: "ORD-12345" },
            amount: { mode: "custom", value: "$99.99" },
          },
        },
        clientId: "order-tracking-12345",
      }),
    }
  );

  const data = await response.json();
  console.log(data);
  ```

  ```python Python - Static Template theme={null}
  import requests

  url = "https://backend.conversales.in/api/v1/sendTemplateMessage"
  headers = {
      "X-API-Key": "3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI",
      "Content-Type": "application/json"
  }
  payload = {
      "to": "+1234567890",
      "templateName": "hello_world",
      "templateLanguage": "en"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```python Python - With Variables theme={null}
  import requests

  url = "https://backend.conversales.in/api/v1/sendTemplateMessage"
  headers = {
      "X-API-Key": "3kJ9mP2nQ8rT5vW7xY1zA4bC6dE8fG0hI",
      "Content-Type": "application/json"
  }
  payload = {
      "to": "+1234567890",
      "templateName": "order_confirmation",
      "templateLanguage": "en",
      "templateVars": {
          "body": {
              "name": {"mode": "custom", "value": "John Doe"},
              "orderId": {"mode": "custom", "value": "ORD-12345"},
              "amount": {"mode": "custom", "value": "$99.99"}
          }
      },
      "clientId": "order-tracking-12345"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "statusCode": 200,
    "message": "Template message sent successfully",
    "data": {
      "messageId": "wamid.HBgNMTIzNDU2Nzg5MAUCABIYFjNFQjBDMTg5RjNCN0Q5OEQyMDhGAA==",
      "status": "sent",
      "recipient": "+1234567890"
    }
  }
  ```

  ```json Error - Missing Required Field theme={null}
  {
    "statusCode": 400,
    "message": "Key: 'ExternalTemplateRequest.To' Error:Field validation for 'To' failed on the 'required' tag",
    "data": null
  }
  ```

  ```json Error - Template Not Found theme={null}
  {
    "statusCode": 500,
    "message": "template 'order_confirmation' with language 'en' not found",
    "data": null
  }
  ```

  ```json Error - Invalid API Key theme={null}
  {
    "statusCode": 401,
    "message": "Invalid API key",
    "data": null
  }
  ```
</ResponseExample>

<Info>
  **Variable Modes:** - `custom` - Use the provided value directly -
  `contactfield` - Look up the value from the contact database using the field
  name
</Info>

<Note>
  Templates must be pre-approved by WhatsApp before use. Variable names must
  match template placeholders exactly. Contact field lookups are case-sensitive.
</Note>

<Tip>
  Use the `clientId` parameter to track messages in your own system. This ID
  will be returned in webhooks and status updates.
</Tip>

<Warning>
  Media URLs (headerMediaUrl) must be HTTPS and publicly accessible. Templates
  with media headers require a valid URL to be provided.
</Warning>