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

The following instructions walk you through the steps to configure your Private Branch Exchange (PBX) system to work with Alexa-enabled devices in rooms on a property that has an Alexa Smart Properties subscription.

Prerequisites

Before you start, you must have the following items:

  • An Alexa Smart Properties subscription that supports calling. For a list of Alexa Smart Properties subscriptions and the features each subscription supports, see Product feature comparison.
  • The property must have at least one room created. For details, see About Managing Properties and Rooms.
  • A communication profile for each room, and access to the communication profile ID for each room. For details about the communication profile ID, see Manage Communication Profiles.
  • Alexa-enabled devices in rooms that support calling. Alexa-enabled devices that support calling include the following models:
    • Amazon Echo (2nd, 3rd, 4th Generation)
    • Amazon Echo Dot (2nd, 3rd, 4th Generation)
    • Amazon Echo Dot with Clock (3rd, 4th Generation)
    • Amazon Echo Plus (1st, 2nd Generation)
    • Amazon Echo Show 5
    • Amazon Echo Show 8
  • A Session Initiation Protocol (SIP)-based PBX system on your property.
  • An Amazon developer account.
  • A Representational State Transfer (REST) client or the curl command-line tool.

Steps to integrate your PBX system with Alexa-enabled devices

To use the PBX API to configure Alexa-enabled devices with your PBX system, complete the following steps:

  1. Create a security profile.
  2. Set up your PBX system for integration.
  3. Get an access token.
  4. Create a SIP trunk.
  5. Map an extension with a room.
  6. Test your configuration.

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 3.

  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: Set up your PBX system for integration

In addition to the Alexa Smart Properties prerequisites, make sure that your PBX system meets 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) and media over Secure Real-time Transport Protocol (SRTP).

  • You should 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 of the signaling and media ports must be accessible by the Amazon infrastructure.

  • Your PBX must have a Secure Sockets Layer (SSL) certificate installed. The certificate doesn't need to be a public certificate issued from a public certificate authority.

  • If you 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.

  • Your network firewall rules must allow the Amazon network. Enter the Amazon Classless Inter-Domain Routing (CIDR) block 3.239.178.128/25.

Step 3: Get an access token

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 that you got in 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 5. Typically, the token has an expiration time. In this example, the token expires in one hour (3600 seconds).

Step 4: Create a SIP trunk

In this step, you make a POST request to create a SIP trunk. You can either use a REST client or the curl command to interact with the PBX API.

To create a SIP trunk

  1. If you use Transport Layer Security (TLS), click the combined certificate bundle link to download the certificate, and then import the wildcard root certificate into your SIP infrastructure.

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

    • Replace {access token} with the token you got in Step 3.
    • Replace the -----BEGIN CERTIFICATE----- lines, pbx.example.com, the IP address 11.22.33.44, 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-----\n...\n-----END CERTIFICATE-----",
         "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----"
       ],
       "name": "pbx.example.com"
     },
     "peers": [
       {
         "ip": "11.22.33.44",
         "port": 5061
       }
     ]
   }

3. 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, you get a successful response with HTTP return code 201 and a trunkId. You must have this trunkId to map an extension on your PBX with a room in Step 5.

For details about the request body and response body properties, see Create a SIP trunk. To see an example body of a successful response, see Response body example.

Step 5: Map an extension with a room

After about ten minutes, the status of the SIP trunk that you created in Step 4 becomes ACTIVE, which indicates that the trunk is fully configured and operational. To verify whether your trunk status is ACTIVE, submit a Get a SIP trunk operation.

Next, complete the following steps to map an Alexa-enabled device in a room on your property with an extension on your PBX.

To map an extension

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

    • Replace amzn1.comms.network.siptrunk.12345 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 3.
    • Replace the amzn1.alexa.unit.did.abcdef1234 with the communication profile ID for the room you intend to map. For details about the communication profile ID, see Manage Communication Profiles.

Copied to clipboard.

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

2. 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 an extension.

Step 6: Test your configuration

After your Alexa-enabled device is mapped to your PBX system, you can make calls from this Alexa-enabled device to other rooms in your property to test whether your SIP trunk configuration and extension mapping are successful.

In the room where the Alexa-enabled device is mapped, speak to your Alexa-enabled device. For example, you might say, "Alexa, call extension 1234."

If the person in the room with extension 1234 gets the call from your Alexa-enabled device, you successfully configured and mapped your PBX to work with Alexa.

Was this page helpful?

Last updated: Nov 28, 2023