This guide explains how to send free form WhatsApp messages for testing, API integration, and triggering agent or flow responses.

​

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:

{
  "whatsapp_message": {
    "content": "Hello! This is a test message from the API."
  }
}

​

Send an image message

{
  "whatsapp_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 '{
    "whatsapp_message": {
      "content": "Hello from the API!"
    }
  }'

​

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

​

Supported message types

You can send various message types through the API:

​

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