Skip to main content
Number selection works the same way for every channel. When you send an outbound message, the integration walks a fixed priority hierarchy and picks the first instance that matches. Only the tag and override syntax changes between WhatsApp, iMessage, and SMS - the decision logic does not.

​
Selection Priority Hierarchy

The system evaluates these rules in order and uses the first one that resolves to a connected instance:
PriorityRuleHow it’s triggered
1 (highest)Manual OverrideThe message contains an override pattern (e.g. { WA#N }, {IM#N})
2Temporary SwitchThe message contains a temporary-switch pattern (e.g. {TEMP-IM#N}) - one message only
3Contact TagsThe contact is tagged with a number (e.g. wa:, im:, sms:)
4User AssignmentThe contact is assigned to a user who has an instance assigned to them
5Default InstanceA location default is configured
6 (lowest)Any AvailableFalls back to any connected instance
In every case the system only considers connected instances. If the rule resolves to a disconnected instance, it raises an error rather than silently falling through - see Number Selection Errors.

​
Per-Channel Syntax Reference

The patterns below are interchangeable in concept - pick the row for the channel you’re sending on. N is the instance index; +1234567890 is the target number.
CapabilityWhatsAppiMessageSMS
Manual override{ WA#N }{IM#N}-
Temporary switch (one message)-{TEMP-IM#N}-
Contact tagwa: +1234567890im: +1234567890sms: +1234567890
Override and temporary-switch patterns are stripped from the message body before it’s delivered, so the recipient never sees them.

​
Priority Rules in Detail

​
1. Manual Override

Add the override pattern for your channel anywhere in the message - { WA#N } for WhatsApp or {IM#N} for iMessage - where N is the instance index, to force a specific instance.
  • When used: The message contains a manual override pattern.
  • Example: "This message will go via the 2nd instance { WA#2 }"
  • Behavior:
    • Extracts the instance index from the pattern.
    • Validates that the instance exists and is connected.
    • Removes the pattern from the message before sending.
The system raises an error if the specified instance doesn’t exist or isn’t connected.

​
2. Temporary Switch (iMessage)

Use {TEMP-IM#N} to send a single message from a different account without permanently changing the contact’s assigned account.
  • When used: You want to send one message from a different number without changing the contact’s normal account assignment.
  • Example: "Quick update from our support line {TEMP-IM#3}"
  • Behavior:
    • Temporarily routes the message through the specified account.
    • Does not change the contact’s default account assignment.
    • Removes the pattern from the message before sending.
    • Future messages to this contact continue using their normal account.

​
3. Contact Tags

Tag a contact with wa: +1234567890 (or im: / sms:) to always use a specific number for that contact.
  • When used: The contact has a number tag for the channel.
  • Example: Contact tagged with wa: +15551234567
  • Behavior:
    1. The system scans the contact’s tags for the channel’s number pattern (wa:, im:, or sms:).
    2. It finds the connected instance whose phone number matches the tagged number.
    3. If a match is found, that instance is used for the message.
An error occurs if the tagged number’s instance is not connected.

​
4. User Assignment

When a contact is assigned to a user in your CRM, the system uses that user’s instance for the channel being sent on.
  • When used: The contact is assigned to a specific user who has an instance assigned to them.
  • Behavior:
    1. The system looks up the user the contact is assigned to in your CRM.
    2. It finds the instance assigned to that user for the channel being sent on.
    3. If that instance is connected, it’s used for the message.
An error occurs if the assigned user’s instance is not connected.

​
5. Default Instance

Always set one instance as the “default” for each location to ensure reliable fallback behavior.
  • When used: No specific override, tag, or user assignment resolves.
  • Behavior:
    • Uses the instance marked as “default” for the location.
    • Only considers connected instances.

​
6. Any Available Instance

  • When used: As the final fallback.
  • Behavior:
    • Selects any connected instance with a phone number.
If no connected instance is available at this point, the message fails (WhatsApp returns Error 106). See Number Selection Errors.

​
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 } / {IM#N} patterns reference existing, connected instances.
2

Maintain contact tags

Keep wa:, im:, and sms: 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 the 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 the resolution

Send a test message to verify the fix worked.
5

Document issues

Keep a log of common problems and solutions.

​
What’s Next?

​
Support​

If you need help with the setup or onboarding: