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

# Transfer Tools

> Route active calls to agents, phone numbers, or SIP destinations

export const Screenshot = ({lightSrc, darkSrc, alt, caption, maxWidth = "880px"}) => {
  return <div style={{
    margin: "1rem auto",
    maxWidth,
    width: "100%"
  }}>
      <Frame>
        <img className="block dark:hidden" src={lightSrc} alt={alt} />
        <img className="hidden dark:block" src={darkSrc} alt={alt} />
      </Frame>
      {caption ? <p style={{
    marginTop: "0.5rem",
    fontSize: "0.875rem",
    color: "inherit",
    opacity: 0.8
  }}>
          {caption}
        </p> : null}
    </div>;
};

**Access:** Open your agent editor and go to the **Tools** tab.

<Note>
  Phone number and SIP transfers only work during a real phone call. They cannot be tested in the web simulator — use **Test Agent → Phone call** to test these.
</Note>

***

## Adding a Transfer Tool

<Steps>
  <Step title="Open the Tools tab">
    In your agent editor, go to the **Tools** tab and click **Add** → **Transfer**.
  </Step>

  <Step title="Name the tool">
    Use a clear, descriptive name — your prompt will reference it by exact name.

    **Good:** "Transfer to Billing", "Transfer to On-Call Manager"

    **Poor:** "Transfer 1", "Escalate"
  </Step>

  <Step title="Choose a destination type">
    Select **Agent**, **Phone**, or **SIP** (see [Transfer Destinations](#transfer-destinations) below).
  </Step>

  <Step title="Configure the destination">
    Fill in the destination details for the chosen type.
  </Step>

  <Step title="Save">
    Click **Save**. The transfer tool appears in the tools table and can be referenced in your prompt.
  </Step>
</Steps>

### Using in Your Prompt

Reference the transfer tool by its exact name:

```text theme={null}
When a customer asks to speak with a human:
1. Explain why you're transferring them
2. Ask "Would you like me to transfer you now?"
3. Wait for confirmation
4. Use the 'Transfer to Support' tool
```

***

## Transfer Destinations

<Screenshot lightSrc="/images/operations__transfer-dest-light.png" darkSrc="/images/operations__transfer-dest-dark.png" alt="Transfer destination dialog showing name and description fields, AI Agent and Phone number transfer type options, Select Agent dropdown, Transfer Message field, and Save button" />

| Destination          | Best when                                                                     | Example                                  |
| -------------------- | ----------------------------------------------------------------------------- | ---------------------------------------- |
| **Another AI agent** | You want to stay inside itellicoAI and route to a more specialized agent      | Billing agent, language-specific agent   |
| **Phone number**     | You need to connect to a human or external destination over the phone network | Live support queue, on-call manager      |
| **SIP address**      | You need to route into a PBX, contact center, or SIP-enabled system           | Contact center queue, internal extension |

<AccordionGroup>
  <Accordion title="Agent Transfer" icon="users" defaultOpen>
    Transfer to another AI agent in your itellicoAI account.

    **Configuration:**

    <Steps>
      <Step title="Select transfer type">Choose **Agent**</Step>
      <Step title="Choose destination agent">Select the target agent from the dropdown</Step>

      <Step title="Optional: Hold music and ring tone">
        In Expert mode, configure audio to play while connecting (0–300 seconds each).
      </Step>
    </Steps>

    **Benefits:** The receiving agent can access the prior conversation history. No telephony costs. Works on all call types including web calls.

    <Badge>Expert Mode</Badge>

    **Audio settings:** You can add hold music and a ring tone for agent transfers. For instant AI-to-AI routing, disable both for immediate connection.
  </Accordion>

  <Accordion title="Phone Number Transfer" icon="phone">
    Transfer to an external phone number — mobile, landline, or business number.

    **Configuration:**

    <Steps>
      <Step title="Select transfer type">Choose **Phone**</Step>

      <Step title="Enter phone number">
        Use E.164 format: `+14155551234`

        * Must include country code (`+1` for US/Canada)
        * No spaces, dashes, or parentheses
      </Step>
    </Steps>

    <Warning>
      Phone transfers incur outbound calling costs and **only work during active phone calls**. They do not work in web calls or widget conversations.
    </Warning>
  </Accordion>

  <Accordion title="SIP Address Transfer" icon="network-wired">
    <Badge>Expert Mode</Badge>

    Transfer to a SIP URI for integration with PBX systems and contact centers.

    **Configuration:**

    <Steps>
      <Step title="Prerequisites">
        Ensure a SIP trunk is configured in itellicoAI and the destination endpoint is reachable.
      </Step>

      <Step title="Select transfer type">Choose **SIP**</Step>

      <Step title="Enter SIP address">
        Use a valid SIP URI: `sip:support@pbx.company.com`
      </Step>
    </Steps>

    <Warning>
      SIP transfers **only work during active phone calls**. They cannot be used during web calls or widget conversations.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Multiple Transfer Tools

<AccordionGroup>
  <Accordion title="Fallback chains" icon="arrow-turn-down-right">
    Write fallback logic directly in the prompt:

    ```text theme={null}
    1. Attempt 'Transfer to Technical Support'
    2. If that fails, attempt 'Transfer to General Support'
    3. If all fail, apologize and collect a callback number
    ```
  </Accordion>

  <Accordion title="Conditional routing" icon="code-branch">
    Use variables to route based on customer data:

    ```jinja theme={null}
    {% if contact_account_type == "enterprise" %}
    Route to 'Transfer to Enterprise Support'
    {% else %}
    Route to 'Transfer to General Support'
    {% endif %}
    ```
  </Accordion>

  <Accordion title="Time-based routing" icon="clock">
    ```jinja theme={null}
    {% set current_hour = current_datetime | date('H') | int %}
    {% if current_hour >= 9 and current_hour < 17 %}
    Business hours: use 'Transfer to Support Team'
    {% else %}
    After hours: use 'Transfer to On-Call Support'
    {% endif %}
    ```
  </Accordion>
</AccordionGroup>

***

## Call End

Call ending is configured in **Call Flow**, not in the **Tools** tab.

When **Allow AI to hang up** is enabled, the agent gets a default `end_conversation` capability it can use when the task is complete or the caller says goodbye.

**To enable:** Open **Call Flow** → scroll to **Call End** → turn on **Allow AI to hang up**.

```text theme={null}
Once you've successfully completed their request:
1. Ask "Is there anything else I can help you with?"
2. If they say no, thank them and end the call naturally
```

<Warning>
  The call ends after the agent finishes the closing turn. Make sure your prompt tells the agent to confirm the caller is done before ending.
</Warning>

***

## Best Practices

<AccordionGroup>
  <Accordion title="Always explain before transferring" icon="comment">
    Never transfer without context. Explain who you're connecting them to and why, then confirm.

    **Good:**

    ```
    "I understand you need help with billing. Our billing team can access
    your account details. Would you like me to connect you now?"
    ```

    **Poor:**

    ```
    "Hold please." [immediate transfer]
    ```
  </Accordion>

  <Accordion title="Ask for confirmation before executing" icon="comments">
    Prompt the agent to wait for a yes before transferring to avoid announcing a transfer that happens on the next turn.

    ```
    "I can transfer you to our billing team. Would you like me to do that now?"
    [Wait for response]
    [Execute transfer after confirmation]
    ```
  </Accordion>

  <Accordion title="Gather context first" icon="clipboard">
    Collect a name, account number, and brief issue summary before transferring so the recipient doesn't need to ask again.
  </Accordion>

  <Accordion title="Always define a fallback" icon="triangle-exclamation">
    Every transfer path needs a fallback for when the destination is unavailable.

    ```
    If 'Transfer to Support' fails:
    1. Apologize: "I'm having trouble connecting right now"
    2. Offer a callback: collect number and best time
    3. Confirm: "Expect a call from us within the hour"
    ```
  </Accordion>

  <Accordion title="Use E.164 format for phone numbers" icon="phone">
    * ✅ `+14155551234`
    * ❌ `(415) 555-1234`
    * ❌ `415-555-1234`
    * ❌ `14155551234` (missing +)
  </Accordion>
</AccordionGroup>

***

## Testing

<Note>
  Phone number and SIP transfers require a real phone call to test. Use **Test Agent → Phone call** for these. The web simulator cannot execute telephony transfers.
</Note>

Before going live, verify:

* Transfer executes to the correct destination
* Agent explains the transfer and confirms before executing
* Failure scenarios are handled gracefully (no answer, busy, invalid destination)
* Hold music and ring tone play as expected (agent transfers, Expert mode)
* Conversation timeline shows the transfer event in [Conversations](/manage/conversations/detail)

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Transfer connects but drops immediately" icon="phone-slash">
    * Verify destination agent is active and published
    * Test the destination phone number independently
    * Check SIP trunk configuration and firewall rules
  </Accordion>

  <Accordion title="No audio after transfer" icon="volume-xmark">
    * Verify RTP ports are open (typically 10000–20000)
    * Check NAT configuration on SIP endpoints
    * Ensure compatible codecs are configured (G.711, Opus)
  </Accordion>

  <Accordion title="Phone transfer fails with error" icon="circle-exclamation">
    * Verify E.164 format: `+14155551234`
    * Check account balance and telephony credits
    * Confirm the destination country is supported
  </Accordion>

  <Accordion title="Agent transfer doesn't pass context" icon="message-slash">
    * Verify both agents are in the same itellicoAI account
    * Confirm the transfer is configured as an agent transfer, not phone
    * Check the receiving agent's prompt for context-handling instructions
  </Accordion>

  <Accordion title="Hold music not playing" icon="music-slash">
    * Enable **Play Music** in the transfer settings (Expert mode)
    * Set a non-zero music duration
    * Hold music only applies to agent transfers
  </Accordion>

  <Accordion title="SIP transfer fails to connect" icon="network-wired">
    * Verify SIP URI format: `sip:user@domain.com`
    * Check that the SIP trunk is configured in itellicoAI
    * Review firewall rules for SIP traffic (port 5060/5061)
    * Test the SIP endpoint with a SIP client independently
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Tools Overview" icon="bolt" href="/build/tools/overview">
    See all available tool types
  </Card>

  <Card title="Booking Calendar" icon="calendar" href="/build/tools/booking-calendar">
    Set up appointment scheduling
  </Card>

  <Card title="Custom API Actions" icon="code" href="/build/tools/custom-api-actions">
    Connect to external systems
  </Card>

  <Card title="Phone Testing" icon="phone" href="/test/phone-testing">
    Validate phone and SIP transfer behavior
  </Card>
</CardGroup>