Best Practices for WhatsApp API via OAuth 2.0

This article highlights recommended best practices for sending WhatsApp messages using the OAuth 2.0–based API.

Phone Number Format

All phone numbers must be in E.164 format:

• Correct: +905551234567

• Incorrect: 05551234567, 5551234567, +90 555 123 45 67

Template Usage

• Templates must be created and approved in the Meta Business Manager before they can be used.

• Template names are case-sensitive and must match exactly.

• Language codes must comply with the ISO 639-1 standard (e.g., tr, en, ar).

Message Keys

• The key value returned for each message is unique and is used in webhook callbacks.

• It is highly recommended to store these keys and use them to match and track webhook events.

Media Upload Limits

WhatsApp Business API media upload limits and supported formats:

• Image: Maximum 5MB. Supported formats: JPG, JPEG, PNG.

• Video: Maximum 16MB. Supported formats: MP4, 3GPP.

  Videos should include a video file. Video URLs are not supported. Refer to Meta’s guide for further details on supported media types.

• Document: Maximum 100MB. Supported formats: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX.

• Audio: Maximum 16MB. Supported formats: AAC, M4A, AMR, MP3, OGG.

Conversational vs. Transactional

• Transactional: Used for template messages. These are not subject to the 24-hour customer service window rule.

• Conversational: Used for non-template messages. These can only be sent if the user has messaged the business within the last 24 hours.

Error Handling

• All error responses are returned in a standard format: {"message": "...", "error": {"message": "...", "code": "..."}}

• You can categorize issues and take appropriate actions using the specific error codes.

• A retry mechanism is recommended for 5xx (server-side) errors.

Maintenance Mode

• When the system is in maintenance mode, all endpoints will return a 503 Service Unavailable error.

• Maintenance mode does not affect incoming webhook callbacks.