Skip to main content
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/message

​
Authentication

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_KEY

​
Request Body

​
to
string
required
The recipient’s phone number in international format with country code (e.g., “+15551234567”).
​
type
string
required
The type of message to send. Must be one of: text, image, video, audio, document.
​
api_key
string
required
Your API key for authentication (also required in request body).
​
recipient_type
string
default:"individual"
The type of recipient. Always use “individual” for single recipients.
​
messaging_product
string
default:"whatsapp"
The messaging platform. Always use “whatsapp”.
​
labels
array
Array of strings for message categorization and analytics (e.g., [“support”, “urgent”]).

​
Message Type-Specific Parameters

  • Text Messages
  • Image Messages
  • Video Messages
  • Audio Messages
  • Document Messages
​
text
object
required
Text message configuration

​
Response

The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.
​
success
boolean
Indicates if the request was successfully processed
​
whatsapp_response_info
object
Details from the WhatsApp Business API about the message delivery
​
error
object
Present only when an error occurs
​
code
string
Error code identifier
​
message
string
Human-readable error description

​
Example Requests

  • Text Message
  • Image Message
  • Video Message
  • Audio Message
  • Document Message
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
    },
    "api_key": "YOUR_API_KEY",
    "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 both the header and request body.
{
  "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

1

Public Accessibility

Ensure your media URLs are publicly accessible without authentication headers or login requirements.
2

HTTPS Protocol

All media URLs must use HTTPS protocol. HTTP URLs will be rejected.
3

Direct File Access

URLs should point directly to the file, not to a page that contains the file or requires redirects.
4

Content-Type Headers

Your server should return appropriate Content-Type headers for media files to ensure proper handling.

​
Supported Formats

Media TypeSupported FormatsMax SizeNotes
ImagesJPG, JPEG, PNG5MBAnimated GIFs not supported
VideosMP4, 3GPP16MBH.264 codec recommended
AudioMP3, AAC, AMR, OGG16MBStereo or mono
DocumentsPDF, DOC, DOCX, PPT, PPTX, XLS, XLSX100MBPassword-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
  • Implement IP whitelisting when possible

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.
Use the message ID returned in the response to track status via webhooks or the Message Status API. The initial response only confirms WhatsApp accepted the message, not final delivery.
This API sends messages immediately. For scheduled messaging, implement your own scheduling logic or use our Scheduled Messages API.
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 is available 24/7 to help with API integration, troubleshooting, or any questions about sending messages.