Skip to main content
POST
/
user
/
whatsapp
/
send-freeform
curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send-freeform" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+1234567890",
    "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
  }'

{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "session_status": {
    "is_open": true,
    "can_send_freeform": true,
    "requires_template": false,
    "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
    "minutes_remaining": 1425,
    "expires_at": "2026-02-25T10:30:00+00:00"
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.autocalls.ai/llms.txt

Use this file to discover all available pages before exploring further.

This endpoint sends a freeform (free-text) WhatsApp message to a recipient. Unlike template messages, freeform messages can contain any text but require an active 24-hour messaging window — meaning the recipient must have sent a message to your WhatsApp sender within the last 24 hours.
Freeform messages can only be sent during an active 24-hour messaging window. If the session has expired, you must send a template message first to re-initiate the conversation. Use the Session Status endpoint to check if a session is active.
This endpoint is rate-limited to 5 requests per second per user.

​
Request Body

​
sender_id
integer
required
The ID of the WhatsApp sender to send from (obtained from the Get Senders endpoint)
​
recipient_phone
string
required
The recipient’s phone number in international format (e.g., +1234567890)
​
message
string
required
The message content to send (max 4096 characters)

​
Response Fields

​
success
boolean
Whether the message was sent successfully
​
conversation_id
integer
The ID of the conversation associated with this message
​
message_id
integer
The ID of the conversation message record
​
whatsapp_message_id
integer
The ID of the WhatsApp message record
​
message_sid
string
The Twilio message SID for tracking delivery
​
session_status
object
Updated session status after sending the message

​
Error Responses

​
402 Insufficient Balance
​
403 Session Expired
​
404 Not Found
​
503 Sender Offline
curl -X POST "https://app.autocalls.ai/api/user/whatsapp/send-freeform" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender_id": 12,
    "recipient_phone": "+1234567890",
    "message": "Thank you for your inquiry! Our team will review your request and get back to you within 2 hours."
  }'

{
  "success": true,
  "conversation_id": 1234,
  "message_id": 567,
  "whatsapp_message_id": 890,
  "message_sid": "SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "session_status": {
    "is_open": true,
    "can_send_freeform": true,
    "requires_template": false,
    "message": "Session open (23 hr 45 min remaining). Unlimited free-form messages allowed.",
    "minutes_remaining": 1425,
    "expires_at": "2026-02-25T10:30:00+00:00"
  }
}

​
24-Hour Messaging Window

WhatsApp enforces a 24-hour messaging window policy:
  1. When a customer sends a message to your WhatsApp Business number, a 24-hour window opens.
  2. During this window, you can send freeform messages without restrictions.
  3. After the window expires, you must use a template message to re-initiate the conversation.
  4. Each new customer message resets the 24-hour timer.
Use the Session Status endpoint to check whether a session is active before attempting to send a freeform message.

​
Notes

  • Maximum message length is 4,096 characters (WhatsApp limit).
  • The sender must be online. Offline senders return a 503 error.
  • Message costs are automatically deducted from your account balance.
  • Rate limit: 5 requests per second per user.