curl -X POST "https://app.famulor.de/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."
}'
const response = await fetch(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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.'
})
}
);
const data = await response.json();
console.log(data);
import requests
response = requests.post(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'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.'
}
)
print(response.json())
{
"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"
}
}
{
"success": false,
"error": "Insufficient balance. Please top up your account.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"success": false,
"error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
"error_code": "SESSION_EXPIRED",
"session_status": {
"is_open": false,
"can_send_freeform": false,
"requires_template": true,
"message": "Session expired. Send a template or wait for customer to reply.",
"expired_at": "2026-02-23T10:30:00+00:00"
}
}
{
"success": false,
"error": "Sender not found or does not belong to you",
"error_code": "SENDER_NOT_FOUND"
}
{
"success": false,
"error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
"error_code": "INVALID_PHONE"
}
{
"success": false,
"error": "Sender is not online. Current status: Offline",
"error_code": "SENDER_OFFLINE"
}
WhatsApp
Send WhatsApp Freeform Message
Send a free-text WhatsApp message within an active 24-hour session via Famulor
POST
/
user
/
whatsapp
/
send-freeform
curl -X POST "https://app.famulor.de/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."
}'
const response = await fetch(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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.'
})
}
);
const data = await response.json();
console.log(data);
import requests
response = requests.post(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'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.'
}
)
print(response.json())
{
"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"
}
}
{
"success": false,
"error": "Insufficient balance. Please top up your account.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"success": false,
"error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
"error_code": "SESSION_EXPIRED",
"session_status": {
"is_open": false,
"can_send_freeform": false,
"requires_template": true,
"message": "Session expired. Send a template or wait for customer to reply.",
"expired_at": "2026-02-23T10:30:00+00:00"
}
}
{
"success": false,
"error": "Sender not found or does not belong to you",
"error_code": "SENDER_NOT_FOUND"
}
{
"success": false,
"error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
"error_code": "INVALID_PHONE"
}
{
"success": false,
"error": "Sender is not online. Current status: Offline",
"error_code": "SENDER_OFFLINE"
}
Famulor 1.0 API (legacy). This page applies only to Famulor 1.0 (
app.famulor.de) and is retained for legacy compatibility. For the current platform, use the Famulor 2.0 API reference.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
The ID of the WhatsApp sender to send from (obtained from the Get Senders endpoint)
Response Fields
Updated session status after sending the message
Show Session status properties
Show Session status properties
Error Responses
curl -X POST "https://app.famulor.de/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."
}'
const response = await fetch(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
{
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
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.'
})
}
);
const data = await response.json();
console.log(data);
import requests
response = requests.post(
'https://app.famulor.de/api/user/whatsapp/send-freeform',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'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.'
}
)
print(response.json())
{
"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"
}
}
{
"success": false,
"error": "Insufficient balance. Please top up your account.",
"error_code": "INSUFFICIENT_BALANCE"
}
{
"success": false,
"error": "The 24-hour messaging window is closed. Customer must reply first, or use a template message.",
"error_code": "SESSION_EXPIRED",
"session_status": {
"is_open": false,
"can_send_freeform": false,
"requires_template": true,
"message": "Session expired. Send a template or wait for customer to reply.",
"expired_at": "2026-02-23T10:30:00+00:00"
}
}
{
"success": false,
"error": "Sender not found or does not belong to you",
"error_code": "SENDER_NOT_FOUND"
}
{
"success": false,
"error": "Invalid phone number format. Use E.164 format (e.g., +14155551234).",
"error_code": "INVALID_PHONE"
}
{
"success": false,
"error": "Sender is not online. Current status: Offline",
"error_code": "SENDER_OFFLINE"
}
24-Hour Messaging Window
WhatsApp enforces a 24-hour messaging window policy:- When a customer sends a message to your WhatsApp Business number, a 24-hour window opens.
- During this window, you can send freeform messages without restrictions.
- After the window expires, you must use a template message to re-initiate the conversation.
- Each new customer message resets the 24-hour timer.
Notes
- Maximum message length is 4,096 characters (WhatsApp limit).
- The sender must be
online. Offline senders return a503error. - Message costs are automatically deducted from your Famulor account balance.
- Rate limit: 5 requests per second per user.