WhatsApp Business Messaging

Overview

DIDfarm WhatsApp Business lets you send template messages, receive customer replies, and manage conversations — all from the same portal and API you use for phone numbers and SMS. Messages are billed per-message from your wallet balance with category-based pricing.

With DIDfarm WhatsApp you can:

• Send template messages — order confirmations, delivery updates, appointment reminders, and OTPs
• Receive and reply — customer-initiated conversations with free replies within 24 hours
• Manage templates — create, submit for Meta approval, and track template status
• Forward inbound messages — to email, webhook, or view in the portal
• Integrate via API — programmatic access for sending, receiving, and status tracking

How It Works

WhatsApp Business messaging operates differently from SMS. There are four message categories with different pricing:

Message flow

1. Outbound (you initiate): You send a pre-approved template message → customer receives it on WhatsApp → you receive delivery and read receipts
2. Inbound (customer initiates): Customer sends a message → DIDfarm receives it via webhook → 24-hour reply window opens → you reply with free-form text

Prerequisites

Before connecting WhatsApp to DIDfarm, you need:

1. A Meta Business Account — create one at business.facebook.com
2. A WhatsApp Business Account (WABA) — created through the Meta Developers portal
3. A registered phone number — a number verified for WhatsApp Business (can be a new number or an existing one not already on WhatsApp)
4. A permanent access token — generated via a System User in Meta Business Settings (temporary tokens expire in 24 hours)
5. Wallet balance — outbound messages are charged from your DIDfarm wallet

Step 1 — Connect Your WhatsApp Business Account

In the Meta Developers portal, go to your app → WhatsApp → API Setup. Copy the following values:

• Phone number ID — shown next to your registered number
• WhatsApp Business Account ID — shown below the phone number ID
• Access token — use "Generate access token" for testing, or create a permanent System User token

Go to My Numbers → WhatsApp tab. If you have no accounts connected, you'll see the setup wizard. Enter your:

• WABA ID — your WhatsApp Business Account ID
• Phone Number ID — the phone number ID from Meta
• Access Token — your permanent (or temporary for testing) access token
• Display Name (optional) — a friendly label for this account

Click Connect WhatsApp Account. DIDfarm will verify your credentials and automatically sync your message templates from Meta.

Step 2 — Create Message Templates

To send outbound messages (outside the 24-hour service window), you need at least one approved message template. Templates are pre-approved message formats that Meta reviews for policy compliance.

Creating a template in Meta Business Manager

1. Go to WhatsApp Manager → Message Templates
2. Click Create Template
3. Choose a category: Utility (transactional), Authentication (OTP), or Marketing (promotional)
4. Enter a template name (lowercase, underscores only, e.g. order_confirmation)
5. Select the language (e.g. en for English, nl for Dutch)
6. Write the message body with variables: Hello 1, your order 2 has shipped!
7. Submit for review — approval typically takes minutes to a few hours

Viewing templates in DIDfarm

Once approved, templates appear in the Templates tab of your WhatsApp section in the portal. Each template shows its name, language, category, and approval status (Approved, Pending, or Rejected).

You can also create templates via the DIDfarm API:

curl -X POST https://didfarm.com/api/v1/whatsapp/templates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "name": "order_shipped",
    "category": "UTILITY",
    "language": "en",
    "components": [
      {
        "type": "BODY",
        "text": "Hi 1, your order 2 has shipped! Track: 3"
      }
    ]
  }'

Step 3 — Send Messages

Sending from the portal

1. Go to My Numbers → WhatsApp → Compose
2. Select your WhatsApp account
3. Enter the recipient phone number in E.164 format (e.g. +31612345678)
4. Select an approved template from the dropdown
5. Click Send Template Message

Sending via API

POST /api/v1/whatsapp/messages

curl -X POST https://didfarm.com/api/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "to": "+31612345678",
    "type": "template",
    "template": {
      "name": "order_shipped",
      "language": "en",
      "components": [
        {
          "type": "body",
          "parameters": [
            {"type": "text", "text": "John"},
            {"type": "text", "text": "ORD-5678"},
            {"type": "text", "text": "https://track.example.com/5678"}
          ]
        }
      ]
    }
  }'

curl -X POST https://didfarm.com/api/v1/whatsapp/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": 1,
    "to": "+31612345678",
    "type": "text",
    "body": "Thanks for your message! Let me check on that for you."
  }'

{
  "data": {
    "id": 42,
    "account_id": 1,
    "from": "109876543210",
    "to": "+31612345678",
    "body": null,
    "direction": "outbound",
    "type": "template",
    "category": "utility",
    "template_name": "order_shipped",
    "status": "sent",
    "cost": 0.03,
    "currency": "EUR",
    "error_code": null,
    "error_message": null,
    "created_at": "2026-04-03T14:30:00+00:00"
  }
}

Step 4 — Receive & Reply to Messages

In the portal

Inbound WhatsApp messages appear in the Conversations tab, grouped by contact. Click on a conversation to see the full message thread and type a reply directly. Replies sent within 24 hours of the customer's last message are free (Service category).

Via webhook

If you've configured a webhook URL on your DID number's WhatsApp forwarding settings, inbound messages are POSTed to your endpoint in real-time:

{
  "event": "message.received",
  "message_id": 55,
  "from": "+31612345678",
  "to": "109876543210",
  "body": "Hi, when will my order arrive?",
  "type": "text",
  "received_at": "2026-04-03T14:35:00+00:00"
}

Via API (polling)

GET /api/v1/whatsapp/messages?direction=inbound

Returns a paginated list of inbound messages. Use the since parameter to fetch only new messages since a given timestamp.

Step 5 — Configure Forwarding

Inbound WhatsApp messages can be forwarded automatically, just like SMS. Configure per-number in My Numbers → Number Settings:

Pricing

WhatsApp messages are charged per-message from your DIDfarm wallet. Rates vary by message category and destination country. Service replies within the 24-hour window are always free.

Default rates (EUR)

How billing works

• Wallet-based: Message costs are deducted from your DIDfarm wallet in real-time when the message is sent
• Auto-refund: If a message fails to deliver, the charge is automatically refunded to your wallet
• Inbound is free: You are never charged for receiving messages
• Service replies are free: Replies within the 24-hour window are not charged
• Insufficient balance: Messages will fail if your wallet balance is too low — top up via the Wallet tab

Additional fees

API Reference

All WhatsApp API endpoints require authentication via Bearer token (API key) or session cookie. Base URL:

https://didfarm.com/api/v1/whatsapp

Endpoints

Send message request body

Message statuses

Status webhook payload

If you provide a status_callback_url when sending, DIDfarm will POST status updates to your endpoint:

{
  "event": "message.status",
  "message_id": 42,
  "meta_id": "wamid.HBgNMzE2MTIzNDU2NzgVAgA...",
  "status": "delivered",
  "to": "+31612345678",
  "error_code": null,
  "timestamp": "2026-04-03T14:30:05+00:00"
}

Troubleshooting

Message failed to send

• Insufficient wallet balance — top up your wallet before sending
• Template not approved — check template status in the Templates tab; only APPROVED templates can be used
• No active service window — for text replies, the customer must have messaged within the last 24 hours
• Invalid phone number — ensure the recipient has WhatsApp and the number is in E.164 format
• Access token expired — if using a temporary token, generate a new one or switch to a permanent System User token

Not receiving inbound messages

• Verify your webhook is subscribed to the messages field in Meta Developer Console → WhatsApp → Configuration
• Check that your account shows as "Active" in the WhatsApp tab
• Ensure your Meta app is published (unpublished apps only receive webhooks from test numbers)

FAQ

Can I use my existing DIDfarm phone number for WhatsApp?

WhatsApp requires a separate phone number registration through Meta. You can use any number that is not already registered on WhatsApp, including a DIDfarm DID number. The number must be able to receive an SMS or voice call for verification.

What's the difference between a temporary and permanent token?

Temporary tokens expire in ~24 hours and are meant for testing only. For production, create a System User in Meta Business Settings → System Users and generate a permanent token with the required WhatsApp permissions.

How many messages can I send per second?

The default rate limit is 80 messages per second per phone number. DIDfarm automatically queues messages that exceed this limit. For higher throughput, contact Meta to upgrade to 1,000 MPS.

Can I send messages to any country?

WhatsApp is available in 180+ countries. You can send messages to any WhatsApp user worldwide. Pricing varies by destination country and message category.

What happens if a message fails?

If a message fails to deliver, the cost is automatically refunded to your DIDfarm wallet. You can check the error code and message in the message detail via the portal or API.

Do I need to verify my business with Meta?

For testing, no. For production use with higher messaging limits, Meta requires business verification. This involves submitting your business registration documents through Meta Business Manager. Verification typically takes 2–5 business days.