This installment creates two SIP extensions, 7101 and 7102, registers two softphones and checks calls in both directions. A queue agent is a separate configuration task: a registered SIP account alone does not join a call-center queue. The next installment connects the accounts to mod_callcenter agents and tiers.
The examples were checked against the official v1.10.12 vanilla files. They assume an existing FreeSWITCH instance, a running mod_sofia, fs_cli access and reachable clients on a test LAN. This is a configuration example, not a report of a test performed on your server. Customized, managed or dynamic configurations require checking their actual sources.
Locate the directory, domain and Profile
In fs_cli connected to the target instance, run:
version
eval $${conf_dir}
eval $${domain}
sofia status profile internal
Record the version, configuration path, domain and listening details. CONF below means the returned configuration path; replace this explanatory placeholder. Confirm directory/default.xml includes default/*.xml inside the relevant domain's users. Do not edit generated files behind a management platform.
Verify that 7101 and 7102 are unused in both user and routing configuration. The vanilla template already uses 2001 and 2002 for group calling, so they are unsuitable numbers to assume available.
Create the user files
Create CONF/directory/default/7101.xml with the following complete file. Replace the password placeholder with a unique strong password before using it.
<include>
<!-- 用户标识：本例的新分机号码 -->
<user id="7101">
<!-- params是供认证等功能读取的用户参数 -->
<params>
<!-- 改为独立密码，并在软电话填写相同值 -->
<param name="password" value="REPLACE_WITH_UNIQUE_PASSWORD_7101"/>
</params>
<!-- variables提供用户相关的通道变量 -->
<variables>
<!-- 呼叫进入哪个拨号计划context -->
<variable name="user_context" value="default"/>
<!-- 用于账务或统计关联；不会自动生成话单 -->
<variable name="accountcode" value="7101"/>
<!-- 本例呼叫使用的主叫显示名 -->
<variable name="effective_caller_id_name" value="Agent 7101"/>
<!-- 本例呼叫使用的主叫显示号码 -->
<variable name="effective_caller_id_number" value="7101"/>
</variables>
</user>
</include>
The user id identifies an account within a domain; the filename is an organizational convention. Renaming a file does not change its id. password supplies SIP authentication. user_context selects default for this example's authenticated calls. accountcode is an accounting association, not a password or automatic CDR configuration.
The effective caller-ID variables provide this example's caller identity. Later routing or devices can change presentation, and a carrier does not automatically permit arbitrary caller numbers.
Create CONF/directory/default/7102.xml by changing every 7101 reference to 7102 and supplying a different unique password. Keep one include root in each file.
Optional settings from the user template
The minimal accounts are enough for this test. Add optional fields according to the feature you are configuring.
vm-password belongs under params and supplies the voicemail PIN, independently of the SIP password. A mailbox also needs its module and access route. Use your own PIN:
<!-- Add under the user params; replace with your voicemail PIN -->
<param name="vm-password" value="REPLACE_WITH_VOICEMAIL_PIN"/>
toll_allow belongs under variables. Labels such as local, domestic and international only restrict calls when outbound dialplan rules inspect them. An unconditional bridge to a trunk will not enforce the label. For a route that explicitly checks a local permission label:
<!-- Add under user variables; the outbound route must check this label -->
<variable name="toll_allow" value="local"/>
outbound_caller_id_name and outbound_caller_id_number store intended outbound presentation. The vanilla file references global outbound_caller_name and outbound_caller_id values. Applicable outbound routing must use those values for the outgoing leg, and the carrier must permit the chosen number. Internal extension identity and a shared business outbound number can be configured separately.
callgroup supports group-related features, including the matching pickup rules in the vanilla dialplan. Its value matters when a rule consumes it. It does not create a mod_callcenter queue, agent or tier. Add each optional setting together with the feature or route that uses it.
Add a route for the new numbers
The reference local-extension rule matches 1000–1019. New user files alone will not extend it to 7101. Confirm that dialplan/default.xml includes default/*.xml inside the default context, then create CONF/dialplan/default/01_agent_test.xml:
<include>
<!-- 规则名称方便在配置和日志中辨认 -->
<extension name="agent-test-7101-7102">
<!-- 完整匹配7101或7102，括号保留被叫号码 -->
<condition field="destination_number" expression="^(710[12])$">
<!-- 呼叫目标振铃等待上限：本例演示值30秒 -->
<action application="set" data="call_timeout=30"/>
<!-- 成功桥接结束后，结束主叫侧剩余流程 -->
<action application="set" data="hangup_after_bridge=true"/>
<!-- 按当前模板域查找用户，再呼叫其注册地址 -->
<action application="bridge" data="user/$1@$${domain}"/>
</condition>
</extension>
</include>
The extension name labels a rule, not a user account. destination_number is the called number. The anchors require a full match; 710[12] accepts only 7101 or 7102. Parentheses capture that value as $1.
bridge calls the target user. The user endpoint uses directory dial-string configuration to locate contact information. $${domain} expands during preprocessing and must match these users' domain. A multi-domain system needs its own domain-selection design.
The 30-second call_timeout is an example choice, not a universal recommendation. hangup_after_bridge controls processing after a successful bridge ends. Earlier broad rules can intercept the numbers; an 01 filename prefix does not guarantee highest priority across the entire dialplan.
Common routing additions
For a busy or unanswered destination, continue_on_fail can allow actions after a failed bridge. Restrict it to the causes you want to handle. This example requires an actual prompt file at the configured absolute path:
<!-- Before bridge: continue only for these failure causes -->
<action application="set" data="continue_on_fail=USER_BUSY,NO_ANSWER"/>
<!-- Keep the bridge between the setting and failure prompt -->
<action application="bridge" data="user/$1@$${domain}"/>
<!-- Replace with an existing local audio file -->
<action application="playback" data="/absolute/path/unavailable.wav"/>
continue_on_fail handles failure before a successful connection; hangup_after_bridge handles what follows a successful bridge. true permits a wider set of failures to continue. Use actual hangup causes when busy, unanswered and missing-number cases need different treatment.
leg_timeout sets an answer timeout for an individual destination, for example [leg_timeout=15] before that leg's dial string. It has a different scope from call_timeout and becomes useful when ringing multiple destinations.
A call_timeout of 30 seconds concerns waiting for an answer, not a 30-second limit on connected conversation. Early media can affect this timeout. ignore_early_media=true can keep waiting for a final answer, but also changes which pre-answer carrier announcements the caller hears. Adjust this according to the route rather than adding it to every configuration.
set assigns a variable on the current call leg. export can also pass it to a later B-leg. Choose the scope according to the behavior required; later installments apply this to trunks, recording and queues.
Load the XML and check users
For these static user and dialplan additions, run reloadxml in fs_cli. A SIP Profile restart is not required for this task. Check:
reloadxml
user_exists id 7101 YOUR_DOMAIN
user_exists id 7102 YOUR_DOMAIN
Replace YOUR_DOMAIN with the actual value. Both lookups should return true. A false result calls for checking domain, id, includes and XML errors. A successful reload is not proof of registration or a working call.
Fill in two softphone accounts
Use separate clients for 7101 and 7102. Set the SIP username and authentication ID to the respective user id, and the password to that user's actual password. Set the SIP domain to the directory domain. Use the reachable FreeSWITCH listener as the server or proxy address, with its actual port; the vanilla internal profile commonly uses 5060.
This test uses UDP only if the Profile listens on UDP and the network permits it. A display name such as Agent 7101 is not an authentication ID. When domain and server address differ, configure them separately in a client that supports it: one identifies the SIP account, the other locates the server. Complete this test on the LAN; public NAT is outside this installment. For registration timeouts check the server, port and transport. For missing audio check RTP and endpoint audio devices.
Verify registration and calls
Run:
sofia status profile internal reg
Find both accounts registered under the expected domain. Do not rely only on a client's logged-in indicator. Repeated authentication failure calls for checking domain, authentication ID and password. A single 401 may be a normal challenge. For timeouts, check the listener address, port and transport path.
Call 7102 from 7101. Verify ringing, answer, two-way speech and normal hangup, then repeat in the other direction. If registration works without ringing, inspect context and routing. If a call connects with one-way audio, investigate RTP, endpoint audio and network handling rather than repeatedly changing credentials.
Common points of confusion
If user_exists returns false, check domain, id and parent includes. Read XML errors near reloadxml, fix the named file and repeat the lookup before registering a client.
If dialing reaches another feature, inspect existing number rules. The vanilla 2001 and 2002 routes are group calls; this test uses 7101 and 7102. Earlier matches still matter more than a small filename prefix.
If both softphones use 7101, they register as the same user and incoming behavior depends on multiple-registration settings. Use distinct accounts for this test.
A 30-second answer wait is separate from a connected-call duration limit. Connected-call limits require additional timed hangup logic.
For rollback, unregister and disable the test accounts in the clients, confirm that no test calls remain, remove the two added user files and the added route, then run reloadxml. Removing files does not terminate existing registrations or calls. Unregister the two clients and let test calls finish before removing their files.
The next installment adds agents, a queue and tiers in mod_callcenter, explaining contact, status and dispatch configuration.
Sources
FreeSWITCH configuration reference
FreeSWITCH configuration reference
FreeSWITCH configuration reference
FreeSWITCH configuration reference