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

# Send Template Message (Number)

> Send a WhatsApp template message to a contact using their phone number. If the contact doesn't exist, it will be automatically created. Templates can include text/media headers, body with variables, footers, and buttons.

### Description

This endpoint allows you to send WhatsApp template messages to a contact using their phone number. If the contact doesn't exist in your workspace, it will be automatically created. Templates can include various components such as headers (text/media), body text with variables, footers, and buttons.

***

## Template Components

Templates may contain the following components:

* **Header**: Text (with variables) or Media (image, video, document)
* **Body**: Message text with dynamic variables (`{{1}}`, `{{2}}`, etc.)
* **Footer**: Static footer text
* **Buttons**: URL buttons (with variables), phone buttons, or quick reply buttons

***

## Request Payload Structure

### Basic Structure

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "variables": ["Header Variable"],
      "file": "https://example.com/image.jpg"
    },
    "body": {
      "variables": ["Variable 1", "Variable 2"]
    },
    "buttons": [
      {
        "type": "URL",
        "variables": ["promo-code-123"]
      }
    ]
  }
}
```

***

## Examples by Template Type

### 1. Simple Body-Only Template

For templates with only body text and no variables:

```json theme={null}
{
  "template_id": 123,
  "template_data": {}
}
```

***

### 2. Body with Variables

Template body: `"Hello \{\{1\}\}, your order \{\{2\}\} is confirmed!"`

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "body": {
      "variables": ["John Doe", "#12345"]
    }
  }
}
```

**Validation Rules:**

* Maximum 20 variables in body
* Each variable max 1000 characters
* Total body length (with variables) max 1024 characters
* Authentication templates: variables max 11 characters, no links allowed

***

### 3. Text Header with Variables

Template header: `"Welcome \{\{1\}\}!"`

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "variables": ["Premium Member"]
    },
    "body": {
      "variables": ["John", "Gold Tier"]
    }
  }
}
```

**Validation Rules:**

* Maximum 1 variable in text header
* Variable max 60 characters
* Total header length (with variables) max 60 characters

***

### 4. Image Header Template

#### Option A: Using Image URL (JSON)

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "file": "https://example.com/product-image.jpg"
    },
    "body": {
      "variables": ["Product Name", "$99.99"]
    }
  }
}
```

#### Option B: Uploading Image File (multipart/form-data)

```bash theme={null}
POST /api/v3/workspaces/{workspace}/contacts/number/{number}/template-messages
Content-Type: multipart/form-data

template_id: 123
template_data[header][file]: [binary image file]
template_data[body][variables][0]: Product Name
template_data[body][variables][1]: $99.99
```

**Validation Rules:**

* Allowed types: jpg, jpeg, png
* Maximum size: 5 MB (5120 KB)

***

### 5. Video Header Template

#### Using Video URL

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "file": "https://example.com/demo-video.mp4"
    },
    "body": {
      "variables": ["John", "Premium Course"]
    }
  }
}
```

#### Uploading Video File

```bash theme={null}
POST /api/v3/workspaces/{workspace}/contacts/number/{number}/template-messages
Content-Type: multipart/form-data

template_id: 123
template_data[header][file]: [binary video file]
template_data[body][variables][0]: John
template_data[body][variables][1]: Premium Course
```

**Validation Rules:**

* Allowed type: video/mp4
* Maximum size: 16 MB (16384 KB)

***

### 6. Document Header Template

#### Using Document URL

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "file": "https://example.com/invoice.pdf"
    },
    "body": {
      "variables": ["Invoice #12345", "$500.00"]
    }
  }
}
```

#### Uploading Document File

```bash theme={null}
POST /api/v3/workspaces/{workspace}/contacts/number/{number}/template-messages
Content-Type: multipart/form-data

template_id: 123
template_data[header][file]: [binary PDF file]
template_data[body][variables][0]: Invoice #12345
template_data[body][variables][1]: $500.00
```

**Validation Rules:**

* Allowed type: application/pdf
* Maximum size: 30 MB (30720 KB)

***

### 7. Authentication/OTP Template

For one-time password templates:

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "body": {
      "variables": ["123456"]
    }
  }
}
```

**Validation Rules:**

* Variables max 11 characters
* No links allowed in variables

***

### 8. URL Button with Variables

Template with dynamic URL button: `https://example.com/promo/\{\{1\}\}`

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "body": {
      "variables": ["John", "SAVE20"]
    },
    "buttons": [
      {
        "type": "URL",
        "variables": ["SAVE20"]
      }
    ]
  }
}
```

**Validation Rules:**

* Each URL button variable max 2000 characters
* Number of variables must match template definition

***

### 9. Multiple URL Buttons with Variables

For templates with multiple URL buttons:

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "body": {
      "variables": ["Order #12345"]
    },
    "buttons": [
      {
        "type": "URL",
        "variables": ["12345"]
      },
      {
        "type": "URL",
        "variables": ["track-code-xyz"]
      }
    ]
  }
}
```

***

### 10. Complex Template (All Components)

Image header + body variables + URL button with variable:

```json theme={null}
{
  "template_id": 123,
  "template_data": {
    "header": {
      "file": "https://example.com/banner.jpg"
    },
    "body": {
      "variables": ["John Doe", "Premium Plan", "$99.99", "December 31, 2025"]
    },
    "buttons": [
      {
        "type": "URL",
        "variables": ["user-123-token-abc"]
      }
    ]
  }
}
```

***

## Phone Number Format

The phone number in the URL should be in international format without the `+` symbol:

* ✅ Correct: `14155552671` (USA), `447911123456` (UK), `919876543210` (India)
* ❌ Incorrect: `+14155552671`, `+44 7911 123456`, `(415) 555-2671`

***

## Media File Requirements

### Image Header

* **Required**: When template has image header
* **Allowed types**: jpg, jpeg, png
* **Maximum size**: 5 MB (5120 KB)

### Video Header

* **Required**: When template has video header
* **Allowed type**: mp4
* **Maximum size**: 16 MB (16384 KB)

### Document Header

* **Required**: When template has document header
* **Allowed type**: PDF
* **Maximum size**: 30 MB (30720 KB)

***

## Complete Example with cURL

```bash theme={null}
# JSON request with image URL to a new contact
curl -X POST "https://lancepilot.com/api/v3/workspaces/123/contacts/number/14155552671/template-messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": 789,
    "template_data": {
      "header": {
        "file": "https://example.com/product.jpg"
      },
      "body": {
        "variables": ["John Doe", "Premium Package", "$149.99"]
      },
      "buttons": [
        {
          "type": "URL",
          "variables": ["promo2025"]
        }
      ]
    }
  }'

# Multipart form-data request with file upload
curl -X POST "https://lancepilot.com/api/v3/workspaces/123/contacts/number/447911123456/template-messages" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "template_id=789" \
  -F "template_data[header][file]=@/path/to/image.jpg" \
  -F "template_data[body][variables][0]=John Doe" \
  -F "template_data[body][variables][1]=Premium Package" \
  -F "template_data[body][variables][2]=$149.99" \
  -F "template_data[buttons][0][type]=URL" \
  -F "template_data[buttons][0][variables][0]=promo2025"
```

***

## Auto-Contact Creation

When sending to a number that doesn't exist in your workspace:

1. The system validates the phone number format
2. Automatically creates a new contact with:
   * Name: "Unknown" (can be updated later)
   * WhatsApp number: The provided number
   * Country: Auto-detected from phone number
   * Timezone: Set based on country
3. Sends the template message to the newly created contact

***

## Error Responses

### Invalid Phone Number

```json theme={null}
{
  "message": "Invalid Number"
}
```

### Invalid Template ID

```json theme={null}
{
  "message": "Template not found"
}
```

### Missing Required Variables

```json theme={null}
{
  "message": "The body.variables field is required.",
  "errors": {
    "body.variables": ["The body.variables field is required."]
  }
}
```

### Variable Count Mismatch

```json theme={null}
{
  "message": "The body.variables must have at least 3 items.",
  "errors": {
    "body.variables": ["The body.variables must have at least 3 items."]
  }
}
```

### Body Text Too Long

```json theme={null}
{
  "message": "Message body with all variable values is too long, it can be max 1024 characters",
  "errors": {
    "body.text": ["Message body with all variable values is too long, it can be max 1024 characters"]
  }
}
```

### Invalid Media File

```json theme={null}
{
  "message": "The header.file must be a file of type: jpg, jpeg, png.",
  "errors": {
    "header.file": ["The header.file must be a file of type: jpg, jpeg, png."]
  }
}
```

***


## OpenAPI

````yaml POST /workspaces/{workspace}/contacts/number/{number}/template-messages
openapi: 3.1.0
info:
  title: Lancepilot API
  description: API for Lancepilot
  version: 1.0.0
  license:
    name: MIT
servers:
  - url: https://lancepilot.com/api/v3
security:
  - bearerAuth: []
paths:
  /workspaces/{workspace}/contacts/number/{number}/template-messages:
    post:
      tags:
        - Template Messages
      summary: Send Template Message (Phone Number)
      description: >-
        Send a WhatsApp template message to a contact using their phone number.
        If the contact doesn't exist, it will be automatically created.
        Templates can include text/media headers, body with variables, footers,
        and buttons.
      parameters:
        - name: workspace
          in: path
          description: ID of the workspace.
          required: true
          schema:
            type: string
            format: uuid
        - name: number
          in: path
          description: >-
            WhatsApp phone number in international format without + symbol
            (e.g., 14155552671 for US, 447911123456 for UK).
          required: true
          schema:
            type: string
            pattern: ^[1-9][0-9]{7,14}$
            example: '14155552671'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                template_id:
                  type: integer
                  example: 123
                  description: ID of the approved template to send.
                template_data:
                  type: object
                  description: >-
                    Template data containing variables and media files.
                    Structure depends on template configuration.
                  properties:
                    header:
                      type: object
                      description: Header data (text variables or media file).
                      properties:
                        variables:
                          type: array
                          description: >-
                            Text header variables (max 1 variable, max 60
                            characters each).
                          maxItems: 1
                          items:
                            type: string
                            maxLength: 60
                          example:
                            - Premium Member
                        file:
                          oneOf:
                            - type: string
                              format: uri
                              description: Media URL for header (image/video/document).
                            - type: string
                              format: binary
                              description: Binary file upload (use multipart/form-data).
                          example: https://example.com/product-image.jpg
                    body:
                      type: object
                      description: Body text variables.
                      properties:
                        variables:
                          type: array
                          description: >-
                            Body variables (max 20 variables, max 1000
                            characters each, max 1024 characters total after
                            replacement).
                          maxItems: 20
                          items:
                            type: string
                            maxLength: 1000
                          example:
                            - John Doe
                            - Premium Package
                            - $149.99
                      required:
                        - variables
                    buttons:
                      type: array
                      description: URL button variables (for dynamic URL parameters).
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - URL
                            example: URL
                          variables:
                            type: array
                            description: URL variables (max 2000 characters each).
                            items:
                              type: string
                              maxLength: 2000
                            example:
                              - promo-code-2025
                        required:
                          - type
                          - variables
              required:
                - template_id
            examples:
              simple_body:
                summary: Simple body-only template
                value:
                  template_id: 123
                  template_data: {}
              body_with_variables:
                summary: Body with variables
                value:
                  template_id: 123
                  template_data:
                    body:
                      variables:
                        - John Doe
                        - '#12345'
              text_header_variables:
                summary: Text header with variables
                value:
                  template_id: 123
                  template_data:
                    header:
                      variables:
                        - Premium Member
                    body:
                      variables:
                        - John
                        - Gold Tier
              image_header_url:
                summary: Image header with URL
                value:
                  template_id: 123
                  template_data:
                    header:
                      file: https://example.com/product-image.jpg
                    body:
                      variables:
                        - Product Name
                        - $99.99
              video_header_url:
                summary: Video header with URL
                value:
                  template_id: 123
                  template_data:
                    header:
                      file: https://example.com/demo-video.mp4
                    body:
                      variables:
                        - John
                        - Premium Course
              document_header_url:
                summary: Document header with URL
                value:
                  template_id: 123
                  template_data:
                    header:
                      file: https://example.com/invoice.pdf
                    body:
                      variables:
                        - 'Invoice #12345'
                        - $500.00
              url_button_variables:
                summary: URL button with variables
                value:
                  template_id: 123
                  template_data:
                    body:
                      variables:
                        - John
                        - SAVE20
                    buttons:
                      - type: URL
                        variables:
                          - SAVE20
              complex_template:
                summary: Complex template (all components)
                value:
                  template_id: 123
                  template_data:
                    header:
                      file: https://example.com/banner.jpg
                    body:
                      variables:
                        - John Doe
                        - Premium Plan
                        - $99.99
                        - December 31, 2025
                    buttons:
                      - type: URL
                        variables:
                          - user-123-token-abc
          multipart/form-data:
            schema:
              type: object
              properties:
                template_id:
                  type: integer
                  example: 123
                template_data[header][file]:
                  type: string
                  format: binary
                  description: >-
                    Image (jpg/jpeg/png, max 5MB), Video (mp4, max 16MB), or
                    Document (pdf, max 30MB).
                template_data[header][variables][0]:
                  type: string
                  description: Text header variable (if applicable).
                template_data[body][variables][0]:
                  type: string
                  description: First body variable.
                template_data[body][variables][1]:
                  type: string
                  description: Second body variable.
                template_data[buttons][0][type]:
                  type: string
                  enum:
                    - URL
                  description: Button type.
                template_data[buttons][0][variables][0]:
                  type: string
                  description: URL button variable.
              required:
                - template_id
      responses:
        '201':
          $ref: '#/components/responses/201'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Only template messages are allowed for this contact
        '401':
          $ref: '#/components/responses/401'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Template not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Invalid Number
                  errors:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
                    example:
                      body.variables:
                        - The body.variables field is required.
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Failed to send message
components:
  responses:
    '201':
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: integer
                example: 201
              message:
                type: string
                example: Resource created successfully.
              data:
                type: object
                description: Created resource data.
            required:
              - status
              - message
              - data
    '401':
      description: ''
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: Unauthenticated.
            required:
              - message
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````