Link a Private Branch Exchange (PBX) to Alexa Smart Properties

The Alexa Smart Properties (ASP) Private Branch Exchange (PBX) feature allows you to link in-room Alexa-enabled devices to a PBX system to enable PBX calling between ASP contacts. With this feature occupants in the room can use calling services through the PBX from their in-room device. For example, an occupant in a room can request to call a specific ASP contact, such as "Alexa, call front desk.". Or, the occupant can ask Alexa to dial an extension to reach another room, such as "Alexa, call 1116." Additionally, linking the PBX system enables occupants to receive inbound calls to the Alexa-enabled device in their room with the same dialing pattern the property already employs. The ASP service connects the call to the property PBX by using a Session Initiation Protocol (SIP) trunk connection through TLS.

The following instructions provide the steps to configure ASP with your property PBX system to enable PBX calling between Alexa-enabled devices in rooms on your property.

Prerequisites

Before you start, make sure that you have the following items:

PBX system requirements

To link your SIP-based PBX system with ASP, your PBX system must meet the following requirements:

  • Your PBX must have access to the internet.

  • Your PBX must have a public static IP address assigned to the network that you use to reach your PBX.

  • Your PBX must support signaling over Transport Layer Security (TLS) v1.2 and media over Secure Real-time Transport Protocol (SRTP).

  • Dedicate a Transmission Control Protocol (TCP) port for SIP signaling and a range of ports for media. You can use any port for signaling, as long as the port is the same as the port that you provide in the Create a SIP trunk request. All signaling and media ports must be accessible by the Amazon infrastructure.

  • Optionally, install a Secure Sockets Layer (SSL) certificate on the PBX. The certificate doesn't need to be a public certificate issued from a public certificate authority. A self-signed certificate is acceptable.

  • To use TLS you must either have a Common Name (CN) through your Domain Name System (DNS) that routes to your PBX, or one of the values in a Subject Alternative Name (SAN) must route to your PBX.

Steps to link your PBX system with ASP

To link your PBX system to Alexa-enabled devices in rooms on your property, complete the following steps:

  1. Create a security profile.
  2. Get an access token for PBX APIs.
  3. Enable the PBX communication skill.
  4. Create a SIP trunk.
  5. Configure the SIP trunk in your PBX system.
  6. Map a PBX extension to a room.
  7. Test the PBX integration.

Step 1: Create a security profile

You must have a security profile with Login with Amazon (LWA). To create a security profile, complete the following steps.

To create a security profile

  1. In the Login with Amazon console, sign in with your Amazon developer account, and then click Create a New Security Profile.

  2. Enter your Security Profile Name, Security Profile Description, and Consent Privacy Notice URL.
    For details about security profiles, see Security Profile.

  3. Click Save.
    After you save the security profile, Amazon issues a client ID and a client secret for your profile.

  4. Save your client ID and client secret in a secure place.
    You need these values in Step 2.

  5. To use Login with Amazon with a website, take the following additional steps in the Login with Amazon console:

    1. To the right of your security profile name, under Manage, click the gear icon.
    2. Click the Web Settings tab.
    3. At the bottom, click Edit.
    4. Under Allowed Return URLs, register a callback URL.
    5. Click Save.

Step 2: Get an access token for PBX APIs

You must have an LWA access token to perform any PBX API operation. The following instructions use the curl command-line tool to get an access token. You can also get an access token by using a REST client.

To get an access token with the curl command

1. Copy the following curl command.

Copied to clipboard.

    curl -i -X POST \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials&client_id={clientID}&client_secret={clientSecret}&scope=amazon_communication::network:siptrunk' \
    https://api.amazon.com/auth/o2/token

2. Replace the {clientID} and {clientSecret} with the client ID and client secret from Step 1.

3. For authentication with the PBX API, set the scope to scope=amazon_communication::network:siptrunk.

4. Run the curl command that you created in the previous steps.

5. Verify that you receive an access_token that looks similar to the following success response example.

{
        "access_token":"Atc|{someToken}",
        "expires_in":3600,
        "scope":"amazon_communication::network:siptrunk",
        "token_type":"Bearer"
}

In the previous response example, the access token that starts with Atc| is the Bearer token that you can use in Step 4 and Step 6. Typically, the token has an expiration time. In this example, the token expires in one hour (3600 seconds).

Step 3: Enable the PBX communication skill

In this step, you enable the Amazon PBX communication skill on each unit where you want to enable calling.

The skill ID for the PBX communication skill is amzn1.ask.skill.9bbb90f1-324c-4040-ad03-5cecf0376da3.

To enable the PBX communication skill for a unit, do one of the following:

To enable the PBX communications skill in the ASP console

  1. Sign in to the ASP console and navigate to the Rooms page.
  2. On the Rooms page, open the page for the room where you want to enable the skill.
  3. Click Enable property skill.
  4. In the Skill ID field, enter the PBX communication skill ID.
  5. For Skill stage, select Live.
  6. Click Enable skill.

Step 4: Create a SIP trunk

In this step, you create a SIP trunk between the ASP service and your PBX. You can use an IP-based peer or Fully Qualified Domain Name (FQDN) peer. For details, see Create SIP trunk. For IP-based peers, Amazon uses the IP address for the SIP domain in the request URI for calls initiated from Alexa-enabled devices. For FQDN-based peers, Amazon uses the domain name in the request URI.

You can either use a REST client or the curl command to interact with the PBX API.

To create a SIP trunk

  1. In the following example, click Copy code, and then make the following replacements:

    • Replace {access token} with the token from Step 2.
    • Replace the -----BEGIN CERTIFICATE----- lines, pbx.example.com, the IP address 192.0.2.1, and port number 5061 with your own.

Copied to clipboard.

   POST /v1/communications/network/siptrunk HTTP/1.1
   Host: api.amazonalexa.com
   Content-type: application/json  
   Authorization:  Bearer {access token}
   {
        "tls": {
            "certificateChain": [
                "-----BEGIN CERTIFICATE-----CERTIFICATE_CHAIN_CONTENT-----END CERTIFICATE-----",
                "-----BEGIN CERTIFICATE-----CERTIFICATE_CHAIN_CONTENT-----END CERTIFICATE-----"
            ],
            "name": "pbx.example.com"
        },
        "peers": [{
            "ip": "192.0.2.1",
            "port": 5061
        }]
    }

  1. Use the request body that you created in the previous step to make a POST request to /v1/communications/network/siptrunk.
    If the command succeeds, the response includes HTTP status code 201 and a trunkId. You must have this trunkId to map an extension on your PBX with a room in Step 6. For details about the request body and response body properties, see Create SIP trunk.

    After you create the SIP trunk, it takes 5–10 minutes for provisioning to complete.

  2. Use the Get SIP Trunk operation to verify successful provisioning of the SIP trunk. Before you proceed to the next, the response must indicate that the trunk is active.

Step 5: Configure the SIP trunk in your PBX system

After the SIP trunk status is ACTIVE, you can add and configure the SIP trunkId in your PBX system.

To configure the SIP trunk in your PBX system

  1. Enable the following SIP trunk settings on your PBX system:
    • Set the SIP trunk transport with Alexa to TLS.
      However, enable both TLS and UDP transport for the trunk.
    • Make sure to set the dialing transport to TLS and not UDP.
    • Set the SSL method for the PBX SIP trunk to TLS1.2
    • Turn off certification verification, if certification isn't required.
    • Configure the PBX SIP trunk to communicate with the Alexa SIP server at <trunkId>.pbx.us-east1.prod.sbc.amcs-tachyon.com on port 5061. Use thetrunkId from Step 4.
    • Include the Amazon network in the network firewall and PBX allowlist rules. Enter the Amazon Classless Inter-Domain Routing (CIDR) block 3.239.178.128/25 in your configuration.
    • For Media communication, make sure to select SRTP within your PBX SIP trunk setting. In addition, make sure the RTP port range is from 10000 to 20000 or to the maximum number that your PBX system supports.
    • Turn off SIP trunk registration and authentication settings, if they exist for the PBX SIP trunk. Alexa doesn't require SIP trunk server registration and authentication.
    • Make sure the NAT and local networks' addresses are both set up correctly within trunk settings.
  2. After you create the SIP in your PBX system, reload the new configuration and restart the PBX system.
  3. Next, verify the status of the new PBX SIP trunk through reports, logs, or other methods that your solution provides. Make sure that your PBX SIP trunk is ONLINE.
  4. Finally, verify that the two SIP trunks can communicate without error. The following example shows a PBX log with successful communication between Alexa and the PBX. 
     SIP/2.0 200 OK
 Via: SIP/2.0/TLS
 3.239.xxx.xxx:5061;rport=42933;received=3.239.178.211;branch=z9hG4bK00Bfc4e64eec0629f9e
 Call-ID: 135029252_1342052450@3.239.xxx.xxx
 From: <sip:3.239.xxx.xxx>;tag=gK007c063a
 To: <sip:35.165.xxx.xxx>;tag=z9hG4bK00Bfc4e64eec0629f9e
 CSeq: 303930 OPTIONS
 Accept: application/sdp, application/dialog-info+xml, application/xpidf+xml, application/cpimpidf+xml, application/simple-message-summary, application/pidf+xml, application/pidf+xml,
 application/dialog-info+xml, application/simple-message-summary, message/sipfrag;version=2.0
 Allow: OPTIONS, INVITE, ACK, BYE, CANCEL, UPDATE, PRACK, REGISTER, SUBSCRIBE, NOTIFY, PUBLISH,
 MESSAGE, REFER
 Supported: 100rel, timer, replaces, norefersub
 Accept-Encoding: identity
 Accept-Language: en
 Server: FPBX-16.0.21.3(16.27.0)
 Content-Length: 0

Step 6: Map a PBX extension to a room

Next, you map an extension on your PBX to an Alexa-enabled device in a room on your property. After you map an extension to a room and configure the extension on your PBX system, a user on the property can dial the extension to ring the Alexa-enabled device in the mapped room.

The mapping uses the communication profile ID for the room, rather than the unit ID, for proper routing on the Alexa side. For details about communication profiles, see Manage Communication Profiles.

To map an extension

  1. In the following example, click Copy code, and then make the following replacements:

    • Replace amzn1.comms.network.siptrunk.1 with your own trunkId from Step 4.
    • Replace extension 7201 with the extension from your PBX that you intend to map.
    • Replace the {access token} with the token from Step 2.
    • Replace the amzn1.alexa.communications.profile.did.1 with the communication profile ID for the room that you intend to map.

Copied to clipboard.

    POST /v1/communications/network/siptrunk/amzn1.comms.network.siptrunk.1/extension/7201 HTTP/1.1
    Host: api.amazonalexa.com
    Accept: application/json  
    Authorization:  Bearer {access token}
    {
    "routingType": "communication-profile",
    "commsProfileId": "amzn1.alexa.communications.profile.did.1"
    }

  1. Use the request body that you created in the previous step to make a POST request to /v1/communications/network/siptrunk/{trunkId}/extension/{extension}.
    A successful response returns HTTP 200 OK. For details about the request body and response body properties, see Map extension.

  2. Repeat steps 1–2 for each room that you want to assign an extension.
  3. To allow calling by friendly name, such as "Alexa, call front desk," create a contact in the room's address book. For more details, see Manage address books and contacts in the ASP console or Manage address books with the Communications REST API .
  4. Configure the extension on your PBX system to route to the SIP trunk that you created in Step 4.

Step 7: Test the PBX integration

After you map a room to an extension on your PBX system, you can make calls from an Alexa-enabled device to other mapped rooms on your property to test whether your SIP trunk configuration and extension mapping are successful.

Alexa to PBX phone calling

In a room with a mapped extension, make a call from an Alexa-enabled device to a PBX phone on your property. For example, you might say, "Alexa, call 1234."

Verify that the phone rings, the call connects, and two-way communication is possible.

PBX phone to room calling

Make a call from a PBX phone on your property to a room with a mapped extension. Verify that the Alexa-enabled device rings, the call connects, and two-way communication is possible.

Room-to-room calling

To set up room-to-room calling, create two rooms on your property, associate an Alexa-enabled device with each room, and map separate extensions for each room. Verify that you can make a call from the extension in one room to the extension in the other room by speaking to your Alexa-enabled device. For example, you might say, "Alexa, call 1101."

Verify that the Alexa-enabled device in the room that you're calling, rings. Make sure that the call connects and two-way communication is possible.

Was this page helpful?

Last updated: Nov 25, 2024