Send WhatsApp Message - FlowIQ API Documentation

This endpoint sends WhatsApp messages through Meta’s WhatsApp Business API. The organization must have Meta WhatsApp configured and the contact must already exist.

Overview

Send various types of WhatsApp messages to existing contacts in your FlowIQ organization. The API supports:

Text messages
Media messages (image, video, audio, document)
Location sharing
Contact cards
Interactive messages (buttons, lists)
Reactions to existing messages

Authentication

All requests require a Bearer token with API key format (fiq_...) in the Authorization header:

Authorization: Bearer fiq_YOUR_API_KEY

Only API keys with the fiq_ prefix are accepted. The API key must belong to the organization specified in tenantId.

Requirements

Prerequisites

Meta WhatsApp Provider: Organization must have whatsapp_provider_choice set to meta 2. Configured Credentials: meta_phone_id and whatsapp_bearer_token must be set 3. Existing Contact: The recipient must already exist in your contacts database

Basic Usage

Send a Text Message

curl -X POST "https://api.flowiq.live/send-whatsapp?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+27123456789",
    "message_type": "text",
    "text": "Hello! This is a test message from FlowIQ API."
  }'

Send an Image with Caption

curl -X POST "https://api.flowiq.live/send-whatsapp?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+27123456789",
    "message_type": "image",
    "media_url": "https://example.com/image.jpg",
    "caption": "Check out this image!"
  }'

Reply to a Message

curl -X POST "https://api.flowiq.live/send-whatsapp?tenantId=YOUR_TENANT_ID" \
  -H "Authorization: Bearer fiq_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+27123456789",
    "message_type": "text",
    "text": "This is a reply to your message!",
    "context_message_id": "wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI..."
  }'

Request Parameters

Query Parameters

Parameter	Type	Required	Description
`tenantId`	string	Yes	Your organization’s tenant identifier (slug)

Request Body (Common Fields)

Field	Type	Required	Description
`phone_number`	string	Yes	Recipient phone number with country code
`message_type`	string	Yes	Type of message (see Message Types below)
`context_message_id`	string	No	WhatsApp message ID to reply to

Message Types

Text Message

Field	Type	Required	Description
`text`	string	Yes	The text content of the message

{
  "phone_number": "+27123456789",
  "message_type": "text",
  "text": "Hello, World!"
}

Image Message

Field	Type	Required	Description
`media_url`	string	Yes	URL to the image file
`caption`	string	No	Optional caption for the image

{
  "phone_number": "+27123456789",
  "message_type": "image",
  "media_url": "https://example.com/product.jpg",
  "caption": "Our latest product!"
}

Supported image formats: JPEG, PNG. The image will be automatically uploaded to our storage with a 1-year signed URL.

Video Message

Field	Type	Required	Description
`media_url`	string	Yes	URL to the video file
`caption`	string	No	Optional caption for the video

{
  "phone_number": "+27123456789",
  "message_type": "video",
  "media_url": "https://example.com/demo.mp4",
  "caption": "Watch our demo video"
}

Audio Message

Field	Type	Required	Description
`media_url`	string	Yes	URL to the audio file

{
  "phone_number": "+27123456789",
  "message_type": "audio",
  "media_url": "https://example.com/message.mp3"
}

Audio messages do not support captions.

Document Message

Field	Type	Required	Description
`media_url`	string	Yes	URL to the document file
`filename`	string	No	Display filename for the document
`caption`	string	No	Optional caption for the document

{
  "phone_number": "+27123456789",
  "message_type": "document",
  "media_url": "https://example.com/invoice.pdf",
  "filename": "Invoice_2025.pdf",
  "caption": "Please find your invoice attached"
}

Location Message

Field	Type	Required	Description
`location.latitude`	number	Yes	Latitude coordinate
`location.longitude`	number	Yes	Longitude coordinate
`location.name`	string	No	Location name
`location.address`	string	No	Location address

{
  "phone_number": "+27123456789",
  "message_type": "location",
  "location": {
    "latitude": -33.9249,
    "longitude": 18.4241,
    "name": "Cape Town Office",
    "address": "123 Main Street, Cape Town"
  }
}

Contacts Message

Share one or more contact cards.

Field	Type	Required	Description
`contacts`	array	Yes	Array of contact objects

{
  "phone_number": "+27123456789",
  "message_type": "contacts",
  "contacts": [
    {
      "name": {
        "formatted_name": "John Doe",
        "first_name": "John",
        "last_name": "Doe"
      },
      "phones": [
        {
          "phone": "+27987654321",
          "type": "CELL"
        }
      ]
    }
  ]
}

Interactive Button Message

Send a message with up to 3 quick reply buttons.

Field	Type	Required	Description
`interactive.type`	string	Yes	Must be `"button"`
`interactive.body`	string	Yes	Main message text (max 1024 chars)
`interactive.header`	string	No	Header text (max 60 chars)
`interactive.footer`	string	No	Footer text (max 60 chars)
`interactive.buttons`	array	Yes	Array of button objects (max 3)
`interactive.header_media`	object	No	Media header (image/video/document)

Basic Button Example

{
  "phone_number": "+27123456789",
  "message_type": "interactive",
  "interactive": {
    "type": "button",
    "header": "Order Confirmation",
    "body": "Would you like to confirm your order #12345?",
    "footer": "Reply within 24 hours",
    "buttons": [
      { "id": "confirm", "title": "Confirm" },
      { "id": "cancel", "title": "Cancel" },
      { "id": "modify", "title": "Modify Order" }
    ]
  }
}

Button with Image Header

{
  "phone_number": "+27123456789",
  "message_type": "interactive",
  "interactive": {
    "type": "button",
    "body": "Check out our new product!",
    "header_media": {
      "type": "image",
      "url": "https://example.com/product.jpg"
    },
    "buttons": [
      { "id": "buy", "title": "Buy Now" },
      { "id": "info", "title": "More Info" }
    ]
  }
}

Button titles are limited to 20 characters. You can have a maximum of 3 buttons.

Interactive List Message

Send a message with a list menu containing multiple sections and rows.

Field	Type	Required	Description
`interactive.type`	string	Yes	Must be `"list"`
`interactive.body`	string	Yes	Main message text (max 1024 chars)
`interactive.button`	string	Yes	Menu button text (max 20 chars)
`interactive.header`	string	No	Header text (max 60 chars)
`interactive.footer`	string	No	Footer text (max 60 chars)
`interactive.sections`	array	Yes	Array of section objects (max 10)

{
  "phone_number": "+27123456789",
  "message_type": "interactive",
  "interactive": {
    "type": "list",
    "header": "Our Menu",
    "body": "Please select from our available options:",
    "footer": "Tap the button below to view options",
    "button": "View Menu",
    "sections": [
      {
        "title": "Main Dishes",
        "rows": [
          {
            "id": "burger",
            "title": "Burger",
            "description": "Beef patty with cheese"
          },
          {
            "id": "pizza",
            "title": "Pizza",
            "description": "Margherita or Pepperoni"
          }
        ]
      },
      {
        "title": "Drinks",
        "rows": [
          { "id": "cola", "title": "Cola", "description": "500ml bottle" },
          {
            "id": "water",
            "title": "Water",
            "description": "Still or sparkling"
          }
        ]
      }
    ]
  }
}

List messages support up to 10 sections with up to 10 rows each. Row titles are limited to 24 characters and descriptions to 72 characters.

Reaction Message

React to an existing message with an emoji.

Field	Type	Required	Description
`reaction.message_id`	string	Yes	WhatsApp message ID to react to
`reaction.emoji`	string	No	Emoji to react with (default: 👍)

{
  "phone_number": "+27123456789",
  "message_type": "reaction",
  "reaction": {
    "message_id": "wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI...",
    "emoji": "❤️"
  }
}

Response Examples

Success Response (200)

{
  "success": true,
  "message": "Message sent successfully",
  "data": {
    "message_id": "wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI...",
    "recipient": "27123456789",
    "message_type": "text",
    "organization": "Your Organization Name",
    "meta_response": {
      "messaging_product": "whatsapp",
      "contacts": [{ "input": "27123456789", "wa_id": "27123456789" }],
      "messages": [{ "id": "wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI..." }]
    }
  }
}

Error: Contact Not Found (404)

{
  "error": "Contact not found",
  "message": "No contact exists with WhatsApp number 27123456789. Please create the contact first using the /api/contact endpoint.",
  "whatsapp_id": "27123456789"
}

Error: Invalid Provider (400)

{
  "error": "Invalid provider",
  "message": "Organization must use Meta WhatsApp provider. Current: wati"
}

Error: Missing Required Field (400)

{
  "error": "Missing required field",
  "message": "text is required for text messages"
}

Error: Invalid API Key (401)

{
  "error": "Invalid API key",
  "message": "API key has been revoked"
}

Error: Meta Upload Failed (500)

{
  "error": "Meta upload failed",
  "message": "Failed to upload media to Meta"
}

Media Handling

Media Upload Flow

When you send media messages, the API automatically: 1. Downloads the media from your provided URL 2. Uploads it to FlowIQ’s storage bucket 3. Generates a 1-year signed URL 4. Uploads to Meta’s servers for delivery 5. Stores the signed URL in the message database

This ensures:

Media is permanently stored for future reference
URLs won’t expire or break
Messages can be viewed in the FlowIQ inbox

Supported media types: - Images: JPEG, PNG - Videos: MP4 - Audio: MP3, AAC, OGG - Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX

Error Codes

Status Code	Error	Description
200	Success	Message sent successfully
400	Bad Request	Missing required fields, invalid message type, or invalid provider
401	Unauthorized	Invalid or expired API key, or tenant mismatch
404	Not Found	Organization or contact not found
500	Internal Server Error	Meta upload failed or server error

Best Practices

Contact Requirement

Always ensure the contact exists before sending messages. Use the /contact endpoint to create contacts first.

Phone Number Format

Include the country code in phone numbers (e.g., +27 for South Africa). The API removes special characters automatically.

Media URLs

Ensure media URLs are publicly accessible. The API needs to download the file before uploading to Meta.

Interactive Messages

Use interactive buttons and lists for better engagement. They provide a better user experience than plain text.

Message Context

Use context_message_id when replying to specific messages. This creates a visual thread in the WhatsApp conversation.

Integration Example

async function sendWhatsAppMessage(tenantId, apiKey, messageData) {
  try {
    const response = await fetch(
      `https://api.flowiq.live/send-whatsapp?tenantId=${tenantId}`,
      {
        method: "POST",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(messageData),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      if (response.status === 404) {
        console.error("Contact not found:", data.message);
        // Handle contact creation first
      } else if (response.status === 400) {
        console.error("Invalid request:", data.message);
      }
      throw new Error(data.message);
    }

    return data;
  } catch (error) {
    console.error("Failed to send message:", error);
    throw error;
  }
}

// Send a text message
const textResult = await sendWhatsAppMessage(
  "your-tenant-id",
  "fiq_your_api_key",
  {
    phone_number: "+27123456789",
    message_type: "text",
    text: "Hello from the FlowIQ API!",
  }
);

// Send an interactive button message
const buttonResult = await sendWhatsAppMessage(
  "your-tenant-id",
  "fiq_your_api_key",
  {
    phone_number: "+27123456789",
    message_type: "interactive",
    interactive: {
      type: "button",
      body: "How would you like to proceed?",
      buttons: [
        { id: "yes", title: "Yes, continue" },
        { id: "no", title: "No, cancel" },
      ],
    },
  }
);

// Send a document with caption
const docResult = await sendWhatsAppMessage(
  "your-tenant-id",
  "fiq_your_api_key",
  {
    phone_number: "+27123456789",
    message_type: "document",
    media_url: "https://example.com/report.pdf",
    filename: "Monthly_Report.pdf",
    caption: "Please review the attached report",
  }
);

Rate Limiting

The WhatsApp Business API has rate limits imposed by Meta. If you exceed these limits, messages may fail to send. Implement exponential backoff and respect 429 responses.

Message Storage

All sent messages are automatically stored in:

helpdesk_messages: Full message details including media URLs
customer_sessions: Message history for the conversation thread

This enables message history viewing in the FlowIQ inbox and conversation tracking.

Authorizations

Authorization

string

header

required

Bearer token for authentication. Format: Bearer YOUR_BEARER_TOKEN

Query Parameters

tenantId

string

required

Organization tenant identifier (slug)

Body

application/json

phone_number

string

required

Recipient phone number with country code

Example:

"+27123456789"

message_type

enum<string>

required

Type of message to send

Available options:

text,

image,

video,

audio,

document,

location,

contacts,

interactive,

reaction

Example:

"text"

text

string

Text content (required for text messages)

Example:

"Hello, World!"

media_url

string

URL to media file (required for image/video/audio/document)

Example:

"https://example.com/image.jpg"

caption

string

Caption for media messages

Example:

"Check this out!"

filename

string

Filename for document messages

Example:

"document.pdf"

location

object

Show child attributes

location.latitude

number

required

Latitude coordinate

Example:

-33.9249

location.longitude

number

required

Longitude coordinate

Example:

18.4241

location.name

string

Location name

Example:

"Cape Town Office"

location.address

string

Location address

Example:

"123 Main Street, Cape Town"

contacts

object[]

Array of contact cards to share

interactive

object

Interactive message configuration

Show child attributes

interactive.type

enum<string>

Type of interactive message

Available options:

button,

list

interactive.body

string

Main message body text (max 1024 chars)

interactive.header

string

Header text (max 60 chars)

interactive.footer

string

Footer text (max 60 chars)

interactive.buttons

object[]

Array of buttons (max 3, for button type)

Show child attributes

interactive.buttons.id

string

Button identifier

interactive.buttons.title

string

Button text (max 20 chars)

interactive.button

string

Menu button text for list type (max 20 chars)

interactive.sections

object[]

Array of sections (max 10, for list type)

Show child attributes

interactive.sections.title

string

Section title (max 24 chars)

interactive.sections.rows

object[]

Show child attributes

interactive.sections.rows.id

string

Row identifier

interactive.sections.rows.title

string

Row title (max 24 chars)

interactive.sections.rows.description

string

Row description (max 72 chars)

interactive.header_media

object

Media header for button messages

Show child attributes

interactive.header_media.type

enum<string>

Available options:

image,

video,

document

interactive.header_media.url

string

interactive.header_media.filename

string

reaction

object

Reaction configuration

Show child attributes

reaction.message_id

string

required

WhatsApp message ID to react to

reaction.emoji

string

default:👍

Emoji to react with

context_message_id

string

WhatsApp message ID to reply to

Example:

"wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI..."

Response

Message sent successfully

success

boolean

required

Whether the message was sent successfully

Example:

true

message

string

required

Success message

Example:

"Message sent successfully"

data

object

required

Show child attributes

data.message_id

string

WhatsApp message ID

Example:

"wamid.HBgLMjc4MTIzNDU2NzgVAgASGBQzRUI..."

data.recipient

string

Recipient phone number

Example:

"27123456789"

data.message_type

string

Type of message sent

Example:

"text"

data.organization

string

Organization name

Example:

"Your Organization"

data.meta_response

object

Raw response from Meta API

Getting Started

Endpoints

​Overview

​Authentication

​Requirements

Prerequisites

​Basic Usage

​Send a Text Message

​Send an Image with Caption

​Reply to a Message

​Request Parameters

​Query Parameters

​Request Body (Common Fields)

​Message Types

​Text Message

​Image Message

​Video Message

​Audio Message

​Document Message

​Location Message

​Contacts Message

​Interactive Button Message

​Basic Button Example

​Button with Image Header

​Interactive List Message

​Reaction Message

​Response Examples

​Success Response (200)

​Error: Contact Not Found (404)

​Error: Invalid Provider (400)

​Error: Missing Required Field (400)

​Error: Invalid API Key (401)

​Error: Meta Upload Failed (500)

​Media Handling

Media Upload Flow

​Error Codes

​Best Practices

Contact Requirement

Phone Number Format

Media URLs

Interactive Messages

Message Context

​Integration Example

​Rate Limiting

​Message Storage

Authorizations

Query Parameters

Body

Response

Overview

Authentication

Requirements

Basic Usage

Send a Text Message

Send an Image with Caption

Reply to a Message

Request Parameters

Query Parameters

Request Body (Common Fields)

Message Types

Text Message

Image Message

Video Message

Audio Message

Document Message

Location Message

Contacts Message

Interactive Button Message

Basic Button Example

Button with Image Header

Interactive List Message

Reaction Message

Response Examples

Success Response (200)

Error: Contact Not Found (404)

Error: Invalid Provider (400)

Error: Missing Required Field (400)

Error: Invalid API Key (401)

Error: Meta Upload Failed (500)

Media Handling

Error Codes

Best Practices

Integration Example

Rate Limiting

Message Storage