Send Template

Send a single WhatsApp template message to a contact. Each request sends one approved template to one recipient.

Basic Usage

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"
  }'

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

With Template Parameters

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

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

{
  "bodyParameters": {
    "name": "{{first_name}}",
    "shop": "FlowIQ Store"
  }
}

Positional Parameters

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

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

{{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”.

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

{
  "buttonParameters": {
    "order_id": "ORD-12345"
  }
}

Positional Button Parameters

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

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

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.

Response

Success (200)

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

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

{
  "error": "Template name is required"
}

Error: Missing Phone Number (400)

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

Error: Contact Not Found (400)

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

Integration Example

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}`);

Template Approval

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.

Authorizations

Authorization

string

header

required

Bearer token for authentication. Format: Bearer fiq_YOUR_API_KEY

Body

application/json

templateName

string

required

Name of the approved WhatsApp template

Example:

"welcome_message"

whatsappNumber

string

required

Recipient phone number (automatically normalized)

Example:

"+27123456789"

bodyParameters

object

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

object

Key-value pairs for template button URL variables

Example:

{ "tracking_url": "ABC123" }

headerMedia

string

Publicly accessible URL for template header media (image, video, or document)

Example:

"https://example.com/promo-banner.jpg"

memberId

string<uuid>

Team member UUID — marks the message as sent by a human agent instead of the bot

Response

Template message sent

success

boolean

Example:

true

summary

object

Show child attributes

results

object[]

Show child attributes

broadcastId

string<uuid>

Unique identifier for this send operation

Getting Started

Webhooks

Endpoints

Requirements

Basic Usage

With Template Parameters

With Header Media

Request Body

Template Parameters

Named Parameters

Positional Parameters

Contact Field Substitution

Button URL Parameters

Named Button Parameters

Positional Button Parameters

Header Media Types

Auto-Create Contact

Response

Success (200)

Failed (200)

Error: Missing Template (400)

Error: Missing Phone Number (400)

Error: Contact Not Found (400)

Integration Example

Template Approval

Authorizations

Body

Response

Getting Started

Webhooks

Endpoints

​Basic Usage

​With Template Parameters

​With Header Media

​Request Body

​Template Parameters

​Named Parameters

​Positional Parameters

​Contact Field Substitution

​Button URL Parameters

​Named Button Parameters

​Positional Button Parameters

​Header Media Types

​Auto-Create Contact

​Response

​Success (200)

​Failed (200)

​Error: Missing Template (400)

​Error: Missing Phone Number (400)

​Error: Contact Not Found (400)

​Integration Example

Template Approval

Authorizations

Body

Response

Basic Usage

With Template Parameters

With Header Media

Request Body

Template Parameters

Named Parameters

Positional Parameters

Contact Field Substitution

Button URL Parameters

Named Button Parameters

Positional Button Parameters

Header Media Types

Auto-Create Contact

Response

Success (200)

Failed (200)

Error: Missing Template (400)

Error: Missing Phone Number (400)

Error: Contact Not Found (400)

Integration Example