Non-Template Message
Reference for the retired legacy send endpoint. Send text and media messages with API v1 instead.
Send instant WhatsApp messages directly to your customers without requiring pre-approved templates. Perfect for quick responses, customer support, and media sharing during ongoing conversations.
The Send Non-Template Message API enables you to send immediate WhatsApp messages including text, images, videos, audio, and documents. This is ideal for customer support scenarios and ongoing conversations where template approval is not required.
Overview
The Send Non-Template Message API enables you to:
- Send instant text messages with URL previews
- Share images, videos, and documents with captions
- Send audio files and voice messages
- Organize messages with custom labels for analytics
- Respond quickly in customer support scenarios
- Continue conversations without template restrictions
Send Non-Template Message
Send various types of WhatsApp messages directly to a specific phone number without requiring pre-approved templates.
Endpoint
POST https://api.insightssystem.com/api:U9ztporN/send/messageAuthentication
All API requests require authentication using your API key. Never share your API keys in client-side code or public repositories.
Include your API key in all requests using Bearer authentication:
Authorization: Bearer YOUR_API_KEYRequest Body
The recipient's phone number in international format with country code (e.g., "+15551234567").
The type of message to send. Must be one of: text, image, video, audio, document.
The type of recipient. Always use "individual" for single recipients.
The messaging platform. Always use "whatsapp".
Array of strings for message categorization and analytics (e.g., ["support", "urgent"]).
WhatsApp's own tracking field, up to 512 characters. On a text message, if you set it, we send it to WhatsApp exactly as you wrote it. On an image, video, audio or document message we build the message from your link and always set our own value, so yours is not sent. If you leave it out, we set it ourselves. WhatsApp sometimes answers a send with a temporary error and still delivers the message minutes later. Our value lets the inbox recognize that late delivery and show the message as delivered instead of failed. If you set your own value on a text message, we can't make that correction for that message.
Message Type-Specific Parameters
Text message configuration
Show Text Properties
The text content of the message (max 4096 characters)
Whether to show URL previews for links in the message
Response
The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.
Indicates if the request was successfully processed
Details from the WhatsApp Business API about the message delivery
Show WhatsApp Response Fields
Always "whatsapp" for WhatsApp messages
Information about the message recipient
The phone number that was provided in the request
WhatsApp's unique identifier for the recipient
Details about the sent message
Unique message identifier (wamid) for tracking status
Initial status of the message (typically "accepted")
Present only when an error occurs
Error code identifier
Human-readable error description
Example Requests
curl -X POST \
https://api.insightssystem.com/api:U9ztporN/send/message \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-d '{
"to": "+15551234567",
"type": "text",
"text": {
"body": "Hello! Thank you for contacting our support team. How can we help you today?",
"preview_url": true
},
"recipient_type": "individual",
"messaging_product": "whatsapp",
"labels": ["support", "greeting"]
}'Example Response
{
"success": true,
"whatsapp_response_info": {
"messaging_product": "whatsapp",
"contacts": [
{
"input": "+15551234567",
"wa_id": "15551234567"
}
],
"messages": [
{
"id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgAERgINQTlEOEJDNzM5QzQwAA==",
"message_status": "accepted"
}
]
}
}Response Codes
Your request was successful and the message has been accepted for delivery.
The request was invalid. Check the error message for details about missing or invalid parameters.
{
"success": false,
"error": {
"code": "missing_required_field",
"message": "The 'to' field is required and must be a valid phone number"
}
}Authentication failed. Verify that you're using a valid API key in the Authorization header.
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Invalid API key provided"
}
}Your account doesn't have permission to send messages or has reached its usage limit.
The media file or message content exceeds size limits.
{
"success": false,
"error": {
"code": "file_too_large",
"message": "The media file exceeds the maximum allowed size"
}
}The request contains invalid data or the media URL is not accessible.
{
"success": false,
"error": {
"code": "invalid_media_url",
"message": "The provided media URL is not accessible"
}
}You've exceeded the rate limit. Implement exponential backoff and retry logic.
An internal server error occurred. Contact support if the issue persists.
{
"success": false,
"error": {
"code": "server_error",
"message": "An internal server error occurred. Please try again later."
}
}Message Types Guide
Understanding the different message types and their optimal use cases will help you choose the right format for your communication needs.
Text Messages
Best Practices
- Keep messages concise and actionable
- Use URL previews for important links
- Break long messages into multiple shorter ones
- Include clear call-to-action when needed
Use Cases
- Customer support responses
- Order confirmations
- Quick updates and notifications
- FAQ responses
Media Messages
Images
- Formats: JPG, JPEG, PNG
- Max Size: 5MB
- Optimal: 1080x1080px or 16:9 ratio
- Use for: Product photos, screenshots, infographics
Videos
- Formats: MP4, 3GPP
- Max Size: 16MB
- Max Duration: 90 seconds
- Use for: Tutorials, product demos, explanations
Audio
- Formats: MP3, AAC, AMR, OGG
- Max Size: 16MB
- Max Duration: 30 minutes
- Use for: Voice messages, audio instructions
Documents
- Formats: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX
- Max Size: 100MB
- Use for: Manuals, invoices, reports, contracts
Media Requirements
All media URLs must be publicly accessible via HTTPS without requiring authentication. For security-sensitive content, consider using signed URLs with expiration times.
URL Requirements
Public Accessibility
Ensure your media URLs are publicly accessible without authentication headers or login requirements.
HTTPS Protocol
All media URLs must use HTTPS protocol. HTTP URLs will be rejected.
Direct File Access
URLs should point directly to the file, not to a page that contains the file or requires redirects.
Content-Type Headers
Your server should return appropriate Content-Type headers for media files to ensure proper handling.
Supported Formats
| Media Type | Supported Formats | Max Size | Notes |
|---|---|---|---|
| Images | JPG, JPEG, PNG | 5MB | Animated GIFs not supported |
| Videos | MP4, 3GPP | 16MB | H.264 codec recommended |
| Audio | MP3, AAC, AMR, OGG | 16MB | Stereo or mono |
| Documents | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX | 100MB | Password-protected files not supported |
Best Practices
Message Optimization
Keep messages concise and actionable. Use rich media when it adds value. Always include clear next steps or calls-to-action when appropriate.
Error Handling
Implement comprehensive error handling with retries. Store failed messages for later retry. Monitor success rates and investigate patterns in failures.
Media Management
Use CDN for media hosting to ensure fast loading. Implement media validation before sending. Consider file size optimization for better delivery rates.
Analytics & Tracking
Use labels consistently for message categorization. Track message IDs for delivery status monitoring. Implement webhook handling for real-time status updates.
Security Considerations
API Key Security
- Never expose API keys in client-side code
- Use environment variables for key storage
- Rotate keys regularly
Data Privacy
- Avoid sending sensitive data in message content
- Use secure, time-limited URLs for confidential documents
- Implement proper access controls
- Follow GDPR and other privacy regulations
FAQs
Non-template messages can only be sent to users who have initiated a conversation with your WhatsApp Business account within the last 24 hours. For proactive messaging, use the Template Message API.
Common reasons include: media URL not publicly accessible, incorrect file format, file size exceeding limits, or missing Content-Type headers. Ensure your media URLs return proper HTTP responses and correct MIME types.
The initial response only confirms WhatsApp accepted the message, not final delivery. This endpoint offers no delivery status, and outgoing webhooks send only received and sent messages. To track delivery, send through Send a message (API v1), then look up the message id it returns with Read a message (API v1).
This API sends messages immediately. For scheduled messaging, implement your own scheduling logic or use our Schedule a message (API v1).
Messages will fail if sent to phone numbers without active WhatsApp accounts. The API will return an error indicating the recipient is not reachable on WhatsApp.
Consider implementing timezone-aware sending in your application logic. Send messages during business hours in the recipient's local timezone for better engagement rates.
Need help?
Our support team can help with API integration, troubleshooting, or any questions about sending messages.