Send WhatsApp Template

curl --request POST \
  --url https://api.minimo.it/public/v1/templates/whatsapp/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipient": "393471234567",
  "type": "template",
  "template": {
    "id": "3NQCOSX",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "ORD-12345"
          }
        ]
      }
    ]
  }
}
'

{
  "data": {
    "success": true
  }
}

{
  "error": "Missing recipient phone number"
}

{
  "error": "Failed to send the message"
}

POST

public

templates

send

curl --request POST \
  --url https://api.minimo.it/public/v1/templates/whatsapp/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "recipient": "393471234567",
  "type": "template",
  "template": {
    "id": "3NQCOSX",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          },
          {
            "type": "text",
            "text": "ORD-12345"
          }
        ]
      }
    ]
  }
}
'

{
  "data": {
    "success": true
  }
}

{
  "error": "Missing recipient phone number"
}

{
  "error": "Failed to send the message"
}

Overview

Send WhatsApp messages to your contacts using pre-approved templates. Perfect for:

Transactional notifications: Order updates, booking confirmations
Customer support: Appointment reminders, service updates
Marketing messages: Product launches, promotional offers (with opt-in)
Authentication: OTP codes, verification messages

Before sending messages, make sure to connect a WhatsApp Business Account by visiting the Channels section at app.minimo.it/channels.

WhatsApp Template Requirements

Unlike emails, WhatsApp messages must use templates approved by Meta (Facebook). This ensures:

User privacy and experience
Compliance with WhatsApp Business Policy
Reduced spam and unwanted messages

Template Approval Process

Create template in Minimo dashboard
Submit for approval to Meta
Wait 24-48 hours for review
Use approved template via API

Only templates with status: "APPROVED" can be used. Attempting to send with pending or rejected templates will fail.

Template Categories

WhatsApp templates must be categorized:

Category	Description	Use Cases	24h Window
`UTILITY`	Account updates, transactions	Order status, booking confirmation	No
`AUTHENTICATION`	OTP codes, verification	2FA codes, login verification	No
`MARKETING`	Promotional content	Product launch, special offers	Yes*

*Marketing templates require user opt-in and are subject to the 24-hour messaging window.

Phone Number Format

WhatsApp requires phone numbers in E.164 format:

+[country code][subscriber number]

Examples:

✅ +393391234567 (Italy)
✅ +12025551234 (US)
✅ +447700900123 (UK)
❌ 3391234567 (missing country code)
❌ +39 339 123 4567 (contains spaces)
❌ +39-339-123-4567 (contains dashes)

Always validate and format phone numbers before sending. Invalid numbers will result in failed messages and count against your quality score.

Choosing the Template: `id` or `name`

Address the template in one of two ways — exactly one, never both:

template.id (recommended) — the template’s stable Minimo id, e.g. 3NQCOSX. Find it in the app on the template card or in the templates table, or in the templateId field of List WhatsApp Templates.
template.name — the template name as approved by Meta, e.g. order_confirmation. Still accepted, but deprecated for templates created in Minimo: send those by id. For templates created on the Meta or 360dialog console the name is the only option (see the note below).

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "id": "3NQCOSX",
    "components": [{ "type": "BODY", "parameters": [{ "type": "text", "text": "Jane" }] }]
  }
}

Why prefer the id. The id identifies the template in Minimo rather than its Meta name, and always sends the version currently in use. A name of a template created in Minimo resolves the same way only while that name still exists in Minimo: once its version is deleted, the name no longer resolves and Meta rejects the send. An id already names one language — each language of a template has its own id. You can omit languageCode when you send by id; if you pass it, it must match the template’s language.

Only templates created in Minimo have an id. Templates created directly on the Meta or 360dialog console show templateId: null in the list: send those by name.

Choosing the Sender (Multi-Number)

A company can connect more than one WhatsApp number (multi-sender / multi-WABA) — e.g. a support line and a marketing line. Control which number a message is sent from with the optional sender field:

Omit sender → the message is sent from the company preferred number.
Set sender → the message is sent from that number. Pass either the phone number (any formatting, e.g. +39 351 1234567) or the Meta phone_number_id.

{
  "recipient": "393391234567",
  "type": "template",
  "sender": "+393517654321",
  "template": {
    "name": "product_launch",
    "components": [
      { "type": "BODY", "parameters": [ { "type": "text", "text": "Jane" } ] }
    ]
  }
}

An unknown or foreign sender returns WHATSAPP_SENDER_NOT_FOUND. Always source valid values from List WhatsApp Senders.

When the recipient isn’t a contact yet, this send creates one (marked “created via API”). Use the optional contactSource field to label where it came from (defaults to WhatsApp); existing contacts are never modified.

Template Variables

Templates support dynamic content through placeholders. Meta allows two placeholder styles, and the style is fixed when the template is created:

Positional: numbered placeholders like {{1}}, {{2}}
Named: descriptive placeholders like {{customer_name}}, {{order_id}}

Positional Variables

Template Example (created in dashboard):

Hello {{1}}, your order {{2}} has been confirmed!

Total: {{3}}
Estimated delivery: {{4}}

Track your order: {{5}}

API Request:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          { "type": "text", "text": "Jane Doe" },
          { "type": "text", "text": "ORD-12345" },
          { "type": "text", "text": "$99.99" },
          { "type": "text", "text": "November 20, 2025" },
          { "type": "text", "text": "https://track.example.com/12345" }
        ]
      }
    ]
  }
}

Variable numbering starts at {{1}}, not {{0}}. Order matters - map parameters in the exact sequence defined in your template.

Set type to "template" to send an approved template, or "text" (with a top-level text field) for a free-form session message. Component type values for filling placeholders are uppercase HEADER, BODY, FOOTER. A dynamic URL button uses the lowercase button component (with sub_type: "url" and a 0-based index) — not BUTTONS (that is only the template-definition block and the provider rejects it on a send with error #100). companyId is resolved from your API key — never send it in the body.

Named Variables

For templates with named placeholders, add parameter_name to each body parameter to state which placeholder the value fills: Template Example (created in dashboard):

Hello {{customer_name}}, your order {{order_id}} has been confirmed!

API Request:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "order_confirmation_named",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          { "type": "text", "text": "Jane Doe", "parameter_name": "customer_name" },
          { "type": "text", "text": "ORD-12345", "parameter_name": "order_id" }
        ]
      }
    ]
  }
}

parameter_name is recommended but optional. If you omit it, Minimo resolves the names automatically from the approved template definition, matching your parameters by position: the first parameter fills the first placeholder appearing in the template body, and so on. When relying on this fallback, the order of your parameters must follow the order in which the placeholders appear in the template.

With explicit parameter_name values, every name must match a placeholder defined in the template — a wrong or missing name is rejected by Meta with (#100) Invalid parameter.

WhatsApp Message Components

Templates can have multiple components:

Header (Optional)

Text, image, document, or video
Single dynamic variable supported

Body (Required)

Main message content
Supports multiple variables
Maximum 1024 characters

Additional info (e.g., “Reply STOP to opt-out”)
No variables allowed

Buttons (Optional)

Call-to-action buttons
Quick reply buttons
URL buttons with dynamic parameters

Use Cases

Order Confirmation

Send instant confirmation when an order is placed:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {"type": "text", "text": "Mario Rossi"},
          {"type": "text", "text": "ORD-789"},
          {"type": "text", "text": "€149.99"}
        ]
      }
    ]
  }
}

Appointment Reminder

Remind customers about upcoming appointments:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "appointment_reminder",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {"type": "text", "text": "Dr. Smith"},
          {"type": "text", "text": "November 15, 2025"},
          {"type": "text", "text": "10:30 AM"},
          {"type": "text", "text": "Via Roma 123, Milano"}
        ]
      }
    ]
  }
}

OTP Verification

Send one-time passwords securely:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "otp_code",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {"type": "text", "text": "847592"},
          {"type": "text", "text": "5 minutes"}
        ]
      }
    ]
  }
}

Shipping Update

Notify customers about delivery status:

{
  "recipient": "393391234567",
  "type": "template",
  "template": {
    "name": "shipping_update",
    "components": [
      {
        "type": "BODY",
        "parameters": [
          {"type": "text", "text": "ORD-12345"},
          {"type": "text", "text": "Out for delivery"},
          {"type": "text", "text": "https://track.example.com/12345"}
        ]
      }
    ]
  }
}

Best Practices

Message Quality Score

WhatsApp monitors your message quality. Maintain a high quality score by:

✅ Only sending to users who opted in
✅ Sending relevant, timely messages
✅ Using clear, professional language
✅ Respecting the 24-hour window for marketing
❌ Avoid spam-like behavior
❌ Don’t send unsolicited messages
❌ Don’t exceed rate limits

Poor quality scores can result in: - Reduced sending limits - Template rejections - Account suspension

Phone Number Validation

Always validate before sending:

function isValidE164(phone) {
  // Basic E.164 validation
  return /^\+[1-9]\d{1,14}$/.test(phone);
}

if (!isValidE164(phone)) {
  console.error('Invalid phone number format');
  return;
}

Template Design Guidelines

Be concise: Keep messages short and clear
Add context: Include order numbers, dates, etc.
Include branding: Mention your company name
Provide value: Every message should be useful
Call-to-action: Make next steps obvious

Rate Limits & Messaging Tiers

WhatsApp enforces tiered messaging limits:

Tier	Daily Limit	How to Advance
Tier 1	1,000	Maintain quality score
Tier 2	10,000	Consistent quality + volume
Tier 3	100,000	High quality + high volume
Tier 4	Unlimited	Enterprise approval

Start at Tier 1, advance automatically with good performance.

Common Errors

Error	Cause	Solution
`template_not_approved`	Template pending/rejected	Check status in dashboard, resubmit if needed
`invalid_phone_number`	Phone not in E.164 format	Add country code, remove spaces/dashes
`template_not_found`	Wrong template name	Verify template name in dashboard
`400` — both or neither of `template.id` and `template.name`	The template must be addressed exactly once	Send one of the two
`400 INVALID_ID_FORMAT`	`template.id` is not a valid id	Copy the id from the app or from `templateId` in the list
`400 INVALID_PARAMETERS` with an id	`languageCode` disagrees with the id’s language	Omit `languageCode`, or use the id of the other language
`404 TEMPLATE_NOT_FOUND`	No template with that id in your account	Check the id; templates created outside Minimo have none — send them by `name`
`409 TEMPLATE_VERSION_NOT_PUBLISHED`	The template has no approved version yet	Wait for Meta’s approval, then retry
`parameter_mismatch`	Wrong number of variables	Match template variable count exactly
`(#100) Invalid parameter`	Wrong `parameter_name` on a named template	Use the exact placeholder names defined in the template, or omit `parameter_name` and send parameters in template order
`rate_limit_exceeded`	Messaging tier limit reached	Wait for reset or request tier upgrade
`recipient_not_on_whatsapp`	Phone number not on WhatsApp	Verify number is active on WhatsApp

Tracking & Analytics

Monitor message delivery and engagement:

Delivery status: Sent, delivered, read
Failure reasons: Why messages didn’t deliver
Response rate: How many users reply

Access analytics via the Minimo dashboard.

24-Hour Messaging Window

For Marketing Templates

After a user-initiated conversation, you have a 24-hour window to send marketing messages without requiring a new opt-in. User-initiated means:

User sends a message to your WhatsApp number
User clicks a WhatsApp link
User interacts with your WhatsApp ad

Outside the 24-hour window: Only UTILITY and AUTHENTICATION templates can be sent.

UTILITY templates (order confirmations, booking updates) can be sent anytime, regardless of the 24-hour window.

Compliance & Opt-In

Get explicit opt-in before sending WhatsApp messages
Keep records of consent
Honor opt-out requests immediately
Follow GDPR and local privacy regulations

Opt-Out Handling

Include opt-out instructions in templates:

Don't want to receive these messages? Reply STOP to opt out.

List WhatsApp Senders - Connected numbers you can send sender from
List WhatsApp Templates - View all available templates
Inbound & Webhooks - How replies and template-status updates arrive

Authorizations

Authorization

string

header

required

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

Body

application/json

recipient

string

required

Phone number of the recipient including country code

Example:

"393471234567"

type

enum<string>

required

Type of message to send

Available options:

text,

template

Example:

"template"

text

string

Plain text message (used only if type is 'text')

Example:

"Hello, this is a plain text message."

template

object

Address the template with exactly one of id or name — both, or neither, is rejected with 400. id is accepted only by POST /public/v1/templates/whatsapp/send; the legacy endpoint requires name.

Show child attributes

sender

string

Multi-sender: the connected WhatsApp number to send from, when the company has more than one. Accepts the phone number (E.164 or any formatting, e.g. +39 351 1234567) or the Meta phone_number_id. Omit to use the company preferred number. An unknown/foreign number returns WHATSAPP_SENDER_NOT_FOUND. List valid values via GET /public/v1/templates/whatsapp/senders.

Example:

"+393511234567"

contactSource

string

Contact source recorded when the recipient does not exist yet and is created as a Minimo contact by this send (defaults to WhatsApp). Does not modify existing contacts. The contact source type is always system-defined and cannot be set by the caller.

Maximum string length: 64

Example:

"WhatsApp"

Response

Message sent successfully

data

object

Show child attributes

Overview

Core Data

Messaging Channels

Connect a Bot (WhatsApp)

Legacy (Deprecated)

Send WhatsApp Template

Overview

WhatsApp Template Requirements

Template Approval Process

Template Categories

Phone Number Format

Choosing the Template: `id` or `name`

Choosing the Sender (Multi-Number)

Template Variables

Positional Variables

Named Variables

WhatsApp Message Components

Header (Optional)

Body (Required)

Footer (Optional)

Buttons (Optional)

Use Cases

Best Practices

Message Quality Score

Phone Number Validation

Template Design Guidelines

Rate Limits & Messaging Tiers

Common Errors

Tracking & Analytics

24-Hour Messaging Window

For Marketing Templates

Compliance & Opt-In

Opt-Out Handling

Authorizations

Body

Response

​Overview

​WhatsApp Template Requirements

​Template Approval Process

​Template Categories

​Phone Number Format

​Choosing the Template: id or name

​Choosing the Sender (Multi-Number)

​Template Variables

​Positional Variables

​Named Variables

​WhatsApp Message Components

​Header (Optional)

​Body (Required)

​Footer (Optional)

​Buttons (Optional)

​Use Cases

​Best Practices

​Message Quality Score

​Phone Number Validation

​Template Design Guidelines

​Rate Limits & Messaging Tiers

​Common Errors

​Tracking & Analytics

​24-Hour Messaging Window

​For Marketing Templates

​Compliance & Opt-In

​User Consent Required

​Opt-Out Handling

​Related Endpoints

Authorizations

Body

Response

Overview

WhatsApp Template Requirements

Template Approval Process

Template Categories

Phone Number Format

Choosing the Template: `id` or `name`

Choosing the Sender (Multi-Number)

Template Variables

Positional Variables

Named Variables

WhatsApp Message Components

Header (Optional)

Body (Required)

Footer (Optional)

Buttons (Optional)

Use Cases

Best Practices

Message Quality Score

Phone Number Validation

Template Design Guidelines

Rate Limits & Messaging Tiers

Common Errors

Tracking & Analytics

24-Hour Messaging Window

For Marketing Templates

Compliance & Opt-In

User Consent Required

Opt-Out Handling

Related Endpoints