> ## Documentation Index
> Fetch the complete documentation index at: https://docs.whatsable.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Non-Template Message

> Send direct WhatsApp messages with text, media, and rich content without templates

<Tip>
  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.
</Tip>

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

<Warning>
  All API requests require authentication using your API key. Never share your API keys in client-side code or public repositories.
</Warning>

Include your API key in all requests using Bearer authentication:

<CodeGroup>
  ```bash theme={null}
  Authorization: Bearer YOUR_API_KEY
  ```

  ```javascript theme={null}
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
  ```
</CodeGroup>

### Request Body

<ParamField body="to" type="string" required>
  The recipient's phone number in international format with country code (e.g., "+15551234567").
</ParamField>

<ParamField body="type" type="string" required>
  The type of message to send. Must be one of: `text`, `image`, `video`, `audio`, `document`.
</ParamField>

<ParamField body="recipient_type" type="string" default="individual">
  The type of recipient. Always use "individual" for single recipients.
</ParamField>

<ParamField body="messaging_product" type="string" default="whatsapp">
  The messaging platform. Always use "whatsapp".
</ParamField>

<ParamField body="labels" type="array" optional>
  Array of strings for message categorization and analytics (e.g., \["support", "urgent"]).
</ParamField>

### Message Type-Specific Parameters

<Tabs>
  <Tab title="Text Messages">
    <ParamField body="text" type="object" required>
      Text message configuration

      <Expandable title="Text Properties">
        <ParamField body="body" type="string" required>
          The text content of the message (max 4096 characters)
        </ParamField>

        <ParamField body="preview_url" type="boolean" default="false">
          Whether to show URL previews for links in the message
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Image Messages">
    <ParamField body="image" type="object" required>
      Image message configuration

      <Expandable title="Image Properties">
        <ParamField body="link" type="string" required>
          Public URL to the image file (JPG, JPEG, PNG)
        </ParamField>

        <ParamField body="caption" type="string" optional>
          Text caption for the image (max 1024 characters)
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Video Messages">
    <ParamField body="video" type="object" required>
      Video message configuration

      <Expandable title="Video Properties">
        <ParamField body="link" type="string" required>
          Public URL to the video file (MP4, 3GPP)
        </ParamField>

        <ParamField body="caption" type="string" optional>
          Text caption for the video (max 1024 characters)
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Audio Messages">
    <ParamField body="audio" type="object" required>
      Audio message configuration

      <Expandable title="Audio Properties">
        <ParamField body="link" type="string" required>
          Public URL to the audio file (MP3, AAC, AMR, OGG)
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>

  <Tab title="Document Messages">
    <ParamField body="document" type="object" required>
      Document message configuration

      <Expandable title="Document Properties">
        <ParamField body="link" type="string" required>
          Public URL to the document file
        </ParamField>

        <ParamField body="caption" type="string" optional>
          Text caption for the document (max 1024 characters)
        </ParamField>

        <ParamField body="filename" type="string" optional>
          Custom filename for the document (with extension)
        </ParamField>
      </Expandable>
    </ParamField>
  </Tab>
</Tabs>

### Response

The API returns a detailed response indicating whether the message was accepted for delivery and provides WhatsApp message identifiers for tracking.

<ResponseField name="success" type="boolean">
  Indicates if the request was successfully processed
</ResponseField>

<ResponseField name="whatsapp_response_info" type="object">
  Details from the WhatsApp Business API about the message delivery

  <Expandable title="WhatsApp Response Fields">
    <ResponseField name="messaging_product" type="string">
      Always "whatsapp" for WhatsApp messages
    </ResponseField>

    <ResponseField name="contacts" type="array">
      Information about the message recipient

      <ResponseField name="input" type="string">
        The phone number that was provided in the request
      </ResponseField>

      <ResponseField name="wa_id" type="string">
        WhatsApp's unique identifier for the recipient
      </ResponseField>
    </ResponseField>

    <ResponseField name="messages" type="array">
      Details about the sent message

      <ResponseField name="id" type="string">
        Unique message identifier (wamid) for tracking status
      </ResponseField>

      <ResponseField name="message_status" type="string">
        Initial status of the message (typically "accepted")
      </ResponseField>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="error" type="object" optional>
  Present only when an error occurs

  <ResponseField name="code" type="string">
    Error code identifier
  </ResponseField>

  <ResponseField name="message" type="string">
    Human-readable error description
  </ResponseField>
</ResponseField>

### Example Requests

<Tabs>
  <Tab title="Text Message">
    <CodeGroup>
      ```bash cURL theme={null}
      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"]
        }'
      ```

      ```javascript Node.js theme={null}
      const apiKey = 'YOUR_API_KEY';

      async function sendTextMessage() {
        try {
          const response = await fetch('https://api.insightssystem.com/api:U9ztporN/send/message', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify({
              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']
            })
          });
          
          const result = await response.json();
          console.log(result);
          return result;
        } catch (error) {
          console.error('Error sending message:', error);
        }
      }

      sendTextMessage();
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.insightssystem.com/api:U9ztporN/send/message"
      api_key = "YOUR_API_KEY"

      payload = {
          "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"]
      }

      headers = {
          "Content-Type": "application/json",
          "Authorization": f"Bearer {api_key}"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Image Message">
    <CodeGroup>
      ```bash cURL theme={null}
      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": "image",
          "image": {
            "link": "https://storage.googleapis.com/your-bucket/product-demo.jpg",
            "caption": "Here'\''s a visual guide to help you get started with our product!"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "tutorial"]
        }'
      ```

      ```javascript Node.js theme={null}
      const apiKey = 'YOUR_API_KEY';

      async function sendImageMessage() {
        try {
          const response = await fetch('https://api.insightssystem.com/api:U9ztporN/send/message', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify({
              to: '+15551234567',
              type: 'image',
              image: {
                link: 'https://storage.googleapis.com/your-bucket/product-demo.jpg',
                caption: 'Here\'s a visual guide to help you get started with our product!'
              },
              recipient_type: 'individual',
              messaging_product: 'whatsapp',
              labels: ['support', 'tutorial']
            })
          });

          const result = await response.json();
          console.log(result);
          return result;
        } catch (error) {
          console.error('Error sending image:', error);
        }
      }

      sendImageMessage();
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Video Message">
    <CodeGroup>
      ```bash cURL theme={null}
      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": "video",
          "video": {
            "link": "https://storage.googleapis.com/your-bucket/tutorial-video.mp4",
            "caption": "Watch this step-by-step tutorial to get started quickly!"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "tutorial"]
        }'
      ```

      ```javascript Node.js theme={null}
      const apiKey = 'YOUR_API_KEY';

      async function sendVideoMessage() {
        try {
          const response = await fetch('https://api.insightssystem.com/api:U9ztporN/send/message', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify({
              to: '+15551234567',
              type: 'video',
              video: {
                link: 'https://storage.googleapis.com/your-bucket/tutorial-video.mp4',
                caption: 'Watch this step-by-step tutorial to get started quickly!'
              },
              recipient_type: 'individual',
              messaging_product: 'whatsapp',
              labels: ['support', 'tutorial']
            })
          });

          const result = await response.json();
          console.log(result);
          return result;
        } catch (error) {
          console.error('Error sending video:', error);
        }
      }

      sendVideoMessage();
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.insightssystem.com/api:U9ztporN/send/message"
      api_key = "YOUR_API_KEY"

      payload = {
          "to": "+15551234567",
          "type": "video",
          "video": {
              "link": "https://storage.googleapis.com/your-bucket/tutorial-video.mp4",
              "caption": "Watch this step-by-step tutorial to get started quickly!"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "tutorial"]
      }

      headers = {
          "Content-Type": "application/json",
          "Authorization": f"Bearer {api_key}"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Audio Message">
    <CodeGroup>
      ```bash cURL theme={null}
      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": "audio",
          "audio": {
            "link": "https://storage.googleapis.com/your-bucket/voice-instructions.mp3"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "voice-note"]
        }'
      ```

      ```javascript Node.js theme={null}
      const apiKey = 'YOUR_API_KEY';

      async function sendAudioMessage() {
        try {
          const response = await fetch('https://api.insightssystem.com/api:U9ztporN/send/message', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify({
              to: '+15551234567',
              type: 'audio',
              audio: {
                link: 'https://storage.googleapis.com/your-bucket/voice-instructions.mp3'
              },
              recipient_type: 'individual',
              messaging_product: 'whatsapp',
              labels: ['support', 'voice-note']
            })
          });
          
          const result = await response.json();
          console.log(result);
          return result;
        } catch (error) {
          console.error('Error sending audio:', error);
        }
      }

      sendAudioMessage();
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.insightssystem.com/api:U9ztporN/send/message"
      api_key = "YOUR_API_KEY"

      payload = {
          "to": "+15551234567",
          "type": "audio",
          "audio": {
              "link": "https://storage.googleapis.com/your-bucket/voice-instructions.mp3"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "voice-note"]
      }

      headers = {
          "Content-Type": "application/json",
          "Authorization": f"Bearer {api_key}"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Document Message">
    <CodeGroup>
      ```bash cURL theme={null}
      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": "document",
          "document": {
            "link": "https://storage.googleapis.com/your-bucket/user-manual.pdf",
            "caption": "Here is the complete user manual you requested.",
            "filename": "Product_User_Manual_v2.1.pdf"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "documentation"]
        }'
      ```

      ```javascript Node.js theme={null}
      const apiKey = 'YOUR_API_KEY';

      async function sendDocumentMessage() {
        try {
          const response = await fetch('https://api.insightssystem.com/api:U9ztporN/send/message', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': `Bearer ${apiKey}`
            },
            body: JSON.stringify({
              to: '+15551234567',
              type: 'document',
              document: {
                link: 'https://storage.googleapis.com/your-bucket/user-manual.pdf',
                caption: 'Here is the complete user manual you requested.',
                filename: 'Product_User_Manual_v2.1.pdf'
              },
              recipient_type: 'individual',
              messaging_product: 'whatsapp',
              labels: ['support', 'documentation']
            })
          });
          
          const result = await response.json();
          console.log(result);
          return result;
        } catch (error) {
          console.error('Error sending document:', error);
        }
      }

      sendDocumentMessage();
      ```

      ```python Python theme={null}
      import requests

      url = "https://api.insightssystem.com/api:U9ztporN/send/message"
      api_key = "YOUR_API_KEY"

      payload = {
          "to": "+15551234567",
          "type": "document",
          "document": {
              "link": "https://storage.googleapis.com/your-bucket/user-manual.pdf",
              "caption": "Here is the complete user manual you requested.",
              "filename": "Product_User_Manual_v2.1.pdf"
          },
          "recipient_type": "individual",
          "messaging_product": "whatsapp",
          "labels": ["support", "documentation"]
      }

      headers = {
          "Content-Type": "application/json",
          "Authorization": f"Bearer {api_key}"
      }

      response = requests.post(url, json=payload, headers=headers)
      print(response.json())
      ```
    </CodeGroup>
  </Tab>
</Tabs>

### Example Response

<CodeGroup>
  ```json Success Response theme={null}
  {
    "success": true,
    "whatsapp_response_info": {
      "messaging_product": "whatsapp",
      "contacts": [
        {
          "input": "+15551234567",
          "wa_id": "15551234567"
        }
      ],
      "messages": [
        {
          "id": "wamid.HBgLMTU1NTEyMzQ1NjcVAgAERgINQTlEOEJDNzM5QzQwAA==",
          "message_status": "accepted"
        }
      ]
    }
  }
  ```

  ```json Error Response theme={null}
  {
    "success": false,
    "error": {
      "code": "invalid_phone_number",
      "message": "The phone number format is invalid. Please use international format with country code."
    }
  }
  ```
</CodeGroup>

## Response Codes

<AccordionGroup>
  <Accordion title="200: Success">
    Your request was successful and the message has been accepted for delivery.
  </Accordion>

  <Accordion title="400: Bad Request">
    The request was invalid. Check the error message for details about missing or invalid parameters.

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "missing_required_field",
        "message": "The 'to' field is required and must be a valid phone number"
      }
    }
    ```
  </Accordion>

  <Accordion title="401: Unauthorized">
    Authentication failed. Verify that you're using a valid API key in the Authorization header.

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "unauthorized",
        "message": "Invalid API key provided"
      }
    }
    ```
  </Accordion>

  <Accordion title="403: Forbidden">
    Your account doesn't have permission to send messages or has reached its usage limit.
  </Accordion>

  <Accordion title="413: Payload Too Large">
    The media file or message content exceeds size limits.

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "file_too_large",
        "message": "The media file exceeds the maximum allowed size"
      }
    }
    ```
  </Accordion>

  <Accordion title="422: Unprocessable Entity">
    The request contains invalid data or the media URL is not accessible.

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "invalid_media_url",
        "message": "The provided media URL is not accessible"
      }
    }
    ```
  </Accordion>

  <Accordion title="429: Too Many Requests">
    You've exceeded the rate limit. Implement exponential backoff and retry logic.
  </Accordion>

  <Accordion title="500: Server Error">
    An internal server error occurred. Contact support if the issue persists.

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "server_error",
        "message": "An internal server error occurred. Please try again later."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## 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

<CardGroup cols={2}>
  <Card title="Best Practices" icon="shield-check">
    * 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
  </Card>

  <Card title="Use Cases" icon="lightbulb">
    * Customer support responses
    * Order confirmations
    * Quick updates and notifications
    * FAQ responses
  </Card>
</CardGroup>

### Media Messages

<CardGroup cols={2}>
  <Card title="Images" icon="image">
    * **Formats**: JPG, JPEG, PNG
    * **Max Size**: 5MB
    * **Optimal**: 1080x1080px or 16:9 ratio
    * **Use for**: Product photos, screenshots, infographics
  </Card>

  <Card title="Videos" icon="video">
    * **Formats**: MP4, 3GPP
    * **Max Size**: 16MB
    * **Max Duration**: 90 seconds
    * **Use for**: Tutorials, product demos, explanations
  </Card>

  <Card title="Audio" icon="volume-high">
    * **Formats**: MP3, AAC, AMR, OGG
    * **Max Size**: 16MB
    * **Max Duration**: 30 minutes
    * **Use for**: Voice messages, audio instructions
  </Card>

  <Card title="Documents" icon="file-text">
    * **Formats**: PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX
    * **Max Size**: 100MB
    * **Use for**: Manuals, invoices, reports, contracts
  </Card>
</CardGroup>

## Media Requirements

<Warning>
  All media URLs must be publicly accessible via HTTPS without requiring authentication. For security-sensitive content, consider using signed URLs with expiration times.
</Warning>

### URL Requirements

<Steps>
  <Step title="Public Accessibility">
    Ensure your media URLs are publicly accessible without authentication headers or login requirements.
  </Step>

  <Step title="HTTPS Protocol">
    All media URLs must use HTTPS protocol. HTTP URLs will be rejected.
  </Step>

  <Step title="Direct File Access">
    URLs should point directly to the file, not to a page that contains the file or requires redirects.
  </Step>

  <Step title="Content-Type Headers">
    Your server should return appropriate Content-Type headers for media files to ensure proper handling.
  </Step>
</Steps>

### 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

<CardGroup cols={2}>
  <Card title="Message Optimization" icon="rocket">
    Keep messages concise and actionable. Use rich media when it adds value. Always include clear next steps or calls-to-action when appropriate.
  </Card>

  <Card title="Error Handling" icon="octagon-check">
    Implement comprehensive error handling with retries. Store failed messages for later retry. Monitor success rates and investigate patterns in failures.
  </Card>

  <Card title="Media Management" icon="server">
    Use CDN for media hosting to ensure fast loading. Implement media validation before sending. Consider file size optimization for better delivery rates.
  </Card>

  <Card title="Analytics & Tracking" icon="chart-bar">
    Use labels consistently for message categorization. Track message IDs for delivery status monitoring. Implement webhook handling for real-time status updates.
  </Card>
</CardGroup>

## Security Considerations

<CardGroup cols={2}>
  <Card title="API Key Security" icon="key">
    * Never expose API keys in client-side code
    * Use environment variables for key storage
    * Rotate keys regularly
    * Implement IP whitelisting when possible
  </Card>

  <Card title="Data Privacy" icon="shield-halved">
    * 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
  </Card>
</CardGroup>

## FAQs

<AccordionGroup>
  <Accordion title="Can I send messages to users who haven't messaged me first?">
    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](/api-reference/notifier-system/templates/send-template-message).
  </Accordion>

  <Accordion title="Why are my media messages failing?">
    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.
  </Accordion>

  <Accordion title="How do I track message delivery status?">
    Use the message ID returned in the response to track status via webhooks or the [Message Status API](/api-reference/notifier-system/message-status). The initial response only confirms WhatsApp accepted the message, not final delivery.
  </Accordion>

  <Accordion title="Can I schedule messages for later delivery?">
    This API sends messages immediately. For scheduled messaging, implement your own scheduling logic or use our [Scheduled Messages API](/api-reference/notifier-system/scheduled-messages).
  </Accordion>

  <Accordion title="What happens if the recipient doesn't have WhatsApp?">
    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.
  </Accordion>

  <Accordion title="How do I handle different time zones for my recipients?">
    Consider implementing timezone-aware sending in your application logic. Send messages during business hours in the recipient's local timezone for better engagement rates.
  </Accordion>
</AccordionGroup>

<Card title="Need help?" icon="headset" href="mailto:team@whatsable.app">
  Our support team is available 24/7 to help with API integration, troubleshooting, or any questions about sending messages.
</Card>