Phone System Integration Guide

By integrating your Audio Agent with a phone system, you can let your voice Agent answer calls directly. Users simply dial a number to have a voice conversation with the Agent.
Scope supported in this release:

Twilio provider · inbound (users call in) · number inbound, ideal for the scenario where "a customer dials a phone number directly and talks to the Agent."
Third-party SIP transfer inbound, ideal for the scenario where you already have a call center or outbound-calling system that, after connecting with a customer, transfers the call to the Agent.

1. Before You Begin (Prerequisites)

An Agent with voice capabilities already enabled
The Agent must already have a voice model, voice timbre, and opening line configured (done in the Agent's voice settings). The opening line played when a call connects is exactly the one configured here.
A Twilio account
- If you go with "public number inbound": you need your own Twilio account with a phone number already purchased.
- If you go with "third-party SIP transfer": you use the shared SIP endpoint provided by the GPTBots platform, with no number of your own required.
Navigation path: DevSpace → your Agent → Integration → Phone System.

2. Binding a Public Phone Number (Most Common)

Ideal for the scenario where "a customer dials a phone number directly and talks to the Agent."

Steps

Service provider: select Twilio · Elastic SIP Trunk.

Fill in your Twilio account information:

Field	What to enter	Description
Account SID	`ACxxxxxxxx…`	Visible on the Twilio console home page
Auth Token	Your Twilio Auth Token	Used to verify the signature of incoming-call requests (X-Twilio-Signature) and prevent spoofed calls
Elastic SIP Trunk domain	`your-trunk.pstn.twilio.com`	Your Trunk domain
Access region	Choose the nearest one (US1 / IE1 / DE1 / AU1 / JP1 / SG1)	Affects call latency
Bound phone number	`+1 415 555 0188`	The number you purchased on Twilio, including the country code
Call direction	Inbound only	Only inbound is supported in this release

Click Save. Once saved successfully, a media / callback URL is automatically generated in the "Webhook" area.
Fill this URL back into Twilio:
Copy the "media / callback URL" → open that number's configuration in the Twilio console → find A CALL COMES IN → set the method to Webhook, paste the URL, and use HTTP POST → save.
Done. Call the number from your phone; you should hear the Agent's opening line and be able to start a conversation.

3. Third-Party SIP System Transfer Inbound (Call Center / PBX)

Ideal for the scenario where "you already have a call center or outbound-calling system that, after connecting with a customer, transfers the call to the Agent." In this case GPTBots itself acts as a SIP endpoint with pure SIP interconnection and no phone number required.

This area is shown only when the provider is Twilio and the platform has enabled a shared SIP Domain.

The information you will see

Agent SIP address (SIP URI) · unique voice entry point
After your third-party system connects with a customer, it transfers the call to this address via SIP REFER transfer, i.e., it reaches the same Agent through "inbound."
SIP username / SIP password (generated automatically after the configuration is saved)
Your PBX / softphone uses this username and password to authenticate against the SIP Domain.

⚠️ The password is shown only once, when it is generated / regenerated; the platform does not store it. Copy it immediately and keep it safe. If you forget it, you can only click "Regenerate" to get a new one.
Supported capabilities: SIP REFER / transfer, custom-header (X-headers) parameter passing, TLS / SRTP.

Usage guide

In your SIP system, place / transfer a call to the Agent SIP address using the SIP username + password above. If you have also bound a public number, both routes reach the same Agent, so no duplicate configuration is needed.

4. Advanced: Passing in End-User Identity for Personalization

By default the Agent identifies the caller by the incoming phone number. If your system already has its own user system, you can carry a user identifier via a custom header (X-headers) on the SIP call:

Header name: X-User-Id
Purpose: The Agent uses it to associate that user's attributes and conversation history, enabling personalized responses (e.g., answering based on membership tier or past orders).

When X-User-Id is not passed, the Agent uses the caller number as the visitor identity. Conversations still work normally; they just do not include profile-based personalization.

5. Placing a Test Call and Viewing Records

Dial the bound number (or transfer from your third-party system) and confirm that:
- You can hear the opening line;
- Multi-turn conversation works normally;
- You can interrupt the content the Agent is currently speaking.
On the Logs / Conversation Records page you can view that call:
- The conversation source is marked as Twilio, with the caller number shown;
- The complete multi-turn Q&A record;
- The runtime sequence (logtree): start node → each conversation turn / tool call → ending voice.

6. Frequently Asked Questions (FAQ)

Q1. No response when dialing the number / it hangs up immediately?

Check whether the "media / callback URL" has been filled back correctly into the Twilio number's A CALL COMES IN, with the method set to HTTP POST.
Check whether the Auth Token is entered correctly—an incorrect value causes incoming-call signature verification to fail and the call to be rejected.
Confirm that the Agent's voice capabilities are fully configured (model / timbre / opening line).

Q2. It says credentials are insufficient / cannot connect?

Confirm that the account has sufficient points: calls are rejected when points run out.
Confirm that the concurrent-call limit is not exceeded: new calls beyond the limit are rejected.

Q3. What if I forget the SIP password?

Click "Regenerate" to get a new password (the old one expires immediately), and update it in sync in your SIP system. The password is shown only once, so save it promptly.

Q4. What is the maximum length of a single call?

A single call lasts at most 60 minutes; beyond that it ends automatically.

Q5. Can the Agent make outbound calls on its own?

This release supports inbound only (users call in); outbound calling is not yet supported.

7. Notes

This release supports only the Twilio provider and the inbound direction.
Call billing is the same as for a regular voice Agent; points are deducted by usage.
After modifying the integration configuration (number, credentials, etc.), you must save again for it to take effect.