Messaging Best Practices

Scope in Dualhook

Because Dualhook uses Webhook Override, message webhooks (messages, statuses, errors) go directly from Meta to your endpoint. These best practices primarily apply to your sending service and your webhook receiver.

Opt-In and Consent

Active user consent is required before business-initiated messaging.

• Collect opt-in through explicit user action.
• Separate opt-ins by message category when possible (marketing, utility, authentication).
• Make opt-out instructions clear and easy to use.
• Store consent evidence (source, timestamp, channel, category) for auditability.

Policy reminder: Business-initiated outreach must use approved templates. Sending without consent increases blocks and reports, which reduces quality and sending limits.

Notification Quality Rules

For notification traffic, messages should be:

• Expected — the recipient understands why they received it.
• Relevant — content is concise, useful, and contextual.
• Timely — sent when it is most useful.

Poor quality signals (blocks/reports) can lead to reduced messaging limits, temporary restrictions, and account suspension risk.

Contact Validation

Validate phone numbers in E.164 format before sending.

Important behavior:

• There is no dedicated API endpoint that confirms WhatsApp validity up front.
• wa_id is returned on successful sends and should be treated as the reliable identifier.
• Handle 131026 (Message Undeliverable) as a likely invalid or unreachable recipient case.

See Contacts & BSUID Mapping for resolution workflows.

Successful Send Response

{
  "messaging_product": "whatsapp",
  "contacts": [
    {
      "input": "12015550123",
      "wa_id": "12015550123"
    }
  ],
  "messages": [
    {
      "id": "wamid.HBgLMTIwMTU1NTAxMjMVAgARGBI..."
    }
  ]
}

Message Sending Reliability

General rules:

• Use POST /<PHONE_NUMBER_ID>/messages for all message types.
• Stop free-form replies if you receive 470 (expired customer service window) and switch to templates.
• Keep text message bodies at <= 4096 characters.
• If preview_url: true, ensure a valid URL is present in the message body.

Media rules:

• Respect supported MIME types, codecs, and file-size limits (see Media Messages).
• For repeated sends, upload once and reuse media_id instead of repeatedly passing hosted URLs (see Upload, Retrieve & Delete Media).

Deep Links

Prefer Universal Links over app deep links for broader cross-device reliability:

https://wa.me/<YOUR_WABA_PHONE_NUMBER>?text=<YOUR_URL_ENCODED_START_MESSAGE>

Callback Handling

Design your webhook receiver as: acknowledge first, process later.

• Return HTTP 200 immediately after authenticity and basic validation.
• Queue and process business logic asynchronously.
• Deduplicate webhook events using wamid + status fields.
• Keep certificate chain valid and DNS publicly resolvable for your callback host.

See Messaging Webhook for payload structure and implementation details.

Latency and Delivery Expectations

Not all delays are API-side. Delivery delays can be caused by recipient device or network conditions (low connectivity, app backgrounding, OS notification delays).

When troubleshooting:

1. Verify webhook ack latency and error rate first.
2. Confirm message status webhooks are arriving (sent, delivered, read).
3. Confirm recipient device, app, and network state if delivery appears delayed.

Chatbot Integrations

During rollout, set a clear fallback message when bot capability is incomplete:

Thanks for contacting us. This automation is currently in rollout and may not answer all requests yet. For urgent help, reply HUMAN.

Chatbot Quality Checklist

Before launch, review:

• Branding — tone and language match your brand.
• Performance — bot intent is clear and answers common queries correctly.
• Consistency — flows are reliable and regularly updated.
• Humanity — bot identifies itself and exposes clear human handoff options.

Policy requirement: If automation cannot resolve an issue, provide a human escalation path (live agent handoff, support phone, support email/web form, or equivalent).

Pre-Launch Checklist

Before scaling sends:

1. Verify category-specific opt-ins are in place.
2. Confirm template quality and status is healthy.
3. Warm up new numbers gradually.
4. Test with internal recipients first (including status webhook flow).
5. Validate retry and idempotency behavior under webhook failure simulation.

For error handling guidance, see Meta API Error Reference. For account health management, see Maintain Account Health.