Usage for WhatsApp

Note

New in version 2.0: WhatsApp commands now use the intuitive agoras whatsapp format. See the migration guide for upgrading from agoras publish.

WhatsApp Business API is Meta’s official API for sending messages via WhatsApp. Agoras can send text messages, images, videos, and template messages to WhatsApp recipients using the official Meta Graph API.

Important: WhatsApp Business API requires a Meta Developer Account, WhatsApp Business Account, and phone number verification. For production use, business verification is required. You must specify a recipient phone number in E.164 format for all message sending operations. Like, share, and delete functionality are not supported by Agoras for WhatsApp.

For CI/CD environments, see WhatsApp credentials for unattended execution setup.

Actions

Send a WhatsApp text message

This command will send a text message to a WhatsApp recipient. The message can include text and a link.

agoras whatsapp post \
  --access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --recipient "${WHATSAPP_RECIPIENT}" \
  --text "Hello from Agoras!" \
  --link "https://example.com"

Parameters:

  • --access-token: Meta Graph API access token (required)

  • --phone-number-id: WhatsApp Business phone number ID (required)

  • --recipient: Target recipient phone number in E.164 format, e.g., +1234567890 (required)

  • --text: The text content of your message

  • --link: A URL to include in the message

Note: You must provide at least --text or --link. The recipient phone number must be in E.164 format (starts with +, includes country code).

Send a WhatsApp message with image

This command will send an image message to a WhatsApp recipient. The image can include a caption.

agoras whatsapp post \
  --access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --recipient "${WHATSAPP_RECIPIENT}" \
  --text "Check this out!" \
  --link "https://example.com" \
  --image-1 "https://example.com/image.jpg"

Parameters:

  • --image-1 through --image-4: URLs pointing to publicly accessible images (JPEG, PNG, GIF)

  • --text: Caption text for the image (optional)

Image requirements: - Supported formats: JPEG, PNG, GIF - Max size: 5MB per image - URL must be publicly accessible: Images must be hosted on HTTPS URLs - Multiple images: If multiple images are provided, they are sent sequentially (not as a group)

Note: WhatsApp downloads images from the provided URLs. The URLs must be publicly accessible via HTTPS.

Send a WhatsApp video message

This command will send a video message to a WhatsApp recipient. The video can include a caption.

agoras whatsapp video \
  --access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --recipient "${WHATSAPP_RECIPIENT}" \
  --video-url "https://example.com/video.mp4" \
  --video-title "My Video" \
  --text "Check out this video!"

Parameters:

  • --video-url: URL pointing to a publicly accessible video file (required)

  • --video-title: Title for the video (optional, not used by WhatsApp but kept for compatibility)

  • --text: Caption text for the video (optional)

Video requirements: - Supported formats: MP4, 3GP - Max size: 16MB - URL must be publicly accessible: Videos must be hosted on HTTPS URLs - Codec: H.264 video codec recommended

Note: WhatsApp downloads videos from the provided URLs. The URLs must be publicly accessible via HTTPS.

Send a WhatsApp template message

This command will send a pre-approved template message to a WhatsApp recipient. Template messages are required for sending messages outside the 24-hour messaging window.

agoras whatsapp template \
  --access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --recipient "${WHATSAPP_RECIPIENT}" \
  --template-name "hello_world" \
  --language-code "en"

Parameters:

  • --template-name: Name of the pre-approved template (required)

  • --language-code: Language code in ISO 639-1 format, e.g., “en”, “es”, “fr” (default: “en”)

  • --template-components: Template components as JSON string (optional, for parameters, buttons, etc.)

Template requirements: - Templates must be pre-approved by Meta before use - Template approval can take several days - Templates are used for notifications and marketing messages - Language code must match an approved template language - Template components can include parameters, buttons, and other interactive elements

Note: Template messages are required when sending to recipients who haven’t messaged you in the last 24 hours. For recipients within the 24-hour window, you can use regular text messages.

RSS Feed Integration

Agoras can automatically publish content from RSS/Atom feeds to WhatsApp. This is useful for automatically sharing blog posts, news articles, or other syndicated content.

Publish Last Entry

Publish the most recent entry from an RSS feed:

agoras utils feed-publish \
  --network whatsapp \
  --mode last \
  --feed-url "https://blog.example.com/feed.xml" \
  --max-count 1 \
  --post-lookback 3600 \
  --whatsapp-access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --whatsapp-phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --whatsapp-recipient "${WHATSAPP_RECIPIENT}"

Publish Random Entry

Publish a random entry from an RSS feed:

agoras utils feed-publish \
  --network whatsapp \
  --mode random \
  --feed-url "https://blog.example.com/feed.xml" \
  --max-post-age 30 \
  --whatsapp-access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --whatsapp-phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --whatsapp-recipient "${WHATSAPP_RECIPIENT}"

Feed Options:

  • --network: Set to whatsapp (required)

  • --mode: Selection mode: last or random (required)

  • --feed-url: URL of the RSS/Atom feed (required)

  • --max-count: Maximum number of posts to publish at once (default: 1)

  • --post-lookback: Only publish posts from the last N seconds

  • --max-post-age: Don’t publish posts older than N days

Feed format requirements: - Feed items should have <title>, <link>, and optionally <enclosure> for images - Images from feed enclosures will be sent with the message - Text and links are combined into the WhatsApp message

Google Sheets Scheduling

Agoras can schedule WhatsApp messages using Google Sheets. This allows you to plan and automate message sending.

Run Scheduled Messages

Process scheduled messages from a Google Sheet:

agoras utils schedule-run \
  --network whatsapp \
  --sheets-id "${GOOGLE_SHEETS_ID}" \
  --sheets-name "WhatsApp" \
  --sheets-client-email "${GOOGLE_SHEETS_CLIENT_EMAIL}" \
  --sheets-private-key "${GOOGLE_SHEETS_PRIVATE_KEY}" \
  --whatsapp-access-token "${WHATSAPP_ACCESS_TOKEN}" \
  --whatsapp-phone-number-id "${WHATSAPP_PHONE_NUMBER_ID}" \
  --whatsapp-recipient "${WHATSAPP_RECIPIENT}"

Sheet Format

Your Google Sheet should have the following columns:

  • status_text: Message text content

  • status_link: URL to include in message

  • status_image_url_1 through status_image_url_4: Image URLs (optional)

  • date: Scheduled date (format: DD-MM-YYYY)

  • hour: Scheduled hour (format: HH, 24-hour format)

  • state: Post state (pending, published, error)

Example sheet row:

status_text,status_link,status_image_url_1,date,hour,state
"Hello World","https://example.com","https://example.com/image.jpg","25-12-2024","14","pending"

Scheduling Logic

  • Posts with state="pending" and scheduled time in the past are processed

  • Posts are created at the scheduled date and hour

  • Sheet state is updated to published after successful posting

  • If posting fails, state is updated to error

  • Use --network whatsapp to process only WhatsApp posts, or omit to process all networks

Configuration

Environment Variables

For security, store credentials in environment variables:

export WHATSAPP_ACCESS_TOKEN="your_access_token_here"
export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id_here"
export WHATSAPP_BUSINESS_ACCOUNT_ID="your_business_account_id_here"  # Optional
export WHATSAPP_RECIPIENT="+1234567890"  # E.164 format

Then use Agoras without specifying credentials in commands:

agoras whatsapp post \
  --text "Hello from Agoras!" \
  --link "https://example.com"

Parameter Precedence

  1. Command-line arguments (highest priority)

  2. Environment variables

  3. Configuration files (if supported)

Security Recommendations

  • Never commit credentials to version control: Use .gitignore for credential files

  • Use environment variables: Store credentials in environment variables, not in code

  • Use secrets managers: For production, use AWS Secrets Manager, HashiCorp Vault, etc.

  • Rotate tokens periodically: Generate new tokens and revoke old ones

  • Limit token permissions: Only grant necessary permissions

  • Monitor token usage: Regularly check for unauthorized access

Troubleshooting

Common Errors and Solutions

Error: “WhatsApp access token and phone number ID are required” - Solution: Ensure you’ve provided both --access-token and --phone-number-id parameters or set the corresponding environment variables.

Error: “WhatsApp recipient phone number is required” - Solution: Provide --recipient parameter with a phone number in E.164 format (e.g., +1234567890).

Error: “Invalid phone number format” - Solution: Ensure phone number is in E.164 format: starts with +, includes country code, no spaces or special characters except +.

Error: “WhatsApp API error: Invalid access token” - Solution: Generate a new access token. Temporary tokens expire in 24 hours. Check token permissions in Meta Business Manager.

Error: “WhatsApp API error: Phone number not found” - Solution: Verify the Phone Number ID is correct. Check your app dashboard for the correct ID.

Error: “WhatsApp API error: Rate limit exceeded” - Solution: You’ve exceeded the rate limit (1000 messages/day for free tier). Wait for the limit to reset or complete business verification for higher limits.

Error: “Failed to validate image/video/document” - Solution: Ensure the URL is publicly accessible via HTTPS. Check that the file format is supported and file size is within limits.

Error: “Template not found” - Solution: Ensure the template name is correct and the template is approved in your Meta Business Manager.

Rate Limiting Issues

  • Free tier limit: 1,000 messages per day

  • Limit reset: Daily at midnight UTC

  • Per recipient limits: Additional limits apply per recipient

  • Business verification: Increases limits significantly

  • Error handling: Agoras will show clear error messages when rate limits are exceeded

Business Verification Problems

  • Verification pending: Business verification can take 3-7 business days

  • Documentation required: Submit all required business documents

  • Status check: Monitor verification status in Meta Business Manager

  • Support contact: Contact Meta support if verification is delayed

Token Expiration Handling

  • Temporary tokens: Expire in 24 hours - generate new token before expiration

  • Permanent tokens: Don’t expire unless revoked - store securely

  • Token refresh: Not supported for WhatsApp (unlike OAuth refresh tokens)

  • Error messages: Agoras will show clear error messages if token is invalid

Message Delivery Issues

  • 24-hour window: Can only send free-form messages within 24 hours of recipient’s last message

  • Template messages: Required for messages outside 24-hour window

  • Recipient opt-out: Recipients can opt-out at any time

  • Delivery status: Check message delivery status in Meta Business Manager

  • Test numbers: Use test phone numbers during development

Best Practices

Message Formatting Tips

  • Keep messages concise: WhatsApp messages work best when brief and clear

  • Use formatting: WhatsApp supports basic text formatting (bold, italic, etc.)

  • Include links: Use --link parameter to include URLs in messages

  • Image captions: Use --text parameter to add captions to images

  • Multiple images: Send multiple images sequentially for better delivery

Media Optimization

  • Image formats: Use JPEG or PNG for best compatibility

  • Image size: Keep images under 5MB for faster delivery

  • Video formats: Use MP4 with H.264 codec

  • Video size: Keep videos under 16MB

  • Document formats: Use common formats (PDF, DOCX, etc.)

  • URL accessibility: Ensure all media URLs are publicly accessible via HTTPS

Rate Limit Management

  • Plan message sending: Distribute messages throughout the day

  • Monitor usage: Track daily message counts

  • Business verification: Complete verification for higher limits

  • Batch sending: Use scheduling for planned message campaigns

  • Error handling: Implement retry logic for rate limit errors

Compliance Guidelines

  • WhatsApp Business Policy: Follow Meta’s WhatsApp Business Policy

  • Message templates: Use pre-approved templates for notifications

  • Opt-in requirements: Ensure recipients have opted in to receive messages

  • Data privacy: Comply with GDPR and local data protection laws

  • Content guidelines: Follow WhatsApp’s content and spam policies

  • Recipient management: Respect opt-outs immediately

Security Recommendations

  • Token security: Store tokens in environment variables or secrets managers

  • Token rotation: Rotate tokens periodically for security

  • Access control: Limit who has access to WhatsApp credentials

  • Monitoring: Monitor for unauthorized access or unusual activity

  • Backup credentials: Keep backup tokens in secure storage

  • Revocation: Immediately revoke compromised tokens

Additional Resources