API Reference
Help Center
Start typing to search…

WhatsApp Message Sending Guide

Getting Started

Welcome to YCloud WhatsApp Messaging Service!

This guide will help you quickly master how to send WhatsApp messages to your users through the YCloud platform.

What's Covered in This Guide

  • Basic Requirements: Prerequisites and permissions needed before you begin
  • Quick Start: Send your first WhatsApp message in 5 minutes
  • Overview: Understanding WhatsApp messaging mechanisms and conversation window rules
  • Implement: Detailed implementation methods for sending messages
  • Advanced Features: Advanced capabilities and best practices
  • Important Notes: Usage limits, considerations, and common error handling

We recommend reading the sections in order, especially the first three, to build a comprehensive understanding of the system.

Basic Requirements

Before you start sending messages, ensure you have the following ready:

1. API Key

Your API Key is the credential used to access YCloud services. You can obtain it from the "Developers > API Keys" section in the YCloud Console.

Important Notes:

  • Keep your API Key secure—never hardcode it in your source code or commit it to version control
  • Use environment variables or a key management service for storage
  • If your API Key is compromised, regenerate it immediately in the console

2. Sender Phone Number

You'll need a WhatsApp Business phone number that's already registered on the YCloud platform. This number will be used as the sender for your messages.

How to Obtain:

  • Complete the WhatsApp Business account embedded signup in the YCloud Console
  • Ensure the number is verified and in active status
  • A single number can be used to send multiple types of messages

For details about the embedded signup, please refer to Embedded Signup.

3. Recipient Phone Number Format

Recipient phone numbers must be in international format, including the + sign and country code.

Correct Format Examples:

  • +8613800138000 (China)
  • +16505551234 (United States)
  • +44 20 7123 4567 (United Kingdom, spaces allowed)

Incorrect Formats:

  • ❌ 13800138000 (missing + sign and country code)
  • ❌ (650) 555-1234 (missing + sign and country code)

Quick Start: Hello World

Let's send your first WhatsApp message in 5 minutes with a simple example.

Step 1: Create a Message Template

First, create a simple welcome message template in the YCloud Dashboard:

  1. Log in to YCloud Dashboard
  2. Navigate to "WhatsApp Manager > Templates"
  3. Click "New Template > Utility"
  4. Fill in the following information:
    • Template Name: hello_world
    • Language: Select "English"
    • Message Content: 
      Hello! Welcome to YCloud.
  5. Submit for review

Typically, approval takes about 15 minutes. You can check the approval status in the template list.

For the list of languages supported by WhatsApp Template and language codes, please refer to Supported Languages.

Step 2: Send Your First Message

Once the template is approved, use the following curl command to send a message:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",           // Replace with your WhatsApp Business phone number
    "to": "+8613800138000",             // Replace with recipient's number
    "type": "template",                 // Message type: template message
    "template": {
      "name": "hello_world",            // Template name
      "language": {
        "code": "en"                 // Language code
      }
    }
  }'

Step 3: Understanding the Response

If the message is sent successfully, you'll receive a response similar to this:

{
  "id": "6543210abcdef1234567890",     // Message ID for future queries
  "status": "accepted",                 // Status: accepted
  "from": "+8613800000001",
  "to": "+8613800138000",
  "type": "template",
  "createTime": "2024-01-15T10:30:00.000Z"
}

Status Explanation:

  • accepted: Message has been accepted and is being processed
  • This doesn't mean the user has received the message yet—actual delivery status will be sent via Webhook asynchronously

🎉 Congratulations! You've successfully sent your first WhatsApp message. Now let's dive deeper into WhatsApp's messaging mechanisms.

Overview

Understanding WhatsApp's Two Message Types

WhatsApp's messaging mechanism differs from traditional SMS. To protect user experience, WhatsApp categorizes messages into two main types, each with specific use cases and restrictions.

Template Messages: Proactive User Outreach

Imagine you need to send order confirmations, shipping updates, or verification codes to users. In these scenarios, users haven't messaged you first—you need to initiate contact. This is where template messages come in.

Template message characteristics:

  • You must create message templates in WhatsApp Manager and submit them for approval in advance
  • Once approved, you can use the template to send messages at any time without restrictions
  • Templates support variable placeholders for dynamic personalization like usernames, order numbers, etc.

This approach ensures users only receive approved, policy-compliant business messages, preventing spam.

Non-Template Messages: Free-Form Conversation

When a user proactively sends you a message, a 24-hour "conversation window" opens. Within this window, you can freely respond with text, images, videos, or even interactive messages with buttons—no template required.

Note: The "conversation window" is a virtual time-based permission window, not a physical UI element. It represents a 24-hour period during which you have permission to send free-form messages to the user.

After 24 hours, if you want to contact the user again, you'll need to use a template message to start a new conversation.

24-Hour Service Window Mechanism

WhatsApp uses a dual-track window mechanism that provides different messaging permissions based on how users enter the conversation.

gantt
    title WhatsApp Dual-Track Service Window Diagram
    dateFormat YYYY-MM-DD HH:mm
    axisFormat %m-%d %H:%M
    
    section User <br/>Actions
    User sends message                    :milestone, m1, 2025-01-01 10:00, 4h
    User clicks ad and sends message      :milestone, m2, 2025-01-01 10:00, 4h
    
    section Service Window <br/>(24 hours)
    Free-form messages allowed            :active, service_window, 2025-01-01 12:00, 24h
    Window closed                         :done, service_close, after service_window, 48h
    
    section Ad Source Window <br/>(72 hours)
    Free template messages allowed        :crit, ad_window, 2025-01-01 12:00, 72h
    Window closed                         :done, ad_close, after ad_window, 24h

How the Dual-Track System Works:

Track One: 24-Hour Service Window

  • When a user proactively sends you a message, a 24-hour service window opens immediately
  • Within these 24 hours, you can freely send any type of message (text, images, Interactive, etc.)
  • After 24 hours, the window closes and you can only send pre-approved template messages
  • If the user sends another message, the window reopens for another 24 hours

Track Two: 72-Hour Ad Source Window

  • When a user clicks through an ad (e.g., Facebook/Instagram ads) and sends their first message, in addition to the 24-hour service window, a 72-hour ad source window also opens
  • Within these 72 hours, you can send template messages for free (normally template messages are charged)
  • This window encourages businesses to build relationships with users acquired through advertising
  • After 72 hours, template message sending returns to normal billing

Sending Methods Comparison

YCloud provides two message sending interfaces that differ in their processing approach:

Asynchronous Sending: Suitable for Most Scenarios

When using the POST /v2/whatsapp/messages endpoint, your message enters a sending queue first, and the API immediately returns a message ID. The system then processes the actual sending asynchronously in the background.

Benefits of this approach:

  • Fast API response time—your application doesn't have to wait
  • Ideal for bulk sending scenarios, allowing rapid submission of large message volumes
  • Your business flow remains unaffected even if underlying services are temporarily busy

Synchronous Sending: For Critical Moments

When using the POST /v2/whatsapp/messages/sendDirectly endpoint, the system immediately attempts to send the message and waits for the sending result before returning.

This approach is particularly suitable for:

  • Sending verification codes (OTP) when you need immediate confirmation of success
  • Real-time customer service scenarios requiring guaranteed instant delivery
  • Situations with strict requirements for sending results

Recommendation: Unless you have specific needs, we recommend using the asynchronous sending method.

Message Status Lifecycle

After sending, messages go through multiple statuses. Understanding these helps you track delivery:

  1. accepted - Your request has been accepted, message enters the queue
  2. sent - Message has been sent to WhatsApp servers
  3. delivered - Message has been delivered to the user's device
  4. read - User has opened and read the message
  5. failed - Sending failed (includes failure reason)

You can track message status in two ways:

  • Active Query: Use the message ID to call the query endpoint
  • Webhook Notifications (recommended): YCloud proactively pushes notifications to your configured address when message status changes

Implement

This section provides detailed instructions on how to send various types of WhatsApp messages using the YCloud API.

Sending Template Messages

Template messages are used for proactive user outreach, suitable for order notifications, marketing campaigns, verification codes, and similar scenarios.

Template Messages with Variables

Suppose you've created an order notification template in WhatsApp Manager:

Template Content:

Hello {{1}}, your order {{2}} has been shipped and is expected to arrive {{3}}.

Sending Example:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "template": {
      "name": "order_shipped",          // Template name
      "language": {
        "code": "en"
      },
      "components": [
        {
          "type": "body",
          "parameters": [
            {
              "type": "text",
              "text": "John"            // Replaces {{1}}
            },
            {
              "type": "text",
              "text": "20240115001"     // Replaces {{2}}
            },
            {
              "type": "text",
              "text": "tomorrow afternoon"  // Replaces {{3}}
            }
          ]
        }
      ]
    }
  }'

Replying to Users in Conversation

Once a user proactively sends you a message, you enter a 24-hour conversation window. Within this window, you can freely send various types of messages.

Sending Text Messages

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "text",
    "text": {
      "body": "Thank you for your inquiry. We will respond shortly.",
      "preview_url": false              // Whether to show link preview
    }
  }'

Sending Interactive Messages (with Buttons)

Interactive messages support buttons, lists, and other interactive elements that allow users to make quick selections:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "interactive",
    "interactive": {
      "type": "button",                 // Interactive type: button
      "body": {
        "text": "Your order has been shipped. Please select an action:"
      },
      "action": {
        "buttons": [                    // Maximum 3 buttons
          {
            "type": "reply",
            "reply": {
              "id": "track_order",      // Button ID
              "title": "Track Order"    // Button text (max 20 characters)
            }
          },
          {
            "type": "reply",
            "reply": {
              "id": "contact_support",
              "title": "Contact Support"
            }
          }
        ]
      }
    }
  }'

When a user clicks a button, you'll receive a notification via Webhook containing the ID of the button clicked.

Sending Media Messages

You can send images, videos, audio, documents, and other media files:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "image",
    "image": {
      "link": "https://example.com/product.jpg",  // Image URL
      "caption": "Check out our new product"      // Image caption (optional)
    }
  }'

Supported Media Types:

  • Images: JPG, PNG (max 5MB)
  • Videos: MP4, 3GP (max 16MB)
  • Audio: AAC, MP3, AMR, OGG (max 16MB)
  • Documents: PDF, DOC, XLSX, etc. (max 100MB)

Best Practice: Upload files to YCloud first, then use the returned id instead of link for better stability and reliability.

Tracking Message Status

Active Query

Query current status using the message ID:

curl -X GET 'https://api.ycloud.com/v2/whatsapp/messages/6543210abcdef1234567890' \
  -H 'X-API-Key: YOUR_API_KEY'

Webhook Notifications (Recommended)

After configuring Webhook, YCloud will proactively push notifications to your server whenever message status changes. This method is more real-time and efficient.

Note: For messaging scenarios, you need to subscribe to the following Webhook events: whatsapp.message.updated (for outbound message status updates) and whatsapp.inbound_message.received (for receiving messages from users).

For detailed Webhook configuration, please refer to the "Webhook Implementation Guide".

Important Notes

Usage Limits

When using YCloud WhatsApp services, there are some restrictions and guidelines to be aware of.

Sending Frequency Limits

  • Sending too many messages to the same user in a short period may result in rate limiting
  • Schedule message sending appropriately to avoid spamming users
  • For bulk messaging needs, we recommend using the asynchronous sending interface
  • About messsaging frequency, please refer to Rate limits.

Message Content Limits

Different message types have different length restrictions:

  • Text messages: maximum 4096 characters
  • Interactive button text: maximum 20 characters, maximum 3 buttons per message
  • Media files have size limits (images 5MB, videos 16MB, documents 100MB, etc.)

Template Review

Template messages must be reviewed before use. The review process ensures message content complies with WhatsApp policies and won't spam users.

  • Typically, reviews are completed within 15 minutes, with a maximum of 24 hours
  • If a template is rejected, you'll receive the rejection reason and can modify and resubmit
  • Approved templates may be suspended or disabled if quality deteriorates (e.g., many user reports)

Advanced Features

Associating Business IDs

In real-world scenarios, you may need to associate WhatsApp messages with orders, tickets, or other records in your system. Use the externalId field to accomplish this:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "externalId": "order_20240115_001",    // Your business ID (e.g., order number)
    "template": {
      "name": "order_notification",
      "language": {
        "code": "en"
      }
    }
  }'

When you receive message status updates via Webhook, you can quickly locate the corresponding business record using the externalId.

Automatic Unsubscribed User Filtering

If you maintain an unsubscribed user list, you can have YCloud automatically filter these users:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "template",
    "filterUnsubscribed": true,            // Automatically filter unsubscribed users
    "filterBlocked": true,                 // Automatically filter blocked users
    "template": {
      "name": "marketing_message",
      "language": {
        "code": "en"
      }
    }
  }'

If the target user is on the unsubscribed or blocked list, the message won't be sent, but you'll still receive a response with the status marked as filtered.

Important Note: The filtering feature only works with the asynchronous sending interface (POST /v2/whatsapp/messages). If you use the synchronous sending interface (POST /v2/whatsapp/messages/sendDirectly), the filterUnsubscribed and filterBlocked parameters will be ignored, and messages will be sent directly. Therefore, if you need to use the filtering feature, be sure to use the asynchronous sending interface.

Replying to Specific Messages

In a conversation, you may want to reply to a specific message from the user. Use the context field to achieve a quoted reply effect:

curl -X POST 'https://api.ycloud.com/v2/whatsapp/messages' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "from": "+8613800000001",
    "to": "+8613800138000",
    "type": "text",
    "text": {
      "body": "Here is the answer to your question"
    },
    "context": {
      "message_id": "wamid.HBgLODYxMzgwMDE..."  // Message ID to reply to
    }
  }'

Users will see your reply associated with their original message in WhatsApp, just like the "quoted reply" feature in regular chat applications.

Common Error Handling

During usage, you may encounter some errors. Below are the most common situations and their solutions.

Phone Number Format Error

This is the most common issue for beginners. WhatsApp requires phone numbers in international format, which must include the + sign and country code.

Correct Formats:

  • +8613800138000 (China)
  • +16505551234 (United States)
  • +44 20 7123 4567 (United Kingdom, spaces and parentheses allowed)

Incorrect Formats:

  • 13800138000 (missing + sign and country code)
  • (650) 555-1234 (missing + sign and country code)

If you see an error like "Invalid phone number format", first check the phone number format.

Template-Related Issues

Template Not Found: If you see "Template does not exist", possible reasons include:

  • Template is still under review and not yet approved
  • Template name spelling error (case-sensitive)
  • Language code mismatch (e.g., template is en_US but request uses zh_CN)

Parameter Count Mismatch: If you see "Template parameter count mismatch", the number of parameters you provided doesn't match the template definition. For example, the template has {{1}} and {{2}} placeholders, but you only provided one parameter value.

Template Suspended: If a template is suspended due to quality issues, you need to modify the template content and resubmit for review.

24-Hour Window Expired

When trying to send text or Interactive messages, if you see "More than 24 hours have passed" error, it means more than 24 hours have elapsed since the user last sent a message.

In this case, you need to use a template message to re-engage the user, or wait for the user to initiate a new conversation.

API Key Authentication Failed

If you see "Invalid API Key" or "Unauthorized", check:

  • Whether the API Key was copied correctly (no extra spaces)
  • Whether the HTTP Header format is correct: X-API-Key: YOUR_API_KEY
  • Whether the API Key has expired or been disabled