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

# WhatsAble API

> Send programmatic WhatsApp messages with the WhatsAble API

# WhatsAble API

> Send programmatic WhatsApp messages with ease

<Frame caption="WhatsAble API enables seamless WhatsApp integration">
  <img className="block dark:hidden" src="https://mintcdn.com/whatsable/denF9KomrZc8Vz_c/images/hero-light.png?fit=max&auto=format&n=denF9KomrZc8Vz_c&q=85&s=4b5a996b8c6fe875189c8fe73cad0009" alt="WhatsAble API Hero Image" width="6000" height="3375" data-path="images/hero-light.png" />

  <img className="hidden dark:block" src="https://mintcdn.com/whatsable/denF9KomrZc8Vz_c/images/hero-dark.png?fit=max&auto=format&n=denF9KomrZc8Vz_c&q=85&s=a5c8bb5fb9981503cb4cb518b5b8c59b" alt="WhatsAble API Hero Image" width="2064" height="1104" data-path="images/hero-dark.png" />
</Frame>

## Overview

WhatsAble API enables developers to programmatically send WhatsApp messages with rich media support. Our RESTful API delivers enterprise-grade reliability while maintaining a simple integration process. Whether you're building a customer support platform, marketing automation system, or notification service, WhatsAble API gives you the tools to engage your users on WhatsApp.

<CardGroup cols={2}>
  <Card title="Quick Start" icon="bolt" href="#getting-started">
    Send your first WhatsApp message in under 5 minutes
  </Card>

  <Card title="API Reference" icon="code" href="#api-reference">
    Complete API endpoints and parameters documentation
  </Card>

  <Card title="Media Support" icon="image" href="#supported-media-types">
    Send images, videos, documents, and more
  </Card>

  <Card title="Templates" icon="layer-group" href="#template-based-messaging">
    Use templates for structured messages
  </Card>
</CardGroup>

## Key Features

<AccordionGroup>
  <Accordion title="Rich Media Messaging" icon="photo-film">
    Send WhatsApp messages with text, images, videos, documents, and audio files.
  </Accordion>

  <Accordion title="Template-Based Messaging" icon="layer-group">
    Use pre-defined templates for structured messages, enabling you to send consistent communications.
  </Accordion>

  <Accordion title="No-Code Integration" icon="puzzle-piece">
    Seamlessly integrate with platforms like Zapier and Make.com without writing code.
  </Accordion>

  <Accordion title="Enterprise Scalability" icon="chart-line">
    Send messages to thousands of recipients with high deliverability and reliability.
  </Accordion>
</AccordionGroup>

## Getting Started

<Steps>
  <Step title="Create a WhatsAble Account">
    Sign up for a [WhatsAble account](https://dashboard.whatsable.app/register) and activate your subscription or start a free trial.

    <Note>
      You'll need a WhatsApp-enabled phone number to send messages from your account.
    </Note>
  </Step>

  <Step title="Obtain Your API Key">
    Navigate to the API section in your WhatsAble dashboard and generate an API key.

    <Warning>
      Keep your API key secure and never share it publicly. It grants full access to send messages from your account.
    </Warning>
  </Step>

  <Step title="Send Your First Message">
    Use the examples below to send your first WhatsApp message programmatically.
  </Step>
</Steps>

## API Reference

### Base URL

<CodeGroup>
  ```bash Base URL theme={null}
  https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0
  ```

  ```bash Legacy URL (v1) theme={null}
  https://dashboard.whatsable.app/api/whatsapp/messages
  ```
</CodeGroup>

### Authentication

All API requests require authentication using your API key in the request header:

<ParamField header="Authorization" type="string" required>
  Your WhatsAble API key
</ParamField>

<CodeGroup>
  ```bash Example theme={null}
  curl -X POST https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0/send \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+1234567890",
    "text": "Hello from WhatsAble!"
  }'
  ```
</CodeGroup>

### Send Message Endpoint

<ParamField path="send" type="string">
  Endpoint to send WhatsApp messages
</ParamField>

#### Request Parameters

<ResponseField name="Body Parameters" type="Object">
  <Expandable title="properties">
    <ResponseField name="to" type="string" required>
      The recipient's phone number in E.164 format (e.g., +1234567890)
    </ResponseField>

    <ResponseField name="text" type="string" required>
      The message content you want to send
    </ResponseField>

    <ResponseField name="attachment" type="string">
      URL or base64-encoded file for attachments (images, videos, PDFs)
    </ResponseField>

    <ResponseField name="filename" type="string">
      Name of the file when sending a document attachment
    </ResponseField>
  </Expandable>
</ResponseField>

#### Response

<ResponseField name="Success Response" type="Object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">
      Indicates if the message was sent successfully (true)
    </ResponseField>

    <ResponseField name="message" type="string">
      A human-readable message describing the result
    </ResponseField>

    <ResponseField name="details" type="object">
      <Expandable title="properties">
        <ResponseField name="messages" type="array">
          <Expandable title="properties">
            <ResponseField name="id" type="string">
              Unique identifier for the message (e.g., wamid.XXXXXX)
            </ResponseField>

            <ResponseField name="message_status" type="string">
              Status of the message (e.g., "accepted")
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0/send \
  -H 'Authorization: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "to": "+1234567890",
    "text": "Hello, this is a test message from WhatsAble!",
    "attachment": "https://example.com/image.jpg",
    "filename": "image.jpg"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success Response theme={null}
  {
    "success": true,
    "message": "Message sent successfully to +1234567890",
    "details": {
      "messages": [
        {
          "id": "wamid.XXXXXX",
          "message_status": "accepted"
        }
      ]
    }
  }
  ```
</ResponseExample>

### Error Codes

<AccordionGroup>
  <Accordion title="400 Bad Request">
    ```json theme={null}
    {
      "success": false,
      "message": "Invalid phone number format",
      "details": "Phone number must be in E.164 format."
    }
    ```

    <Tip>
      Ensure phone numbers are in E.164 format (e.g., +1234567890) with country code.
    </Tip>
  </Accordion>

  <Accordion title="401 Unauthorized">
    ```json theme={null}
    {
      "success": false,
      "message": "API key is required"
    }
    ```

    <Warning>
      Make sure you're including the API key in the Authorization header.
    </Warning>
  </Accordion>

  <Accordion title="403 Forbidden">
    ```json theme={null}
    {
      "success": false,
      "message": "Invalid API Key"
    }
    ```

    <Warning>
      Verify your API key is correct and active in your WhatsAble dashboard.
    </Warning>
  </Accordion>

  <Accordion title="404 Not Found">
    ```json theme={null}
    {
      "success": false,
      "message": "The number +1234567890 is not registered."
    }
    ```

    <Info>
      The recipient's number must be registered with WhatsApp to receive messages.
    </Info>
  </Accordion>
</AccordionGroup>

## Code Examples

<CodeGroup>
  ```javascript JavaScript (Fetch) theme={null}
  const sendWhatsAppMessage = async () => {
    const apiKey = 'YOUR_API_KEY';
    const endpoint = 'https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0/send';
    
    const payload = {
      to: '+1234567890',
      text: 'Hello, this is a test message from WhatsAble!',
      attachment: 'https://example.com/image.jpg',
      filename: 'image.jpg'
    };
    
    try {
      const response = await fetch(endpoint, {
        method: 'POST',
        headers: {
          'Authorization': apiKey,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(payload)
      });
      
      const data = await response.json();
      console.log('Message sent:', data);
      return data;
    } catch (error) {
      console.error('Error sending message:', error);
      throw error;
    }
  };

  sendWhatsAppMessage();
  ```

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

  def send_whatsapp_message():
      api_key = 'YOUR_API_KEY'
      endpoint = 'https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0/send'
      
      payload = {
          'to': '+1234567890',
          'text': 'Hello, this is a test message from WhatsAble!',
          'attachment': 'https://example.com/image.jpg',
          'filename': 'image.jpg'
      }
      
      headers = {
          'Authorization': api_key,
          'Content-Type': 'application/json'
      }
      
      try:
          response = requests.post(endpoint, headers=headers, data=json.dumps(payload))
          data = response.json()
          print('Message sent:', data)
          return data
      except Exception as e:
          print('Error sending message:', str(e))
          raise e

  send_whatsapp_message()
  ```

  ```php PHP theme={null}
  <?php

  function sendWhatsAppMessage() {
      $apiKey = 'YOUR_API_KEY';
      $endpoint = 'https://dashboard.whatsable.app/api/whatsapp/messages/v2.0.0/send';
      
      $payload = [
          'to' => '+1234567890',
          'text' => 'Hello, this is a test message from WhatsAble!',
          'attachment' => 'https://example.com/image.jpg',
          'filename' => 'image.jpg'
      ];
      
      $headers = [
          'Authorization: ' . $apiKey,
          'Content-Type: application/json'
      ];
      
      $ch = curl_init($endpoint);
      curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
      curl_setopt($ch, CURLOPT_POST, true);
      curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
      curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
      
      $response = curl_exec($ch);
      $error = curl_error($ch);
      curl_close($ch);
      
      if ($error) {
          echo 'Error sending message: ' . $error;
          return false;
      }
      
      $data = json_decode($response, true);
      echo 'Message sent: ' . print_r($data, true);
      return $data;
  }

  sendWhatsAppMessage();
  ```
</CodeGroup>

## Supported Media Types

WhatsAble API supports a wide range of media types for sending rich messages via WhatsApp.

<Tabs>
  <Tab title="Images">
    <ResponseField name="Supported Formats" type="Object">
      <Expandable title="formats">
        <ResponseField name="JPEG" type="Image">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .jpeg, .jpg
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              image/jpeg
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              5MB
            </ResponseField>

            <ResponseField name="Requirements" type="string">
              8-bit, RGB or RGBA
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="PNG" type="Image">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .png
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              image/png
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              5MB
            </ResponseField>

            <ResponseField name="Requirements" type="string">
              8-bit, RGB or RGBA
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <CodeGroup>
      ```javascript Send Image Example theme={null}
      const payload = {
        to: '+1234567890',
        text: 'Check out this image!',
        attachment: 'https://example.com/image.jpg',
        filename: 'image.jpg'
      };
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Videos">
    <ResponseField name="Supported Formats" type="Object">
      <Expandable title="formats">
        <ResponseField name="MP4" type="Video">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .mp4
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              video/mp4
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>

            <ResponseField name="Codec" type="string">
              H.264 video, AAC audio
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="3GPP" type="Video">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .3gp
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              video/3gpp
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>

            <ResponseField name="Codec" type="string">
              H.264 video, AAC audio
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="Documents">
    <ResponseField name="Supported Formats" type="Object">
      <Expandable title="formats">
        <ResponseField name="PDF" type="Document">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .pdf
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              application/pdf
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Microsoft Word" type="Document">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .doc, .docx
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Microsoft Excel" type="Document">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .xls, .xlsx
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Microsoft PowerPoint" type="Document">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .ppt, .pptx
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Text" type="Document">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .txt
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              text/plain
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100MB
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="Audio">
    <ResponseField name="Supported Formats" type="Object">
      <Expandable title="formats">
        <ResponseField name="MP3" type="Audio">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .mp3
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              audio/mpeg
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="AAC" type="Audio">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .aac
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              audio/aac
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="OGG (OPUS)" type="Audio">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .ogg
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              audio/ogg
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>

            <ResponseField name="Codec" type="string">
              OPUS only
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="AMR" type="Audio">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .amr
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              audio/amr
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="MP4 Audio" type="Audio">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .m4a
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              audio/mp4
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              16MB
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>

  <Tab title="Stickers">
    <ResponseField name="Supported Formats" type="Object">
      <Expandable title="formats">
        <ResponseField name="Static Sticker" type="WebP">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .webp
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              image/webp
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              100KB
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="Animated Sticker" type="WebP">
          <Expandable title="specifications">
            <ResponseField name="Extension" type="string">
              .webp
            </ResponseField>

            <ResponseField name="MIME Type" type="string">
              image/webp
            </ResponseField>

            <ResponseField name="Max Size" type="string">
              500KB
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Tab>
</Tabs>

## Template-Based Messaging

WhatsAble intelligently selects the appropriate template based on the message content and attachment type.

<Accordion title="Template Selection Logic" icon="wand-magic-sparkles">
  WhatsAble automatically selects the appropriate template based on your content:

  * **Text-only messages**: Uses templates like `standard_1_line_textonly`, `standard_2_line_textonly`, etc.
  * **Image attachments**: Uses templates like `standard_image_notification_1_lines`, `standard_image_notification_2_lines`, etc.
  * **Video attachments**: Uses templates like `standard_video_notification_1_lines`, `standard_video_notification_2_lines`, etc.
  * **Document attachments**: Uses templates like `standard_doc_message_1_line`, `standard_doc_message_2_lines`, etc.
</Accordion>

<Note>
  Template messaging ensures your messages maintain consistent formatting and follow WhatsApp guidelines.
</Note>

## Rate Limits and Best Practices

<Steps>
  <Step title="Respect Rate Limits">
    WhatsAble enforces rate limits to ensure reliable message delivery. Standard accounts are limited to 50 messages per minute, while enterprise accounts have customizable limits.

    <Warning>
      Exceeding rate limits may result in temporary API access restrictions.
    </Warning>
  </Step>

  <Step title="Implement Error Handling">
    Always implement proper error handling to manage failed message deliveries gracefully:

    ```javascript theme={null}
    try {
      const response = await sendWhatsAppMessage();
      if (!response.success) {
        // Handle specific error based on response message
        console.error('Message sending failed:', response.message);
      }
    } catch (error) {
      // Handle network or server errors
      console.error('API request failed:', error);
    }
    ```
  </Step>

  <Step title="Optimize Media Size">
    Compress images and videos before sending to improve delivery speed and reliability:

    * Resize images to appropriate dimensions for WhatsApp (1080px max width recommended)
    * Compress videos to reduce file size while maintaining quality
    * Use CDN-hosted media when possible rather than base64 encoding
  </Step>
</Steps>

## FAQ

<AccordionGroup>
  <Accordion title="Is WhatsAble officially affiliated with WhatsApp?">
    No, WhatsAble is not affiliated with or endorsed by WhatsApp Inc. WhatsAble uses the WhatsApp Business API to provide its services.
  </Accordion>

  <Accordion title="Do recipients need to opt in before receiving messages?">
    Yes, according to WhatsApp's policy, recipients must explicitly opt in to receive messages from businesses. Ensure you have proper consent before sending messages.
  </Accordion>

  <Accordion title="Can I track message delivery status?">
    Currently, the WhatsAble API provides message acceptance status in the response. Real-time delivery and read receipts are planned for a future release.
  </Accordion>

  <Accordion title="Can I send messages to multiple recipients at once?">
    Yes, but you need to send individual API requests for each recipient. Bulk messaging functionality with a single API call is available for enterprise customers.
  </Accordion>
</AccordionGroup>

## Support

<CardGroup cols={2}>
  <Card title="Live Chat Support" icon="message" href="https://dashboard.whatsable.app/support" color="#25d366">
    Click the green chat button in the bottom right corner of the WhatsAble dashboard
  </Card>

  <Card title="Email Support" icon="envelope" href="mailto:team@whatsable.app" color="#4A9DF8">
    Contact our team at [team@whatsable.app](mailto:team@whatsable.app)
  </Card>
</CardGroup>

<Note>
  Our support team is available Monday through Friday, 9 AM to 6 PM UTC. Enterprise customers receive 24/7 support access.
</Note>

## Updates

<Update label="2023-09-01" description="API v2.0.0 Release">
  <Frame>
    <img className="block dark:hidden" src="https://mintlify.s3.us-west-1.amazonaws.com/whatsable/images/release-v2-light.png" alt="API v2.0.0 Release" />

    <img className="hidden dark:block" src="https://mintlify.s3.us-west-1.amazonaws.com/whatsable/images/release-v2-dark.png" alt="API v2.0.0 Release" />
  </Frame>

  ### What's New

  * **Improved Media Handling**: Support for larger file sizes and more media types
  * **Enhanced Error Reporting**: More detailed error messages and status codes
  * **Better Reliability**: Automatic retry mechanism for failed message delivery
  * **Performance Improvements**: 50% faster message delivery times
</Update>

<Update label="2023-06-15" description="API v1.5.0 Release">
  ### What's New

  * Added support for sticker messages
  * Improved template selection algorithm
  * Fixed issues with document attachments
</Update>

<Tip>
  For a complete changelog, visit the [WhatsAble Release Notes](https://dashboard.whatsable.app/changelog) page.
</Tip>

<Warning>
  API v1 is scheduled for deprecation on December 31, 2023. Please upgrade to v2.0.0 before this date.
</Warning>