This guide explains how to send free form WhatsApp messages for testing, API integration, and triggering agent or flow responses.
Free form messages are regular WhatsApp messages (text, images, etc.) that you can send without using templates - but only within the 24-hour customer service window.

​
Understanding the 24-hour window

WhatsApp allows free form messages only when:
  • A customer has messaged you in the last 24 hours
  • The 24-hour window is still active
After 24 hours, you must use approved templates to re-engage customers.

​
Method 1: Send a test message (health check)

Perfect for verifying your WhatsApp configuration is working:
  1. Go to WhatsApp → Configurations
  2. Click on your WhatsApp configuration
  3. Click Run Health Check
  4. In the health check modal, find the Test Message section
  5. Enter a phone number that has messaged you recently
  6. Click Send Test Message
The health check will:
  • Verify your configuration is working
  • Send a test message to confirm delivery
  • Show any errors if the 24-hour window has expired

​
Method 2: Send via API

Use the API to send messages programmatically:

​
Send a text message

POST /api/v1/whatsapp_conversations/{conversation_id}/whatsapp_messages
Request body: 
{
  "message": {
    "content": "Hello! This is a test message from the API."
  }
}

​
Send an image message

{
  "message": {
    "message_type": "image",
    "media_url": "https://example.com/image.jpg",
    "content": "Check out this image!"
  }
}

​
Example using cURL

curl -X POST https://app.kapso.ai/api/v1/whatsapp_conversations/123e4567/whatsapp_messages \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": "Hello from the API!"
    }
  }'
The conversation_id must be in the URL path. Messages can only be sent if there’s an active 24-hour window.

​
Method 3: Trigger agent or flow responses

Send messages that trigger automated responses:

​
Triggering an agent

  1. Ensure your agent is connected to a WhatsApp configuration
  2. Send any message to the WhatsApp number
  3. The agent will:
    • Receive the message
    • Process it according to its configuration
    • Send an automated response

​
Triggering a flow

  1. Set up a flow with an Inbound Message Trigger
  2. Configure trigger conditions (keywords, patterns, or all messages)
  3. Send a message matching your trigger
  4. The flow will:
    • Capture the message
    • Execute the flow steps
    • Send responses as configured
Test your triggers using the sandbox first to ensure they work as expected before using production numbers.

​
Supported message types

You can send various message types through the API:

Text

Simple text messages up to 4096 characters

Image

JPEG, PNG images with optional captions

Video

MP4, 3GPP videos up to 16MB

Audio

Audio files in various formats

Document

PDFs and other documents with filenames

Location

Geographic coordinates with names

​
When messages fail

Common reasons for message failure:

​
Outside 24-hour window

Error: “Re-engagement message” or error code 131047 Solution: Use an approved template message instead

​
Invalid phone number

Error: “Invalid WhatsApp number” Solution: Ensure the number is registered on WhatsApp

​
No active conversation

Error: “Conversation not found” Solution: Customer must message you first to start a conversation

​
Next steps

Use templates for re-engagement

Learn how to message customers after 24 hours

Set up webhooks

Receive notifications when customers respond