Send WhatsApp messages through Zeiko

POST /api/whatsapp/messages?accountSlug={accountSlug}

Production URL: https://zeiko.io/api/whatsapp/messages?accountSlug=acme

The endpoint also supports OPTIONS preflight requests for browser and integration clients.

Send a scoped workforce API key for the same account in the authorization header.

Authorization: Bearer wfb_...

The key must include WhatsApp plugin access and this scope:

• Plugin: whatsapp
• Permission: channels:send

The route also accepts existing workforce API-key fallbacks: x-agent-api-key and x-api-key.

{
  "to": "+15551234567",
  "type": "text",
  "text": "Your order is ready for pickup.",
  "integrationId": "9f410fe1-6ad7-40c1-9ed7-8f4a4a87208b",
  "agentId": "13ad2813-4303-4a97-a360-7ddfc2d7eeb6",
  "idempotencyKey": "order-123-ready",
  "metadata": {
    "source": "checkout",
    "orderId": "123"
  }
}

Use type: "template" with an approved WhatsApp template to start or reopen a conversation.

{
  "to": "+15551234567",
  "type": "template",
  "template": {
    "name": "order_ready",
    "language": "en_US",
    "bodyParameters": ["12345"]
  },
  "idempotencyKey": "order-123-ready-template"
}

{
  "success": true,
  "messageId": "wamid.HBgL...",
  "provider": "meta_cloud",
  "usageEventId": "2bd8da04-4046-4f00-8b2c-0ac4f190b809",
  "recipient": "15551234567",
  "status": "sent",
  "error": null
}

WhatsApp does not allow arbitrary business-initiated free-form text. Use an approved template to start a conversation, reopen a closed customer-service window, or send an automated notification before a customer messages the business.

Free-form type: "text" remains available after the customer messages the business number and opens the 24-hour service window.

Use idempotencyKey or the Idempotency-Key header for retryable sends. Zeiko stores successful, failed, and skipped sends in whatsapp_usage_events.

When the same key is received again for the same account, Zeiko returns the stored usage event instead of dispatching a duplicate WhatsApp message.

Zeiko meters inbound and outbound WhatsApp platform activity in whatsapp_usage_events. The default behavior is log-only unless the account has explicit WhatsApp platform allowance enforcement configured.

• WhatsApp API Pro at $25/month
• 100,000 included WhatsApp platform messages per month
• $0.002 per additional Zeiko-metered message
• 3 connected WhatsApp phone numbers
• 1,000 included integration/API calls per month

Meta and WhatsApp Business Account conversation fees are separate in V1. If the customer owns the WABA or provider payment method, those charges remain billed by Meta or the connected provider.

Free-form text inside an open service window:

curl -X POST "https://zeiko.io/api/whatsapp/messages?accountSlug=acme" \
  -H "Authorization: Bearer $ZEIKO_WORKFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-ready" \
  -d '{
    "to": "+15551234567",
    "text": "Your order is ready for pickup.",
    "metadata": {
      "source": "checkout",
      "orderId": "123"
    }
  }'

Approved template for initiating or reopening a conversation:

curl -X POST "https://zeiko.io/api/whatsapp/messages?accountSlug=acme" \
  -H "Authorization: Bearer $ZEIKO_WORKFORCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-123-ready-template" \
  -d '{
    "to": "+15551234567",
    "type": "template",
    "template": {
      "name": "order_ready",
      "language": "en_US",
      "bodyParameters": ["12345"]
    },
    "metadata": {
      "source": "checkout",
      "orderId": "123"
    }
  }'

• Account-level text and template sends only; agent-owned template dispatch is not exposed yet
• No public media-send endpoint yet
• No in-endpoint calculation of Meta/WABA conversation fees
• Usage enforcement is explicit opt-in configuration