Skip to main content

WhatsApp Integration for Recipient Notifications

Ioana Nicolae
Updated

In this article, you will learn how to integrate and configure WhatsApp Business to send automated delivery notifications to your recipients.

WhatsApp can be used as an alternative to SMS for delivery notifications, providing a richer messaging experience. This integration allows you to send delivery updates, ETAs, and tracking information via WhatsApp while automatically falling back to SMS if needed.

Overview 

  1. Supported features and limitations
  2. WhatsApp Business Account setup
  3. Connecting your WhatsApp Business Account
  4. Creating message templates
  5. Configuring notifications
  6. Setting up SMS fallback
  7. Monitoring notifications
  8. Best practices

1. Supported Features and Limitations

What's Supported

  • Secure WhatsApp Business Account Connection: Connect your WhatsApp Business Account to Urbantz securely, allowing Urbantz to send messages on behalf of your business using your phone number
  • Recipient Notifications: Send delivery updates, ETAs, and tracking information via WhatsApp
  • Multi-language Support: Create templates in multiple languages to reach recipients in their preferred language
  • SMS Fallback: Automatically fall back to SMS if WhatsApp delivery fails

Current Limitations

❗ Recipient Notifications Only: WhatsApp integration is currently limited to recipient notifications. Platform administrator notifications (such as alerts to dispatchers or internal staff) cannot be sent via WhatsApp and should continue using other channels like SMS or email.

❗ No Two-way Communication: Recipients can reply to WhatsApp messages, but these responses won't currently be displayed or managed in Urbantz. Since Urbantz controls the WhatsApp number via API, you cannot access replies through the WhatsApp app either.

2. WhatsApp Business Account Setup

Creating Your Account

To use WhatsApp with Urbantz, you must first create a WhatsApp Business Account. Please follow Meta's official documentation:

Important Requirements and Limitations

Before connecting WhatsApp to Urbantz, be aware of these important constraints:

Message Templates and Conversation Windows

  • Initial Messages: To notify a recipient, you must use a template that has been approved by Meta
  • 24-Hour Window: If a recipient responds to your message, you have a 24-hour window to send free-form messages or geolocation requests
  • Window Renewal: Each time the recipient sends a message, the 24-hour window resets
  • After 24 Hours: You must use approved templates again to re-initiate the conversation

Phone Number Limitations

❗ Exclusive API Access: Once connected to WhatsApp Business API, the phone number can ONLY be used for automated messaging through the API. You cannot use this number with WhatsApp mobile or web apps.

❗ Platform Lock: Each phone number can only be connected to ONE messaging platform (Urbantz in this case).

✅ Other Uses OK: The number can still receive regular SMS and voice calls.

Pricing

Pricing rules are explained in detail here: WhatsApp Pricing Documentation

ℹ️ Note: When Urbantz sends a message, we immediately receive the pricing model associated with it, allowing for real-time price estimation of WhatsApp messaging on your platform.

3. Connecting Your WhatsApp Business Account

Once WhatsApp has been enabled for your platform, you can connect your WhatsApp Business Account:

  1. From your platform, go to Administration > Platform > Integrations
  2. Select WhatsApp integration
  3. Click on the "Connect to Facebook" button
  4. Follow the OAuth flow to authorize Urbantz to access your WhatsApp Business Account
  5. Select the WhatsApp Business Account and phone number to use
  6. Complete the connection process

Verify Your Connection

Once successfully connected, your WhatsApp Business Account information will be displayed, along with the connected phone number. This is a one-time setup - your platform will remain connected to this WhatsApp Business Account. You can disconnect and reconnect to a different account if needed.

Testing Your Integration

To test your WhatsApp integration, you can send test messages to any phone number:

  • Requirement: You must have a template named urbantz_test created in your WhatsApp Business Account
  • Test Button: Use the test button in the integration page to send test messages
  • Verify: Check if the message is sent and received correctly on the target phone

ℹ️ You will notice that on the Integration page (Administration > Platform > Integration > WhatsApp), you have the possibility to test WhatsApp notifications. Click on "Send Test Message" and enter your phone number, then click on "Send".

4. Creating Message Templates

Template Creation in Meta Business Suite

All WhatsApp messages sent by Urbantz must use pre-approved templates created in your WhatsApp Business Account.

For detailed instructions on creating message templates, refer to:

Key Points for Template Creation

  1. Access Meta Business Suite > WhatsApp Manager > Message Templates
  2. Create templates with meaningful names (e.g., delivery_notification)
  3. Select the "Utility" category for transactional messages (cheaper than marketing)
  4. Use only named variables with clear names ({{recipient_name}}, {{parcel_number}}, etc.) for dynamic content
    • (later we will link this variables names to element in Urbantz)
  5. Submit for approval (up to 48-hour review process)

Multi-language Template Requirements

Critical for Urbantz integration: When creating templates in multiple languages:

❗ Same Template Name: All language versions must have the exact same name

✅ Different Language Setting: Set the language field for each version

✅ Different Content: Customize the text for each language

Example:

  • Template Name: delivery_notification (Language: English)
  • Template Name: delivery_notification (Language: French)
  • Template Name: delivery_notification (Language: Spanish)

Why this matters: Urbantz uses the template name to find all language versions and automatically sends the message in the recipient's preferred language. If template names differ, the multi-language functionality won't work.

5. Configuring Notifications in Urbantz

Once your templates are approved, you can configure automatic notifications:

Step 1: Create a New Configuration

  1. From your platform, go to Administration > Messaging > Configurations
  2. Create a new configuration:
    • Name: e.g., "WhatsApp Delivery Notifications."
    • Trigger: Select the trigger event type (e.g., "Notify the consumer when the driver has started his round")
    • Rules: Configure extra sending rules and conditions
    • Delivery Mode: WhatsApp

Step 2: Configure Content

  1. Select the Content tab
  2. Choose the approved template (you must have set up this template in your WhatsApp Business Account for it to appear in the drop-down menu)
  3. Select a default language
  4. Map template variables to Urbantz fields (e.g., map {{1}} to recipient name, {{2}} to delivery date, etc.)

  5. Click Save

You can customize the content of your notifications in different languages and add automatic information called "variables" (delivery day, time window, customer name, link to the tracking page, etc.).

For all notifications, you need to specify the flow, the sender (client), as well as the task type (delivery/pick-up/service). This will define who receives a notification.

ℹ️ For more information about notification triggers and setup, please see the article: SMS and e-mail notifications - set up, types and triggers [2]

6. Setting Up SMS Fallback (Optional)

WhatsApp messages may fail if the recipient doesn't have WhatsApp installed. You can configure automatic fallback to SMS or Email.

Creating a Fallback Notification

  1. Create a Fallback Notification:
    • Click on the "+" sign to add another notification
    • Create a new notification with the SAME trigger type as your WhatsApp notification
    • Select SMS or Email as the delivery mode
  2. Adapt Your Content:
    • Create content adapted to SMS and email format constraints
  3. Configure Notification Order (CRITICAL):
    • The notification list order on the left side determines priority
    • WhatsApp notification MUST be ABOVE the SMS notification
    • Urbantz tries notifications in order: first WhatsApp, then SMS if WhatsApp fails
    • Use drag-and-drop to reorder notifications if needed
    • Always click Save after reordering
CleanShot 2025-09-09 at 14.00.04.gif

How Fallback Works

When a recipient notification is triggered:

  1. Urbantz first attempts to send via WhatsApp
  2. If WhatsApp fails because the recipient doesn't have WhatsApp installed, the fallback is triggered
    • Current limitation: Fallback currently only activates for "recipient has no WhatsApp" errors
    • Future enhancement: Additional error types may trigger fallback in future updates
  3. Urbantz automatically tries the next notification in the list (SMS/Email)
  4. The recipient receives the message through the first successful channel

7. Monitoring Notifications

You can monitor WhatsApp notifications in the same way as other types of notifications.

Platform-level Monitoring

From your platform, go to: Administration > System Monitor, and select the Notifications Tab

Task-level Monitoring

  1. From your platform, open the Tasks item in the menu
  2. Select any task and open the Notifications Tab
  3. From there, you can check the history of notification attempts related to the task (successful or failed ones) and get more information about the notification delivery process for each attempt

From the different monitoring tools, you can check if a failed WhatsApp delivery is followed by an SMS attempt.

8. Best Practices

Template Categories and Pricing

When creating WhatsApp templates in your WhatsApp Business account, you must select a category: Marketing, Utility, or Authentication.

Category Selection Guidelines

For delivery notifications, always select "Utility" because:

  • Utility templates are significantly cheaper than marketing templates
  • Delivery updates are transactional, not promotional
  • Delivery notifications fit within the scope of utility messages

Category Review by Meta

⚠️ Meta reviews and may reclassify your templates:

  • Even if you select "Utility", Meta may reclassify it as "Marketing."
  • This happens if your template appears promotional rather than informational

Spam Prevention

❗ Sending the same marketing template repeatedly will trigger Meta's spam detection

❗ Messages may be blocked after very few repeated marketing sends

✅ Utility templates have more lenient limits for transactional use

FAQ

Q: Can I use WhatsApp for internal notifications to dispatchers?

A: No, WhatsApp integration is currently limited to recipient notifications only. Internal notifications should continue using SMS or email.

Q: Can I see recipient replies to WhatsApp messages?

A: No, two-way communication is not supported in the first version. Replies are not displayed in Urbantz, and you cannot access them through the WhatsApp app either since the number is controlled via API.

Q: What happens if my WhatsApp message fails?

A: If you've configured SMS fallback and the failure is due to the recipient not having WhatsApp, Urbantz will automatically send an SMS instead.

Q: How do I know which language version of my template will be sent?

A: Urbantz automatically selects the template language based on the recipient's preferred language. Make sure all language versions have the same template name for this to work correctly.

Q: Can I use the same phone number for both the WhatsApp API and the WhatsApp mobile app?

A: No, once a phone number is connected to the WhatsApp Business API, it can only be used for API messaging. You cannot use it with WhatsApp mobile or web apps.

 


 

Comments

0 comments

Please sign in to leave a comment.