Connect Plivo to Zoice: A Step-by-Step Guide to Putting an AI Agent on Your Phone Number

Most teams that buy a phone number for their business never imagined it would one day be answered by an AI agent. With Zoice, the gap between "we own a Plivo number" and "an AI agent answers every call on it, 24/7" is a single guided flow inside the dashboard — no Plivo console configuration, no manually pasted answer URLs, no XML.

This guide walks through the exact onboarding path: importing your Plivo number, what Zoice verifies behind the scenes, assigning an agent, and how the automatic webhook configuration works — including what every status badge means and how to recover when something fails.

What You Need Before You Start

The whole flow takes a few minutes if you have these five things ready:

• Plivo API credentials — your Plivo Auth ID and Auth Token from the Plivo console. You enter them once in Zoice; they are stored encrypted server-side.
• A phone number owned in that Plivo account. Zoice verifies the number actually exists in your account by listing your owned numbers through the Plivo API, and surfaces whether the number is voice-enabled.
• The number in E.164 format — full country code, plus sign, no spaces. For India that looks like +919876543210 (the form placeholder is "+91...").
• A Zoice login with the right role. Importing a number into an organization requires the owner or admin role; the Inbound Calls page itself is gated behind the calls.view permission.
• At least one AI agent created in Zoice. The assignment dialog lists your existing agents — if you have none, it shows "No agents found."

One thing you explicitly do not need: any setup on the Plivo side beyond owning the number. You never create a Plivo Application or configure answer URLs yourself — Zoice does that automatically through the Plivo API when you assign an agent. If your traffic runs on a different carrier, Zoice also supports generic SIP/BYOC trunks — see the SIP and BYOC page — but this guide focuses on the native Plivo path.

Step 1–3: Import the Number

Open the import dialog

Navigate to /dashboard/phone-numbers and click the Import Number button in the top right. A dialog opens titled "Import Phone Number" with the prompt "Select your telephony provider." (The page also supports a deep link with ?import=true, which the Inbound page uses to send you here when you have no numbers yet.)

Select Plivo

The provider picker shows three options: Plivo, Twilio, and Exotel. Plivo is live today; Twilio and Exotel appear with "Coming Soon" badges and cannot be selected yet. Choose Plivo and the dialog switches to the credential form.

Fill the credential form

Three required fields: Plivo Auth ID, Plivo Auth Token (masked as a password field), and Plivo Phone Number. Submit with the Import Number button — the label flips to "Verifying..." and then "Importing..." as the two-phase process runs. Leave any field empty and you get an immediate "Please fill all the fields" toast with no API call made.

Step 4–5: What Zoice Verifies Before Importing

This is where Zoice earns its keep. On submit, three live checks run against the Plivo API before anything touches the database:

• Credential check — Zoice calls Plivo's account endpoint with your Auth ID and Token. A 401 from Plivo surfaces as an "Invalid Credentials" toast.
• Format check — the number must match E.164 (country code, 7–15 digits). Anything else triggers "Invalid Phone Number" with an example of the correct format.
• Ownership check — Zoice lists your account's numbers (first 100) and matches your entry against them, normalizing plus signs, spaces, and dashes. If the number is not in your account, you see "Number Not Found."

On success the UI toasts "Credentials & number verified!" and immediately imports: the backend atomically creates a telephony config (credentials encrypted at rest) and a phone number record. Trying to import the same number twice returns a clean 409 — "Phone number is already added to your account." The number then appears in the Connected Numbers table. Five pieces make this flow work end to end:

Step 6–8: Assign an Agent and Let Zoice Wire the Webhook

Head to /dashboard/inbound. The page splits your numbers into Active Inbound Numbers (agent assigned) and Available Numbers (unassigned, shown with an "Unassigned" badge). A "How It Works" strip summarizes the whole journey: Import Number → Assign Agent → Auto-Configure Webhook → Receive Calls.

Click Assign Agent on your number. The dialog says it plainly: "Select an AI agent to handle incoming calls on this number. The Plivo webhook will be automatically configured." Pick an agent from the dropdown and confirm. Behind the scenes, Zoice saves the assignment and then — in the same request — configures Plivo for you: it creates (or reuses) a Plivo Application named after your number, sets the answer URL to Zoice's inbound handler at /telephony/v1/call/receive/inbound and a matching hangup URL, links that application to your number through Plivo's Numbers API, and stores the application ID on the record.

The Webhook column then tells you exactly where you stand:

Badge	Meaning	Action available
Webhook Active (green)	Plivo is configured; incoming calls route to the assigned agent	None needed — you are live
Webhook Failed (red)	Agent saved, but Plivo-side configuration failed; calls will not reach the agent yet	Retry button (one click)
Pending (yellow)	Webhook not yet configured on Plivo	Configure button (one click)

Retry and Configure call the same endpoint and re-run the full configuration flow. A useful detail: the agent assignment always persists even when the webhook step fails, so recovery is one click — never a re-import. With that mental model, the rollout plan is short:

You're Live — and What Happens on Every Call

Once the badge reads Webhook Active, Plivo POSTs each incoming call to Zoice, which resolves the agent by the dialed number, logs the call as inbound, and answers with your AI voice agent — around the clock, no queue, no IVR maze. After each call, the dashboard gives you an AI-generated summary, sentiment, and structured data extraction, all browsable in call analytics. The same imported numbers can also run outbound campaigns via CSV upload, so one number serves both directions.

Troubleshooting Cheat Sheet

• "Invalid Credentials" — Plivo rejected the Auth ID/Token pair. Re-copy both from the Plivo console.
• "Invalid Phone Number" — formatting issue. Use the full E.164 form: +919876543210.
• "Number Not Found" — the number is not owned by that Plivo account (verification scans the first 100 numbers in the account).
• "Duplicate Number" — the number is already imported on your account; manage it from Connected Numbers instead.
• "Agent assigned but Plivo webhook configuration failed" — click Retry. Note that after a page refresh this state displays as the yellow Pending badge with a Configure button — same fix, same endpoint.
• Retry fails repeatedly — the toast says "Check your Plivo credentials"; the backend reports the Plivo-side reason. Confirm the token has not been rotated in Plivo.
• Callers hear an immediate disconnect — that number is either not provisioned in Zoice or has no agent assigned; Zoice answers Plivo with a hangup instruction and logs the rejection.

Teardown, When You Need It

Clicking Unassign removes the agent and best-effort cleans up the Plivo side — unlinking and deleting the Plivo Application Zoice created. Deleting a number or the whole telephony config requires step-up authentication and disconnects inbound service immediately, which is exactly the friction you want around a destructive action.

Quick FAQ

Do I need to touch the Plivo console at all?

Only to buy the number and copy your Auth ID and Auth Token. Application creation, answer URLs, hangup URLs, and number linking are all handled by Zoice automatically when you assign an agent.

Can I use Twilio or another carrier instead?

Twilio appears in the provider picker with a Coming Soon badge. For other carriers today, Zoice supports bring-your-own-carrier via SIP trunking, linked above.

Can I change the agent on a live number?

Yes — the assigned number shows a Change Agent button that reopens the same dialog. The webhook is reconfigured as part of the change.

What languages can the agent answer in?

Zoice agents support 10+ Indian languages, so the same number can greet callers in the language your customers actually speak.

What does this cost?

Plivo bills you directly for the number and carrier minutes; Zoice pricing for the AI layer is on the pricing page. If you want a guided onboarding, reach out below and we will walk your first number through this flow live.