The Phone Numbers section connects telephone numbers to AIUNIFY Assistant for inbound and outbound calling.
A connected number can be used to:
AIUNIFY Assistant supports two telephone providers:
This chapter focuses primarily on Twilio numbers, caller ID, and Twilio inbound routing. SIP Trunks and their advanced routing requirements are covered fully in Chapter 6.
The Phone Number record stores the number, a friendly name, provider type, assigned inbound Agent, optional SIP Trunk, optional SIP fallback number, owner, and internal status. Each user can add a particular telephone number only once.
A Phone Number is the actual callable number, such as:
A telephone provider supplies the network connection that allows the number to place or receive calls.
In AIUNIFY Assistant, the supported provider choices are:
Adding a number to AIUNIFY Assistant does not itself purchase the number from Twilio, activate it with a telephone carrier, or prove that it supports voice calling.
The number should already exist and be operational with the selected provider before being added.
A Twilio number uses credentials stored in the user’s AIUNIFY Assistant Settings.
Twilio calling generally requires:
The Assistant customer interface does not contain a Twilio-number purchasing or provisioning workflow. It records a number that the user already controls.
A SIP number connects through a separately configured SIP Trunk and the system’s Asterisk voice engine.
A SIP number requires:
Selecting SIP without choosing a SIP Trunk is rejected by the backend.
The same connected number can potentially perform two different roles.
A customer calls the number, and AIUNIFY Assistant routes the incoming call to its assigned inbound Agent.
An AI Agent uses the number as the originating caller ID when placing a Campaign or test call.
These assignments are related but separate:
Adding an inbound Agent to a number does not automatically make that number the Agent’s outbound caller ID.
Caller ID is the telephone number presented to the recipient during an outbound call.
For AIUNIFY Assistant Campaigns, the outbound number is normally assigned through the selected AI Agent.
The relationship is:
The Campaign does not independently choose a number in the reviewed implementation. It uses the number assigned to its Agent.
After signing in:
The page describes its purpose as managing Twilio and SIP numbers for outbound Campaigns and inbound calls.
The page contains:
The exact information displayed depends on the account’s saved numbers and configuration.
When no numbers have been added, the page displays:
and explains that a Twilio or SIP number must be added to begin making AI voice calls.
The empty state contains an Add Number button.
The page checks whether these AI services have been configured:
When one or more are missing, the page displays:
and explains that those services are required for AI calling.
Select Configure AI Keys to open Settings.
The services perform different parts of the conversation:
A telephone number can be saved before these services are configured, but a complete AI conversation may not operate correctly.
When a Twilio number exists but the Account SID or Auth Token is missing, the page displays:
The warning explains that the Twilio SID and Token must be configured in Settings before Twilio numbers can be used.
Select Configure Now to open Settings.
The configuration check considers Twilio configured only when both the Account SID and Auth Token are present.
The page checks whether credential values are stored. It does not establish that they are correct, active, or authorized.
For example, the page can stop displaying the warning even when:
A test call is the practical next step after saving the credentials.
The Connected Numbers table displays:
The newest connected numbers are returned first.
The Friendly Name is an internal label that helps users identify the purpose of the number.
Examples:
The Friendly Name is not necessarily displayed to the person receiving the call.
The Phone Number column displays the provider-connected number.
For Twilio, store it in international E.164 format:
The number shown here should match the number shown in the provider account.
The Provider column identifies the connection as:
or:
For a SIP number, the table can also display the associated SIP Trunk name.
The Inbound Agent column displays the Agent that will handle calls received through the number.
When an Agent is assigned, its name appears.
When none is assigned, the table displays:
For SIP numbers, an optional fallback number can also appear in this column.
The Test Call button places a basic verification call from the selected connected number.
This is used to confirm:
It is not a complete test of the assigned AI Agent.
The Actions menu contains:
Use Edit to change the number’s name, provider relationship, inbound Agent, and related routing information.
Use Delete only after reviewing Agent and Campaign dependencies.
Confirm that:
To begin:
The dialog explains that it is used to configure a number, choose a provider, and assign an inbound Agent.
For a Twilio number, the form displays:
The SIP Trunk and Fallback Number fields are displayed only when SIP is selected.
The form requires an international-style number commonly called E.164 format.
Recommended:
The accepted value can begin with +, followed by the country code and telephone digits.
The backend permits a maximum of 15 digits after the optional plus sign and requires the first digit to be from 1 through 9.
Lead telephone numbers are normalized by removing punctuation. Phone Number records are handled more strictly.
The Phone Number route removes spaces before validation but does not show equivalent removal of:
Therefore, enter:
rather than:
or:
Include the correct country code.
United States example:
Saved without spaces:
United Kingdom example:
Saudi Arabia example:
Do not rely on AIUNIFY Assistant to infer a missing country code.
Some countries use a domestic leading zero that is not used in international format.
Confirm the provider’s correct international representation before saving the number.
The number in AIUNIFY Assistant should match the form Twilio sends in its inbound To value.
Do not enter an extension in the Phone Number field.
Incorrect:
The field represents a callable provider number, not a contact destination with an extension.
Friendly Name is required.
Use a name that describes the number’s business purpose.
Recommended:
Avoid:
A clear label becomes more important when the account manages several numbers.
Changing the Friendly Name does not:
It changes the label inside AIUNIFY Assistant.
The form contains:
Select the AI Agent that should answer calls made to this number.
Only Agents available to the signed-in account appear in the selection.
The backend also confirms that the selected Agent belongs to the same user before saving the number.
The selection contains:
For a Twilio number, this means an inbound call will not be handled by an AI Agent.
When the Twilio inbound webhook reaches AIUNIFY Assistant and no Agent is assigned, the caller hears a message indicating that no Agent is available, and the call is ended.
The current customer form does not display the Fallback Number field when Twilio is selected.
The fallback field is presented only for SIP numbers.
Therefore, users should not assume that an unassigned Twilio number will automatically forward to another telephone number.
For the reviewed Twilio inbound route:
Before assigning an Agent, confirm:
An outbound sales Agent may not be appropriate for incoming support calls.
A Phone Number record stores one inbound Agent assignment.
To use several specialized Agents, the business can:
The Phone Number form does not provide a multi-Agent queue.
After completing the form:
A successful addition displays:
The same user cannot add the same number twice.
The system responds:
The uniqueness rule is based on:
Another AIUNIFY account could technically store the same number, but a user cannot duplicate it within the same account.
The number is associated with the user who added it.
The Phone Numbers page retrieves only numbers owned by the signed-in user.
A normal user cannot assign another user’s Agent or SIP Trunk to the number.
A newly created Phone Number record receives:
The data model supports:
However, the reviewed customer Phone Numbers page does not display a user-facing status switch.
To enter the credentials:
The settings page states that these keys are required to initiate calls and power the AI Agent.
The Twilio Account SID commonly begins with:
The field displays an example similar to:
Copy the complete value from the intended Twilio account.
Do not use:
unless that is specifically the account intended to own the calling operation.
The Auth Token is a private credential used with the Account SID.
The field is displayed as a password field to reduce accidental exposure.
Do not send the Auth Token through:
The Account SID and Auth Token must come from the same Twilio account or authorized subaccount.
An SID from one account and a Token from another will fail authentication.
After entering the values:
The absence of the warning confirms only that both values are stored.
When the Auth Token is rotated in Twilio:
An old token can cause both outbound initiation and certain inbound call-control functions to fail.
Twilio must know where to send an incoming call for AI processing.
AIUNIFY Assistant displays an inbound voice webhook on the Phone Numbers page.
The page instructs the user to connect Twilio’s incoming-call setting, commonly labeled:
to the displayed AIUNIFY Assistant webhook.
The Phone Numbers page generates the correct webhook from the application’s configured API address.
Use the exact URL displayed under:
It will end with:
Do not manually replace the host with:
The source confirms that AIUNIFY Assistant accepts its voice webhook at the Twilio voice route and uses it to identify and process inbound calls.
In the Twilio number’s voice configuration:
The wording and placement inside Twilio may vary, but the required destination is the webhook displayed in AIUNIFY Assistant.
Use the secure public HTTPS URL shown in the application.
Twilio must be able to reach the URL from the public internet.
Do not use an address available only inside the server or local network.
When Twilio sends an incoming call, AIUNIFY Assistant looks for a Phone Number record matching Twilio’s To value.
This makes consistent E.164 formatting important.
Example:
This is a match.
Potential mismatch:
Although both represent the same telephone number, the exact stored strings may not match the inbound lookup.
For Twilio numbers, retain the leading +.
The connected Phone Number should be the Twilio-owned business number.
Correct:
Do not add the customer’s number as the provider-connected number unless the business actually owns and controls it.
A properly configured inbound call follows this sequence:
AIUNIFY Assistant normalizes the caller’s From number into digits and searches for a Lead owned by the same account.
Example:
When that Lead already exists, the inbound call is associated with the existing record.
When no Lead matches the caller’s normalized telephone number, AIUNIFY Assistant creates one automatically.
The generated Lead name follows a form similar to:
The new Lead receives:
The system can also trigger the account’s leadCreated webhook event.
After the call:
When an inbound Twilio call is detected, AIUNIFY Assistant can trigger the configured:
webhook event.
The event can contain information such as:
This allows an authorized external system to respond to inbound call activity when Webhooks are enabled in Settings.
The inbound call is stored with:
The Call Log can later receive its final status, duration, recording, transcript, and analysis.
The assigned Agent delivers its configured opening message.
Example:
Before activating inbound calling, verify that the opening message is appropriate for a caller who initiated the contact.
An outbound opening message such as:
would be inappropriate for an inbound caller.
Agent messages can use available Lead information.
The Twilio voice handler supports variables such as:
and other Lead custom-field names.
An automatically created inbound Lead may initially have only the generated name and telephone number, so personalization should be designed to handle incomplete caller information gracefully.
When the Agent is not using the custom-voice streaming mode, Twilio’s standard voice process:
The Agent’s selected language is mapped to an appropriate Twilio speech language where supported.
When Custom Voice is enabled, the call is connected to AIUNIFY Assistant’s secure voice-streaming service.
That process can use:
Custom voice requires all related AI infrastructure to be working.
When the inbound configuration references an Agent or Lead that cannot be found, the call can play an error message and end.
Possible causes include:
Reopen the Phone Number and assign an existing Agent.
The Settings page contains:
with the description:
When enabled, AIUNIFY Assistant attempts to start recording an inbound Twilio call.
The reviewed customer interface provides one recording setting for the user’s account.
It does not show a separate recording toggle for each Phone Number.
Changing the setting can therefore affect calls across the account.
A recording may be unavailable when:
Review Call Logs after the call has ended.
Before recording calls, the business must determine whether notification or consent is required.
The system’s ability to record does not remove the business’s responsibility to comply with applicable privacy and recording laws.
The Agent’s opening message may need to disclose that the call is recorded.
Settings contains:
This can automatically end calls after a configured duration.
Separate limits exist for:
The Incoming Timeout controls the maximum duration for inbound sessions when Auto Hangup is enabled.
Example:
An inbound call can be ended after approximately 10 minutes.
For an inbound Twilio call with a limit greater than one minute, the system attempts to play a warning approximately one minute before the call ends:
The conversation is then redirected back into the voice process.
When Auto Hangup is enabled and a limit is set to zero, the Settings interface can display:
A zero-minute limit can cause calls to terminate immediately.
Review these values carefully before testing inbound service.
To use the Twilio number for outbound Campaigns:
The Agent model stores an outboundPhoneNumber relationship to a Phone Number record.
Each Agent stores one outbound Phone Number.
Several Agents may potentially use the same connected number, provided the provider account permits the resulting call volume.
To use different caller IDs:
Before a Twilio Campaign starts, AIUNIFY Assistant verifies that:
When no number is assigned, the Campaign can return:
AIUNIFY Assistant supplies the connected telephone number as the outbound From value.
The name displayed by the recipient’s carrier or mobile device can depend on:
Changing the AIUNIFY Friendly Name does not control the recipient’s caller-ID name.
Do not enter a number that is not owned or authorized by the provider account.
Twilio may reject a call when the From number is not a valid outgoing caller ID for that account.
From Connected Numbers:
The button displays:
while the request is being initiated.
The prompt requests a number such as:
Use the complete destination with country code.
Recommended:
Avoid:
For a Twilio number, the test call plays a short message similar to:
The test uses:
A successful basic test can confirm:
The Phone Numbers page test does not fully verify:
Test those functions separately.
The reviewed Twilio basic-test route does not show the same Lead and Call Log creation workflow as a normal AI Campaign call.
Do not expect every basic provider test to appear as a standard AI Call Log.
After Twilio accepts the call request, the interface displays:
This means Twilio accepted the request. It does not guarantee that the destination answered.
To edit:
A successful edit displays:
The Edit dialog can be used to change:
The backend also supports certain record fields, but the visible customer form determines what normal users can edit directly.
The actual Phone Number field is disabled when editing an existing record.
Therefore, correcting the number generally requires:
This behavior reduces the risk of silently replacing the identity of a connected number.
Changing a number from Twilio to SIP or from SIP to Twilio can alter its routing requirements.
Before changing:
Selecting Twilio clears the SIP Trunk selection in the visible form.
Selecting:
removes the inbound Agent assignment.
For Twilio, callers will not be forwarded through the SIP fallback function. They will receive the no-Agent response and the call will end.
To remove a number:
A successful deletion displays:
Deleting the AIUNIFY Assistant record does not necessarily:
Provider management must be completed separately where required.
The number-deletion route removes the Phone Number record. It does not show an automatic process that clears the number from every Agent.
Before deleting:
Deleting a number still assigned to an Agent can leave that Agent unable to start a Campaign.
Before deletion, also confirm:
Separate numbers can be used for:
Assign each number to an Agent trained for that purpose.
Regional caller IDs can improve familiarity for Leads, but users must follow provider and telecommunications requirements.
Example:
The Agent assigned to each Campaign determines its outbound number.
A business can use:
This can simplify reporting and call-flow management.
Where possible, maintain:
Do not use an active customer service line for repeated development tests when those tests could interfere with real callers.
Check:
The number must follow a pattern similar to:
Remove:
Search the Connected Numbers table for the same value.
Do not create duplicate labels for the same number. Edit the existing record instead.
The inbound Agent selected in the request does not belong to the signed-in account.
Possible causes include:
Refresh the page and select an Agent shown in the current dialog.
Confirm that:
The Test Call route could not find both saved Twilio credentials.
Open Settings and save the Account SID and Auth Token again.
Possible causes include:
Replace the credentials with a confirmed matching pair and test again.
A provider error involving the From number can mean:
Compare the AIUNIFY Phone Number with the exact active number in Twilio.
Check:
A successful request does not guarantee delivery through every carrier.
A basic Test Call verifies Twilio connectivity but not the full AI stack.
Check:
The number exists in Phone Numbers, but it may not be assigned to the Campaign’s Agent.
Open the Agent and select the correct outbound number.
Check:
Check:
This normally means:
Confirm:
Possible causes include:
Review server logs and Call Logs, then contact Support with the call time and number.
Open the number’s Edit dialog and review:
Also confirm that the caller reached the expected telephone number rather than another number owned by the business.
Check:
Search Leads by the caller’s digits and filter for the inbound Tag.
The inbound process matches callers using normalized telephone digits.
Duplicates can occur when:
Standardize Lead telephone data.
Confirm:
Review:
A zero or very low Incoming Timeout can end the call unexpectedly.
Check:
End the call from the provider console when necessary and correct the configuration before further testing.
Treat the Account SID and especially the Auth Token as confidential.
Anyone with valid credentials may be able to use or modify telephone resources within the permissions of that account.
Only authorized administrators should:
Never place a Twilio SID or Auth Token in:
Before using a number for outbound AI calls, confirm:
Do not misrepresent the identity of the caller or use an unauthorized number.
Caller ID should correspond to a number the business owns or is legally authorized to use.
Inbound callers may provide personal or confidential information.
Review:
Use this order:
For the first test:
Confirm:
Confirm:
Confirm:
Confirm:
Confirm:
Confirm:
At the end of this chapter, the user should understand how AIUNIFY Assistant stores and displays Phone Numbers, how Twilio differs from SIP, how to enter a Twilio number in E.164 format, how to configure the Account SID and Auth Token, why adding a number does not purchase or provision it, how to assign an inbound Agent, why Twilio does not use the visible SIP fallback option, how to configure the incoming voice webhook, how inbound callers are matched to or created as Leads, how recordings and Auto Hangup affect inbound calls, how an Agent determines outbound caller ID, how to place a basic test call, how to edit or delete a number safely, and how to troubleshoot common Twilio and inbound-routing problems.