Telephony

Telephony is what connects your Nexus agent to actual phone calls - inbound (a customer calls your number) and outbound (your bot calls a customer). Two different surfaces are involved, and it's easy to conflate them:

• AI Agent → Voice → Telephony in Studio - a test-call panel (browser Web Call + outbound Phone Call) for trying your voice agent. It doesn't connect a telephony provider.
• Extensions → Channels → Twilio Voice - where you actually connect a phone number to your bot for production inbound/outbound calls.

This page covers connecting a real number under Channels. For making test calls without any telephony setup, see Testing.

Step 1: Open the Telephony test panel

In your bot, go to AI Agent → Voice → Telephony.

This tab is a test-call panel, not a provider picker: a Web Call section for browser-based test calls and a Phone Call section for placing an outbound test call to a real number. It's for trying your agent's voice behaviour, not for connecting a telephony provider.

Step 2: Connect a number under Channels

Yellow.ai currently supports Twilio Voice as a connectable telephony channel:

1. Go to Extensions → Channels, find Twilio Voice, and open its configuration.
2. Enter your Twilio Account SID and Auth Token (find both at twilio.com/console) and save.
3. Once connected, the numbers on your Twilio account are listed. Click Connect next to the number you want to wire to this bot.

There's no manual webhook URL to copy or SIP trunk to configure for this - connecting the number wires it up.

If you already have a Twilio number you use elsewhere, use that one. Switching the underlying number later is more disruptive than switching almost any other component.

Best practice: keep your Account SID and Auth Token in a password manager and rotate them per Yellow's security guidelines. Don't paste production credentials into a chat or email.

Step 3: Configure inbound

For incoming calls (your customer dials your number, the bot picks up):

1. Confirm the number shows as connected under Extensions → Channels → Twilio Voice.
2. Make a test call to confirm it lands on your bot.
3. Listen for the welcome message - that's your Welcome message from AI Agent → Profile → Profile Settings speaking through your configured voice.

If the call rings but no audio plays, the most common causes are:

• The number isn't actually connected yet under Channels.
• Missing welcome action - set one in Profile Settings.
• Voice provider misconfigured - verify in Voice settings.

Step 4: Configure outbound

Outbound calls let your bot ring a phone number - for collections, appointment reminders, surveys, sales follow-ups, etc. Production outbound calls go out from the number you connected under Channels.

1. Confirm the caller ID recipients see matches your connected number.
2. Make a test outbound call from the Voice Playground - type a phone number and click Call me. This test path uses Yellow's own test-call infrastructure rather than your connected Twilio number, so it's for validating the conversation itself; verify caller ID and call quality separately on a real production outbound call.

For programmatic outbound (triggering calls from a workflow or external system), Yellow exposes an outbound-call API. Talk to your account team about API access.

Step 5: Test the full path

Before going live:

• Test inbound - call your connected number from a phone, run through the golden path, confirm the bot recognizes you and responds in the configured voice.
• Test outbound - initiate a call from the Voice Playground to your own phone, take the call, confirm.
• Test escalation - trigger a Transfer Call tool. Confirm it forwards to the configured human destination cleanly. See Escalation tools.

Best practices

• Set caller ID thoughtfully. Recipients are more likely to pick up calls from a familiar local number; spam filters punish numbers without consistent usage patterns.
• Verify recording compliance for your region. Some jurisdictions require explicit consent before recording. Configure the Recording action on your Transfer Call tool accordingly. See Escalation tools.
• Don't publish your Twilio Account SID / Auth Token. Treat them like an API key.
• Have a fallback path. If Yellow can't reach the LLM, what does the user hear? A generic apology + a fallback to a human is far better than dead air. Wire the Fallback in Profile Settings to a human-handoff workflow.
• Keep a runbook. When something breaks at 2 a.m. (it will), you want a one-page runbook with: where credentials live, how to disable the bot temporarily, who to call. Don't write this during the incident.

Common pitfalls

Symptom	Likely cause
Calls ring but no audio	Number not connected yet under Channels, or voice provider misconfigured.
Outbound calls fail silently	Twilio account balance or permissions issue on the connected number.
Recipient sees an unfamiliar caller ID	Caller ID doesn't match the connected number, or the number has poor reputation.
Audio is choppy or robotic	Codec or network issue on the call path.

Reference for the rest

• Voice settings - provider, voice, VAD, bot-wide (not per agent).
• Custom Voices - clone a brand voice for your calls.
• Testing - Voice Playground walkthrough.
• Voice as a Channel (cookbook) - foundational voice concepts and architecture.

Continue to: Testing.