Responsible Messaging

Send Message Example

Every send request should include message_purpose.

POST /api/send-message

Headers:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Body:
{
  "instance_id": "inst_12345",
  "phone": "+9665XXXXXXX",
  "message": "Your order #2041 has been shipped.",
  "message_purpose": "transactional"
}
Response:
{
  "success": true,
  "status": "sent",
  "message_id": "string",
  "log_id": 123
}

Plan Limits

Each plan includes daily and monthly fair-use limits. Limits protect gateway reliability and prevent misuse.

Error Responses

Responsible messaging and limit failures use the same JSON shape across API-style responses.

{
  "success": false,
  "error": "error_code",
  "message": "Human readable explanation.",
  "details": {
    "action": "block",
    "risk_score": 90,
    "limit": 100,
    "used": 100
  }
}

message_purpose_required

{
    "success": false,
    "error": "message_purpose_required",
    "message": "message_purpose is required. Allowed values are transactional, operational, support, internal_team, and authentication.",
    "details": {
        "action": "block",
        "risk_score": 0
    }
}

message_purpose_not_allowed

{
    "success": false,
    "error": "message_purpose_not_allowed",
    "message": "WhatsApp Gateway does not support marketing, cold outreach, political, or bulk campaign messaging.",
    "details": {
        "action": "block",
        "risk_score": 100
    }
}

daily_message_limit_exceeded

{
    "success": false,
    "error": "daily_message_limit_exceeded",
    "message": "Your daily transactional message limit has been reached. Please try again tomorrow or request a higher reviewed limit.",
    "details": {
        "action": "block",
        "risk_score": 90,
        "limit": 100,
        "used": 100
    }
}

monthly_message_limit_exceeded

{
    "success": false,
    "error": "monthly_message_limit_exceeded",
    "message": "Your monthly fair-use message limit has been reached. Please contact support for a reviewed higher limit.",
    "details": {
        "action": "block",
        "risk_score": 90,
        "limit": 2000,
        "used": 2000
    }
}

recipient_suppressed

{
    "success": false,
    "error": "recipient_suppressed",
    "message": "This recipient has opted out or has been blocked from non-essential messages.",
    "details": {
        "action": "block",
        "risk_score": 100
    }
}

sending_throttled

{
    "success": false,
    "error": "sending_throttled",
    "message": "Sending speed has been temporarily limited to protect gateway reliability and prevent bulk messaging.",
    "details": {
        "action": "throttle",
        "risk_score": 65
    }
}

instance_paused_for_review

{
    "success": false,
    "error": "instance_paused_for_review",
    "message": "This instance has been paused for responsible messaging review.",
    "details": {
        "action": "pause_instance",
        "risk_score": 100
    }
}

policy_violation

{
    "success": false,
    "error": "policy_violation",
    "message": "This message appears to violate WhatsApp Gateway responsible messaging rules. Bulk marketing, spam, and cold outreach are not allowed.",
    "details": {
        "action": "block",
        "risk_score": 90
    }
}

Opt-Out Webhook Event

If an inbound opt-out message is detected, your webhook receiver may see a suppression event like this.

{
  "event": "recipient.opted_out",
  "instance_id": "demo-support-line",
  "instance_name": "Demo Support Line",
  "from": "+9665XXXXXXX",
  "reason": "recipient_requested_stop",
  "message_text": "STOP",
  "timestamp": "2026-05-08T10:00:00Z"
}

Best Practices

• Send messages only to expected recipients.
• Keep messages transactional and relevant.
• Avoid repeated identical content.
• Avoid suspicious or shortened links.
• Respect opt-outs.
• Monitor failed delivery rates.
• Use official Meta/BSP channels where approved marketing is required.