Skip to main content

Need Help Using Spok Knowledge?

Internet Explorer is not supported. Please reload in Chrome, Edge, Firefox, or Safari.
Spok

Configuring Spok Messenger API

The API interface is deployed with the Server feature and is a core component of that service. A few configuration steps must be taken before it can be used for the first time by a third party or by internal features that depend on it.

The following steps must be taken before the API interface can be used:

  • The HTTPS listening port must be configured if you do not want to use the default 18134. We recommend using the default port when possible.
  • SSL certificate must be bound to the HTTPS listening port on the Windows server.

 

Configuring API Inbound Routes

Multiple inbound API routes can be created and are configured based on the User selected. 

Once new routes are added, they can be configured as an input gateway source in the Event Actions > Sources screen. For more information about event action sources, see Managing Events in Spok Messenger: Managing Gateways.

To use a new route, the user can login to the account associated with inbound API gateway route and send events using API. Spok Messenger API will automatically map the correct API inbound gateway route.

If a user is signed in with an account that does not have an associated API inbound gateway route for a RESTFUL request, then a default inbound API route “API” will be used as an input source gateway.

Create a New API Inbound Route

Users can create multiple API inbound routes to have better flow control when multiple inbound systems are integrated with Messenger API for sending messages.   

  1. In Spok Messenger, go to Interfaces > API. Any previously configured API inbound routes display in the window.
  2. From the Users drop down, select a user from the list. This list filters only enabled users that have the messaging privilege. For more information about configuring users, see Configuring Users in Spok Messenger.
  3. In the Route Name field, enter the name for the new API Inbound gateway route.
  4. Click Add to add a new route. 
  5. Click Save to save the new route. The route now displays in the list.
  6. When all changes are complete, click Close to exit the interface.

Delete an API Inbound Route

  1. In Spok Messenger, go to Interfaces > API. A list of existing API inbound routes display.
    M_APINewRoute.png
  2. Highlight the route you wish to delete and click Delete.
  3. Click Yes to confirm deletion of the route or No to cancel.
  4. If the route is deleted, it no longer displays in the list.
    M_APIGwy.png

 

Configuring the API Port Number

The API port in Spok Messenger is configured through the API interface. The default for this port is '18134'. To change the port number, follow the steps below.

  1. In Spok Messenger, go to Interfaces > API and click Configuration.
  2. In the HTTPS Port Number field, enter the port number the API will use for HTTPS binding.
    M_API Port.png
  3. HTTP bindings to the Messenger API are disabled by default. Click the Enable Local HTTP checkbox to enable HTTP connections to the Messenger API via the configured HTTP Port Number. Messenger will only accept HTTP connections from the same machine as Messenger is installed to. All HTTP connections from remote clients will be denied.
  4. The HTTP Port Number field is enabled when Enable Local HTTP is checked. Set this value to the port number the Messenger API will use for HTTP connections.
  5. Clicking Save will restart the Messenger API service if any of the values in the dialog have been changed.

API SSL Certificates

You can use an existing certificate or create a new self-signed certificate for the API port. The certificate needs to be imported into the host machine’s Certificate’s store (local Computer). Once you have imported the certificate into the Windows certificate store you can bind the certificate to the API port using the Windows command line shell.

 SSL Self-signed certificates expire after 1 year.

To manually create a certificate and bind it to the API port, follow the Manual Steps.

To us the (automated) method, use the Alternative (Automated) steps.

Manual Steps

Creating a Self-Signed Certificate (Manual)

If you already have a certificate, then skip this section and move on to the Bind the Certificate to the Port section.

If a certificate for the API server is not provided, one must be created.

In this example, IIS manager is used to create a self-signed certificate.

  1. Open Internet Information Services Manager and click Server Certificates > Create Self-Signed Certificate.


  2. In the Create Self-Signed Certificate dialog, enter a name for the certificate. Leave the certificate store as 'Personal' and click Ok.

     

After the self-signed certificate is created via IIS manager, Windows automatically imports the certificate into the Certificates store (local Computer).
NOTE: The certificate may need to be installed manually.

Bind the Certificate to the Port (Manual)

After the certificate is created and imported into the trusted root certification authorities, it must be bonded to the HTTPS request port.

  1. Click the certificate and click the Details tab.
  2. Copy the certificate thumbprint to notepad and remove the spaces.
  3. Run the Windows cmd prompt as an administator and enter the following:
    1. Enter netsh http add urlacl url=https://+:<Port Number>/ user=<Your user name> and press Enter.
      <Port Number> Enter the port to be used as an HTTPS listener.
      <Your user name> Enter your user name.

      In this example, the port number is '18134' and the username is 'Everyone'.

       
    2. Enter netsh http add sslcert ipport=0.0.0.0:<Port number> certhash=<thumbprint> appid={app-guid} and press Enter.
      This command is used to bind the certificate with the port number and application id. 
       
      <Port Number> This is the listening port that matches any IP address for the local machine.
      <thumbprint> Certificate SHA hash. Paste the thumbprint copied earlier into this section.
      app-guid This is the identity of the owning application.

    3. Enter netsh http show sslcert ipport=0.0.0.0:<Port number> and press Enter.
      This command is used to show the SSL certificate binding result.

Alternative (Automated)

You can use PowerShell commands to do everything outlined in the API SSL Certificates steps without performing manual steps.

Enter the following:

Import-Module WebAdministration

$dns = Resolve-DNSName -Name $env:ComputerName -type A

netsh http add urlacl url=https://+:18134/ user=$env:USERNAME

$cert = New-SelfSignedCertificate -DNSName $dns.name,$dns.IPAddress,$ENV:ComputerName,"localhost" -CertStoreLocation "Cert:\localMachine\my"

$cert = Move-item $cert.pspath "Cert:\LocalMachine\Root" -PassThru

$cert | New-Item IIS:\SslBindings\0.0.0.0!18134

netsh http show sslcert ipport=0.0.0.0:18134

Invoke-RestMethod "https://localhost:18134/help"

 

NOTE: The script above will create a cert that is more flexible for the Host name in the URL. The cert will lack a friendly name (that would be a feature that is only supported in PowerShell 5+).

Test the API Interface

Verify the API is ready for use and a valid certificate is properly bound to the listening port by executing the following Url from a web browser.

NOTE: If you followed the API SSL Certificate (Manual) steps, then you must use the exact host name.

https://<host>:18134/help/index

Where <host> is the host name or IP address of the Messenger server. You will need to change the 18134 to a different port number if you configured the API port to listen on something different than the default port.

If successful, you should see the API help page similar to the following. Also, the browser should not display any warnings or errors about your certificate if it is valid, trusted and properly bound to the port.

Once successful, the API interface is ready for use.

Spok Messenger API Documentation

Below is a list of documentation for Spok Messenger API and the location where to find it:

 

Spok Messenger API online documentation

Location: https://<hostname>:<port>/help/index

 

Spok Messenger API Offline Documentation License

This offline API Documentation is generated by swagger, which is an open-source API documentation tool.

Location: http://apache.org/licenses/LICENSE-2.0.html