> ## Documentation Index
> Fetch the complete documentation index at: https://help.messagesync.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Number Selection

> The shared, priority-based algorithm that decides which number an outbound message is sent from - common to WhatsApp, iMessage, and SMS - and the tag and override syntax for each channel.

<Info>
  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.
</Info>

## Selection Priority Hierarchy

The system evaluates these rules in order and uses the first one that resolves to a connected instance:

| Priority    | Rule                 | How it's triggered                                                                      |
| ----------- | -------------------- | --------------------------------------------------------------------------------------- |
| 1 (highest) | **Manual Override**  | The message contains an override pattern (e.g. `{ WA#N }`, `{IM#N}`)                    |
| 2           | **Temporary Switch** | The message contains a temporary-switch pattern (e.g. `{TEMP-IM#N}`) - one message only |
| 3           | **Contact Tags**     | The contact is tagged with a number (e.g. `wa:`, `im:`, `sms:`)                         |
| 4           | **User Assignment**  | The contact is assigned to a user who has an instance assigned to them                  |
| 5           | **Default Instance** | A location default is configured                                                        |
| 6 (lowest)  | **Any Available**    | Falls back to any connected instance                                                    |

<Note>
  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](/multiple-instances/number-selection-errors).
</Note>

## 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.

| Capability                     | WhatsApp          | iMessage          | SMS                |
| ------------------------------ | ----------------- | ----------------- | ------------------ |
| Manual override                | `{ WA#N }`        | `{IM#N}`          | -                  |
| Temporary switch (one message) | -                 | `{TEMP-IM#N}`     | -                  |
| Contact tag                    | `wa: +1234567890` | `im: +1234567890` | `sms: +1234567890` |

<Tip>
  Override and temporary-switch patterns are stripped from the message body before it's delivered, so the recipient never sees them.
</Tip>

## Priority Rules in Detail

### 1. Manual Override

<Check>
  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.
</Check>

* **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.

<Warning>
  The system raises an error if the specified instance doesn't exist or isn't connected.
</Warning>

### 2. Temporary Switch (iMessage)

<Check>
  Use `{TEMP-IM#N}` to send a single message from a different account without permanently changing the contact's assigned account.
</Check>

* **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

<Check>
  Tag a contact with `wa: +1234567890` (or `im:` / `sms:`) to always use a specific number for that contact.
</Check>

* **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.

<Warning>
  An error occurs if the tagged number's instance is not connected.
</Warning>

### 4. User Assignment

<Check>
  When a contact is assigned to a user in your CRM, the system uses that user's instance for the channel being sent on.
</Check>

* **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.

<Warning>
  An error occurs if the assigned user's instance is not connected.
</Warning>

### 5. Default Instance

<Check>
  Always set one instance as the "default" for each location to ensure reliable fallback behavior.
</Check>

* **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.

<Warning>
  If no connected instance is available at this point, the message fails (WhatsApp returns Error 106). See [Number Selection Errors](/multiple-instances/number-selection-errors).
</Warning>

## Advanced Configuration Examples

### Example 1: E-commerce Setup

```text theme={null}
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

```text theme={null}
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

<Steps>
  <Step title="Always set a default">
    Ensure one instance is marked as default for fallback scenarios.
  </Step>

  <Step title="Document your strategy">
    Keep a record of which numbers are used for what purposes.
  </Step>

  <Step title="Test your setup">
    Send test messages to verify number selection works as expected.
  </Step>

  <Step title="Monitor regularly">
    Check instance connection status daily.
  </Step>
</Steps>

### Error Prevention

<Steps>
  <Step title="Validate manual overrides">
    Ensure `{ WA#N }` / `{IM#N}` patterns reference existing, connected instances.
  </Step>

  <Step title="Maintain contact tags">
    Keep `wa:`, `im:`, and `sms:` tags updated when instances change.
  </Step>

  <Step title="Review user assignments">
    Regularly verify that assigned users have connected instances.
  </Step>

  <Step title="Health monitoring">
    Set up alerts for instance disconnections.
  </Step>
</Steps>

### Troubleshooting Workflow

<Steps>
  <Step title="Check the error code">
    Identify the specific error (101-106).
  </Step>

  <Step title="Verify instance status">
    Confirm which instances are connected.
  </Step>

  <Step title="Review configuration">
    Check user assignments, tags, and default settings.
  </Step>

  <Step title="Test the resolution">
    Send a test message to verify the fix worked.
  </Step>

  <Step title="Document issues">
    Keep a log of common problems and solutions.
  </Step>
</Steps>

## What's Next?

* [**Number Selection Errors**](/multiple-instances/number-selection-errors): Error codes 101-106 and how to resolve them
* [**Multiple Instances Overview**](/multiple-instances/overview): Use cases, benefits, and setup
* [**Full Setup Guide**](/getting-started/full-setup): Connect instances and configure assignments

***

## Support[​](#support "Direct link to Support")

If you need help with the setup or onboarding:

* Email: [**support@messagesync.ai**](mailto:support@messagesync.ai)