WhatsApp API

Reach 2+ billion users on WhatsApp. Send templates, interactive messages, and rich media at enterprise scale.

2B+ Users

Reach the world's most popular messaging platform.

Interactive Messages

Buttons, lists, and quick replies for engagement.

Rich Media

Images, videos, documents, and location sharing.

Conversation Types

WhatsApp has different pricing and rules for business-initiated vs user-initiated conversations.

Business-Initiated

Messages sent outside of a 24-hour session window. Requires approved templates.

Marketing and promotional messages
Order updates and notifications
Authentication codes (OTP)

User-Initiated

Messages within 24 hours of user's last message. Free-form responses allowed.

Customer support conversations
Responding to user inquiries
Interactive conversations

Quick Start

Send your first WhatsApp message using an approved template.

POST/v1/whatsapp/messages

curl -X POST https://api.canarymsg.dev/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
  {
    "to": "+15551234567",
    "template": {
      "name": "order_confirmation",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            { "type": "text", "text": "Alice" },
            { "type": "text", "text": "#12345" }
          ]
        }
      ]
    }
  }
'

Response

{
  "id": "wamid_abc123xyz",
  "to": "+15551234567",
  "type": "template",
  "status": "sent",
  "created_at": "2024-01-01T12:00:00Z"
}

Message Templates

Templates must be approved by Meta before use. Canary provides a template management API and dashboard for creating and submitting templates.

Create a Template

POST/v1/whatsapp/templates

{
  "name": "order_shipped",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Order Shipped!"
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, your order {{2}} has been shipped. Track it here: {{3}}"
    },
    {
      "type": "FOOTER",
      "text": "Thanks for shopping with us!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Track Order",
          "url": "https://yourstore.com/track/{{1}}"
        }
      ]
    }
  ]
}

Template Categories

Category	Use Case	Pricing
`UTILITY`	Order updates, shipping, appointments	Standard rate
`MARKETING`	Promotions, offers, product updates	Premium rate
`AUTHENTICATION`	OTP, verification codes	Lowest rate

Interactive Messages

Send interactive messages with buttons, lists, and quick replies to increase engagement and guide user actions.

Button Message

{
  "to": "+15551234567",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "Would you like to confirm your appointment?"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "confirm",
            "title": "Confirm"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "reschedule",
            "title": "Reschedule"
          }
        }
      ]
    }
  }
}

List Message

{
  "to": "+15551234567",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "body": {
      "text": "Please select a product category:"
    },
    "action": {
      "button": "View Categories",
      "sections": [
        {
          "title": "Electronics",
          "rows": [
            { "id": "phones", "title": "Phones", "description": "Latest smartphones" },
            { "id": "laptops", "title": "Laptops", "description": "Work & gaming" }
          ]
        },
        {
          "title": "Fashion",
          "rows": [
            { "id": "clothing", "title": "Clothing", "description": "Men & women" },
            { "id": "shoes", "title": "Shoes", "description": "All styles" }
          ]
        }
      ]
    }
  }
}

Media Messages

Send images, videos, documents, and audio files to engage users with rich content.

Image Message

{
  "to": "+15551234567",
  "type": "image",
  "image": {
    "url": "https://example.com/product.jpg",
    "caption": "Check out our new product!"
  }
}

Supported Media Types

Type	Formats	Max Size
Image	JPEG, PNG	5 MB
Video	MP4, 3GPP	16 MB
Audio	AAC, MP3, OGG, AMR	16 MB
Document	PDF, DOC, XLS, PPT, etc.	100 MB
Sticker	WebP	500 KB

Receiving Messages

Configure webhooks to receive incoming messages and status updates.

Incoming Message Webhook

{
  "type": "message",
  "from": "+15551234567",
  "timestamp": "2024-01-01T12:00:00Z",
  "message": {
    "id": "wamid_xyz789",
    "type": "text",
    "text": {
      "body": "Hi, I need help with my order"
    }
  },
  "contact": {
    "name": "Alice Smith",
    "wa_id": "15551234567"
  }
}

SDK Examples

Node.js

import Canary from '@canary/node';

const canary = new Canary('YOUR_API_KEY');

// Send a template message
const message = await canary.whatsapp.send({
  to: '+15551234567',
  template: {
    name: 'order_confirmation',
    language: 'en',
    components: [
      {
        type: 'body',
        parameters: [
          { type: 'text', text: 'Alice' },
          { type: 'text', text: '#12345' }
        ]
      }
    ]
  }
});

console.log('Message sent:', message.id);

Python

from canary import Canary

canary = Canary("YOUR_API_KEY")

message = canary.whatsapp.send(
    to="+15551234567",
    template={
        "name": "order_confirmation",
        "language": "en",
        "components": [
            {
                "type": "body",
                "parameters": [
                    {"type": "text", "text": "Alice"},
                    {"type": "text", "text": "#12345"}
                ]
            }
        ]
    }
)

print(f"Message sent: {message.id}")

Next Steps

Global Channels OTP & Verification