Introduction
Create an interconnection
There are three types of interconnections :
- SIP
- IAX
- Customized
SIP interconnections
SIP interconnections are used to connect to a SIP provider or to another PBX that is part of your telecom infrastructure.
Global SIP configurations are available with at the following endpoints:
/api/confd/1.1/asterisk/pjsip/global
/api/confd/1.1/asterisk/pjsip/system
Endpoint and trunk configurations are available with at the following endpoints:
/api/confd/1.1/endpoints/sip
: For the SIP configuration of the trunk/api/confd/1.1/endpoints/sip/templates
: Theglobal
template can be used for global settings shared between all SIP endpoints/api/confd/1.1/trunks
: SIP specific trunk configuration
The API documentation can be used for more details on the configuration.
Environment with NAT
There are some configuration steps that are required when connecting to a SIP provider from a NAT environment.
Configuring your transport
The transport needs to be configured with the local network and it's external address and port. This
can be done using the /api/confd/1.1/sip/transports
API.
{
"name": "transport-udp",
"options": [
...,
["local_net", "192.168.0.0/16"],
["local_net", "10.1.1.0/24"],
["external_media_port", "<PUBLIC IP ADDRESS"],
["external_signaling_address", "<PUBLIC IP ADDRESS>"]
]
},
external_signaling_address
: This is your public IP addressexternal_media_address
: This is your public IP addresslocal_net
: Your internal network range
Note that modifying a transport requires an Asterisk restart to be applied
Configuring your Endpoints
Some options should be set on your endpoints for them to work in a NAT environment. The global
SIP
template can be used to apply settings to all SIP endpoints.
-
PUT /api/confd/1.1/endpoints/sip/templates/<SIP template UUID>
{ "uuid": "<UUID>", "label": "global", ..., "endpoint_section_options": [ ..., ["rtp_symmetric", "yes"], ["rewrite_contact", "yes"] ], ... }
SIP Headers
Outgoing calls
There are some use cases where you need to set specific SIP headers on all outgoing calls done using a trunk.
Adding a SIP header can be done using dialplan with the PJSIP_HEADER(add,MY-HEADER)=value
or it
can be done in the endpoint configuration using a set_var
.
Using the endpoint configuration endpoint /endpoints/sip
{
"uuid": "<UUID>",
...,
"endpoint_section_options": [
...,
["set_var", "PJSIP_HEADER(add,<HEADER NAME>)=<HEADER VALUE>"]
],
...
}
Incoming calls
Sometimes it is necessary to match incoming SIP INVITE against a specific header to route the call to the appropriate SIP endpoint.
This is useful in a multi tenant situation where multiple tenants share the same provider.
If your provider sends the X-Dest-User: abc123
header when you receive a call you should add a
match on the trunk SIP endpoint to get those calls routed to this endpoint.
{
"uuid": "<UUID>",
...,
"endpoint_section_options": [
...,
["identify_by", "header,auth_username,username"],
],
"identify_section_options": [
...,
["match_header", "X-Dest-User: abc123"]
],
...
}
Customized interconnections
Customized interconnections are mainly used for interconnections using Local channels:
-
name
: it is the name which will appear in the outcall interconnections list, -
interface
: this is the channel name -
interface_suffix
: a suffix added after the dialed number (in fact the Dial command will dial:<Interface>/<EXTEN><Interface suffix>
-
Context
: currently not relevant
Debug
Interesting Asterisk commands: :
sip show peers
sip show registry
sip set debug on
Caller ID
When setting up an interconnection with the public network or another PBX, it is possible to set a caller ID in different places. Each way to configure a caller ID has it's own use case.
The format for a caller ID is the following "My Name" <9999>
If you don't set the number part of
the caller ID, the dialplan's number will be used instead. This might not be a good option in most
cases.
Outgoing call caller ID
When you create an outgoing call, it's possible to set the internal_caller_id
. When this option is
activated, the caller's caller ID will be forwarded to the trunk. This option is use full when the
other side of the trunk can reach the user with it's caller ID number.
When the caller's caller ID is not usable to the called party, the outgoing call's caller id can be fixed to a given value that is more use full to the outside world. Giving the public number here might be a good idea.
PUT /outcalls/{outcall_id}/extensions/{extension_id} {"caller_id": ""XIVO" <555>"}
A user can also have a forced caller ID for outgoing calls. This can be use full for someone who has
his own public number. This option can be set by user. The outgoing_caller_id
option must be set
to the caller ID. The user can also set his outgoing_caller_id
to anonymous
.
PUT /users/{user_uuid} {"outgoing_caller_id": ""Bob" <555>"}
The order of precedence when setting the caller ID in multiple place is the following.
internal_caller_id
- User's
outgoing_caller_id
- Outgoing call
- Default caller ID