Send Template Message (Number) - Lancepilot API Documentation

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

{
  "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:

{
  "template_id": 123,
  "template_data": {}
}

2. Body with Variables

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

{
  "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\}\}!"

{
  "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)

{
  "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)

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

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

Uploading Video File

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

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

Uploading Document File

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:

{
  "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\}\}

{
  "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:

{
  "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:

{
  "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

# 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:

The system validates the phone number format
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
Sends the template message to the newly created contact

Error Responses

Invalid Phone Number

{
  "message": "Invalid Number"
}

Invalid Template ID

{
  "message": "Template not found"
}

Missing Required Variables

{
  "message": "The body.variables field is required.",
  "errors": {
    "body.variables": ["The body.variables field is required."]
  }
}

Variable Count Mismatch

{
  "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

{
  "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

{
  "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."]
  }
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

workspace

string<uuid>

required

ID of the workspace.

number

string

required

WhatsApp phone number in international format without + symbol (e.g., 14155552671 for US, 447911123456 for UK).

Example:

"14155552671"

Body

template_id

integer

required

ID of the approved template to send.

Example:

123

template_data

object

Template data containing variables and media files. Structure depends on template configuration.

Show child attributes

Response

status

integer

required

Example:

201

message

string

required

Example:

"Resource created successfully."

data

object

required

Created resource data.

Documentation

API Reference

​Description

​Template Components

​Request Payload Structure

​Basic Structure

​Examples by Template Type

​1. Simple Body-Only Template

​2. Body with Variables

​3. Text Header with Variables

​4. Image Header Template

​Option A: Using Image URL (JSON)

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

​5. Video Header Template

​Using Video URL

​Uploading Video File

​6. Document Header Template

​Using Document URL

​Uploading Document File

​7. Authentication/OTP Template

​8. URL Button with Variables

​9. Multiple URL Buttons with Variables

​10. Complex Template (All Components)

​Phone Number Format

​Media File Requirements

​Image Header

​Video Header

​Document Header

​Complete Example with cURL

​Auto-Contact Creation

​Error Responses

​Invalid Phone Number

​Invalid Template ID

​Missing Required Variables

​Variable Count Mismatch

​Body Text Too Long

​Invalid Media File

Authorizations

Path Parameters

Body

Response

Description

Template Components

Request Payload Structure

Basic Structure

Examples by Template Type

1. Simple Body-Only Template

2. Body with Variables

3. Text Header with Variables

4. Image Header Template

Option A: Using Image URL (JSON)

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

5. Video Header Template

Using Video URL

Uploading Video File

6. Document Header Template

Using Document URL

Uploading Document File

7. Authentication/OTP Template

8. URL Button with Variables

9. Multiple URL Buttons with Variables

10. Complex Template (All Components)

Phone Number Format

Media File Requirements

Image Header

Video Header

Document Header

Complete Example with cURL

Auto-Contact Creation

Error Responses

Invalid Phone Number

Invalid Template ID

Missing Required Variables

Variable Count Mismatch

Body Text Too Long

Invalid Media File