Skip to main content

WhatsApp Number Selection

info

This documentation explains how the system automatically selects which WhatsApp instance to use when sending outbound messages. Understanding this process will help you optimize your setup and troubleshoot messaging issues.

Overview Video​

Overview​

The WhatsApp Number Selection system determines which WhatsApp instance and phone number to use when sending outbound messages. This system implements a priority-based selection algorithm with comprehensive error handling and fallback mechanisms.

Selection Priority Hierarchy​

The system follows a strict priority order to ensure predictable and logical number selection:

Priority 1: Manual Override (Highest)​

Manual Override Pattern

Use {{ WA#N }} in your message where N is the instance index to force a specific WhatsApp instance number.

When Used: When a message contains a manual override pattern

Example: "This message will go via 2nd instance {{ WA#2 }}"

Behavior:

  • Extracts instance index from message pattern
  • Validates instance exists and is connected
  • Removes pattern from message before sending
warning

The system will throw an error if the specified instance doesn't exist or isn't connected.

Priority 2: Contact Tags​

Contact Tagging

Tag contacts with wa: +1234567890 to always use a specific WhatsApp number for that contact.

When Used: When a contact has a WhatsApp number tag

Example: Contact tagged with wa: +15551234567

Behavior:

  • Searches contact tags for WhatsApp number pattern
  • Finds instance with matching phone number
warning

Error occurs if the tagged number's instance is not connected.

Priority 3: Contact Assigned To​

User Assignment

When a contact is assigned to a user in your CRM, the system will try to use that user's WhatsApp instance for messaging.

When Used: When a contact is assigned to a specific user who has a WhatsApp instance assigned to them

Behavior:

  • Looks up contact's assigned user
  • Finds WhatsApp instance assigned to that user
warning

Error occurs if the assigned user's instance is not connected.

Priority 4: Default Instance​

Best Practice

Always set one instance as "default" for each location to ensure reliable fallback behavior.

When Used: When no specific assignment is found

Behavior:

  • Uses the instance marked as "default" for the location
  • Only considers connected instances

Priority 5: Any Available Instance (Lowest)​

When Used: As final fallback

Behavior:

  • Selects any connected instance with a phone number
danger

If no instances are available at this point, the message will fail with Error 106.

Advanced Configuration Examples​

Example 1: E-commerce Setup​

Instance #1: +1-555-ORDERS (Order confirmations)
- Assigned to: Order Management User
- Usage: Automated order workflows

Instance #2: +1-555-SUPPORT (Default - Customer service)
- Marked as: Default Instance
- Usage: General customer inquiries

Instance #3: +1-555-BILLING (Billing inquiries)
- Contact Tags: VIP customers tagged with "wa: +1-555-BILLING"
- Usage: Payment and billing communications

Example 2: Agency Client Management​

Instance #1: Client A Brand Number
- Manual Override: Workflows use `{{ WA#1 }}` for Client A

Instance #2: Client B Brand Number  
- User Assignment: Client B team members assigned to Instance #2

Instance #3: Agency Main Line (Default)
- Default Instance: Used for all other communications

Best Practices​

Setup Recommendations​

  1. Always Set a Default: Ensure one instance is marked as default for fallback scenarios
  2. Document Your Strategy: Keep a record of which numbers are used for what purposes
  3. Test Your Setup: Send test messages to verify number selection works as expected
  4. Monitor Regularly: Check instance connection status daily

Error Prevention​

  1. Validate Manual Overrides: Ensure {{ WA#N }} patterns reference existing, connected instances
  2. Maintain Contact Tags: Keep wa: tags updated when instances change
  3. Review User Assignments: Regularly verify that assigned users have connected instances
  4. Health Monitoring: Set up alerts for instance disconnections

Troubleshooting Workflow​

  1. Check Error Code: Identify the specific error (101-106)
  2. Verify Instance Status: Confirm which instances are connected
  3. Review Configuration: Check user assignments, tags, and default settings
  4. Test Resolution: Send a test message to verify the fix worked
  5. Document Issues: Keep a log of common problems and solutions

For additional support with number selection issues, contact our team through the WhatsApp button below.

Let's connect