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

# Send Template

> Send a single WhatsApp template message to a contact. Each request sends one approved template to one recipient, with support for named/positional body parameters, button URL parameters, and header media.

## Requirements
- Organization must have Meta WhatsApp provider configured
- Contact must already exist (or will be auto-created if `name` body parameter is provided)
- Valid API key with `fiq_` prefix
- Template must be approved in Meta Business Manager

<Note>
  Send a single WhatsApp template message to a contact. Each request sends one approved template to one recipient.
</Note>

## Basic Usage

```bash theme={null}
curl -X POST "https://api.flowiq.live/send-template" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "welcome_message",
    "whatsappNumber": "+27 79 497 5464"
  }'
```

<Tip>
  Phone numbers are automatically normalized. Formats like `+27 79 497 5464`, `0794975464`, and `27794975464` all resolve to the same contact.
</Tip>

### With Template Parameters

```bash theme={null}
curl -X POST "https://api.flowiq.live/send-template" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "order_update",
    "whatsappNumber": "+27123456789",
    "bodyParameters": {
      "name": "{{first_name}}",
      "order_status": "shipped"
    },
    "buttonParameters": {
      "tracking_url": "ABC123"
    }
  }'
```

### With Header Media

```bash theme={null}
curl -X POST "https://api.flowiq.live/send-template" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "templateName": "promo_image",
    "whatsappNumber": "+27123456789",
    "headerMedia": "https://example.com/promo-banner.jpg",
    "bodyParameters": {
      "name": "{{first_name}}",
      "discount": "20%"
    }
  }'
```

***

## Request Body

| Field              | Type   | Required | Description                                              |
| ------------------ | ------ | -------- | -------------------------------------------------------- |
| `templateName`     | string | Yes      | Name of the approved WhatsApp template                   |
| `whatsappNumber`   | string | Yes      | Recipient phone number (automatically normalized)        |
| `bodyParameters`   | object | No       | Key-value pairs for template body variables              |
| `buttonParameters` | object | No       | Key-value pairs for template button URL variables        |
| `headerMedia`      | string | No       | URL for the template header media (image/video/document) |
| `memberId`         | string | No       | Team member UUID (marks message as sent by human agent)  |

***

## Template Parameters

WhatsApp templates support two parameter formats. The endpoint handles both automatically based on the template's configuration.

### Named Parameters

For templates using named variables like `{{name}}`, `{{shop}}`:

```json theme={null}
{
  "bodyParameters": {
    "name": "{{first_name}}",
    "shop": "FlowIQ Store"
  }
}
```

### Positional Parameters

For templates using positional variables like `{{1}}`, `{{2}}`:

```json theme={null}
{
  "bodyParameters": {
    "1": "{{first_name}}",
    "2": "Your order has shipped"
  }
}
```

***

## Contact Field Substitution

Parameter values can include placeholders that are automatically replaced with the recipient's contact data:

| Placeholder        | Replaced With                                   |
| ------------------ | ----------------------------------------------- |
| `{{first_name}}`   | Contact's first name (extracted from full name) |
| `{{full_name}}`    | Contact's full name                             |
| `{{email}}`        | Contact's email address                         |
| `{{phone_number}}` | Contact's phone number                          |
| `{{whatsapp_id}}`  | Contact's WhatsApp ID                           |

<Tip>
  `{{first_name}}` uses intelligent extraction — it strips emojis, ignores phone-number-only names, and falls back to "there" for unrecognizable names. For example, a contact named "🎉 John Smith" resolves to "John".
</Tip>

***

## Button URL Parameters

For templates with dynamic URL buttons (e.g. `https://example.com/track/{{1}}`), pass the variable portion in `buttonParameters`:

### Named Button Parameters

```json theme={null}
{
  "buttonParameters": {
    "order_id": "ORD-12345"
  }
}
```

### Positional Button Parameters

```json theme={null}
{
  "buttonParameters": {
    "param1": "ORD-12345"
  }
}
```

***

## Header Media Types

Templates with media headers (image, video, document) require the `headerMedia` field with a publicly accessible URL.

| Header Type | Max Size | Supported Formats                    |
| ----------- | -------- | ------------------------------------ |
| Image       | 5 MB     | JPEG, PNG                            |
| Video       | 16 MB    | MP4                                  |
| Document    | 100 MB   | PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX |

***

## Auto-Create Contact

When the phone number doesn't match any existing contact, the endpoint can automatically create the contact if a `name` body parameter is provided:

```json theme={null}
{
  "templateName": "welcome_message",
  "whatsappNumber": "+27123456789",
  "bodyParameters": {
    "name": "John Doe"
  }
}
```

The new contact is created with `contact_source: "send_template_auto_create"` and the message is sent immediately.

<Note>
  If the phone number has no existing contact and no `name` body parameter is provided, a 400 error is returned with a message suggesting you provide `bodyParameters.name` to auto-create.
</Note>

***

## Response

### Success (200)

```json theme={null}
{
  "success": true,
  "summary": {
    "total": 1,
    "successful": 1,
    "failed": 0
  },
  "results": [
    {
      "contactId": "contact-uuid",
      "contactName": "John Doe",
      "success": true,
      "messageId": "wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI...",
      "error": null
    }
  ],
  "broadcastId": "broadcast-uuid-here"
}
```

### Failed (200)

When the message fails to send, `success` is `false` and the error is surfaced:

```json theme={null}
{
  "success": false,
  "summary": {
    "total": 1,
    "successful": 0,
    "failed": 1
  },
  "results": [
    {
      "contactId": "contact-uuid",
      "contactName": "John Doe",
      "success": false,
      "messageId": null,
      "error": "Template not found in Meta API"
    }
  ],
  "error": "Template not found in Meta API",
  "broadcastId": "broadcast-uuid-here"
}
```

### Error: Missing Template (400)

```json theme={null}
{
  "error": "Template name is required"
}
```

### Error: Missing Phone Number (400)

```json theme={null}
{
  "error": "whatsappNumber is required",
  "example": {
    "templateName": "your_template",
    "whatsappNumber": "+27 79 123 4567",
    "bodyParameters": { "name": "Sam" }
  }
}
```

### Error: Contact Not Found (400)

```json theme={null}
{
  "error": "Contact not found",
  "message": "No contact found with number +27123456789. Provide bodyParameters.name to auto-create."
}
```

***

## Integration Example

```javascript theme={null}
async function sendTemplate(apiKey, templateName, whatsappNumber, params) {
  const response = await fetch(
    "https://api.flowiq.live/send-template",
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        templateName,
        whatsappNumber,
        bodyParameters: params,
      }),
    }
  );
  const data = await response.json();
  if (!response.ok) throw new Error(data.message || data.error);
  return data;
}

const result = await sendTemplate(
  "fiq_YOUR_API_KEY",
  "welcome_message",
  "+27123456789",
  { name: "{{first_name}}", promo: "SAVE20" }
);

console.log(`Message ID: ${result.results[0].messageId}`);
```

***

<Card title="Template Approval" icon="circle-check">
  Templates must be approved in your Meta Business Manager before they can be
  sent via this endpoint. Unapproved or rejected templates will return an error.
</Card>


## OpenAPI

````yaml flowiq-api-reference/openapi-send-template.json POST /send-template
openapi: 3.1.0
info:
  title: FlowIQ - Send Template
  version: 1.0.0
servers:
  - url: https://api.flowiq.live
    description: FlowIQ Production API
security:
  - BearerAuth: []
paths:
  /send-template:
    post:
      tags:
        - Endpoints
      summary: Send Template
      description: >-
        Send a single WhatsApp template message to a contact. Each request sends
        one approved template to one recipient, with support for
        named/positional body parameters, button URL parameters, and header
        media.


        ## Requirements

        - Organization must have Meta WhatsApp provider configured

        - Contact must already exist (or will be auto-created if `name` body
        parameter is provided)

        - Valid API key with `fiq_` prefix

        - Template must be approved in Meta Business Manager
      operationId: sendTemplate
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                templateName:
                  type: string
                  description: Name of the approved WhatsApp template
                  example: welcome_message
                whatsappNumber:
                  type: string
                  description: Recipient phone number (automatically normalized)
                  example: '+27123456789'
                bodyParameters:
                  type: object
                  description: >-
                    Key-value pairs for template body variables. Supports named
                    (e.g. `name`, `shop`) or positional (e.g. `1`, `2`) keys.
                    Values can include contact field placeholders like
                    `{{first_name}}`.
                  example:
                    name: '{{first_name}}'
                    order_status: shipped
                buttonParameters:
                  type: object
                  description: Key-value pairs for template button URL variables
                  example:
                    tracking_url: ABC123
                headerMedia:
                  type: string
                  description: >-
                    Publicly accessible URL for template header media (image,
                    video, or document)
                  example: https://example.com/promo-banner.jpg
                memberId:
                  type: string
                  format: uuid
                  description: >-
                    Team member UUID — marks the message as sent by a human
                    agent instead of the bot
              required:
                - templateName
                - whatsappNumber
            examples:
              basic:
                summary: Basic Template Send
                value:
                  templateName: welcome_message
                  whatsappNumber: '+27123456789'
              with-parameters:
                summary: With Template Parameters
                value:
                  templateName: order_update
                  whatsappNumber: '+27123456789'
                  bodyParameters:
                    name: '{{first_name}}'
                    order_status: shipped
                  buttonParameters:
                    tracking_url: ABC123
              with-media:
                summary: With Header Media
                value:
                  templateName: promo_image
                  whatsappNumber: '+27123456789'
                  headerMedia: https://example.com/promo-banner.jpg
                  bodyParameters:
                    name: '{{first_name}}'
                    discount: 20%
              auto-create:
                summary: Auto-Create Contact
                value:
                  templateName: welcome_message
                  whatsappNumber: '+27123456789'
                  bodyParameters:
                    name: John Doe
      responses:
        '200':
          description: Template message sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  summary:
                    type: object
                    properties:
                      total:
                        type: integer
                        example: 1
                      successful:
                        type: integer
                        example: 1
                      failed:
                        type: integer
                        example: 0
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        contactId:
                          type: string
                          format: uuid
                        contactName:
                          type: string
                        success:
                          type: boolean
                        messageId:
                          type: string
                          nullable: true
                        error:
                          type: string
                          nullable: true
                  broadcastId:
                    type: string
                    format: uuid
                    description: Unique identifier for this send operation
              example:
                success: true
                summary:
                  total: 1
                  successful: 1
                  failed: 0
                results:
                  - contactId: 123e4567-e89b-12d3-a456-426614174000
                    contactName: John Doe
                    success: true
                    messageId: wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI...
                    error: null
                broadcastId: broadcast-uuid-here
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              examples:
                missing-template:
                  summary: Missing Template Name
                  value:
                    error: Template name is required
                missing-number:
                  summary: Missing Phone Number
                  value:
                    error: whatsappNumber is required
                    example:
                      templateName: your_template
                      whatsappNumber: +27 79 123 4567
                      bodyParameters:
                        name: Sam
                contact-not-found:
                  summary: Contact Not Found
                  value:
                    error: Contact not found
                    message: >-
                      No contact found with number +27123456789. Provide
                      bodyParameters.name to auto-create.
                credentials-missing:
                  summary: WhatsApp Credentials Not Configured
                  value:
                    error: Meta WhatsApp credentials not configured
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Invalid API key
                message: API key has been revoked
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
              example:
                error: Organization not found for API key
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: Internal server error
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token for authentication. Format: `Bearer fiq_YOUR_API_KEY`'
      bearerFormat: JWT

````