Configure API mappings

Role: Company Administrator

API Mapping is Whispir’s ‘actions engine’ that runs based on rules. It allows third-party IT systems and applications (such as voicemail, email and SMS messaging services) to push information to Whispir via HTTP requests in order to trigger specified actions. The API mappings that are created on the API Mapping page provide the mechanism that allows an action workflow to be executed. API mappings can be invoked by address mappings (the inbound gateway) and Whispir’s rich messages.

For example, an API mapping could be created to prompt a person to send an SMS message to a particular phone number, which then triggers an event – or perhaps adds the person to a distribution list in Whispir. There’s a wide range of actions available.

Important! If you’re interested in using the API Mapping feature contact the Whispir Support Team ( It requires technical input and guidance to set up and invoke correctly, particularly for complex workflows.

Note: You can review inbound HTTP requests on the Incoming Request Log page. See View the Incoming Request Log.

Create the mapping

  1. Open the API Mapping page (click administration sidebar icon > Administration sidebar > API Mapping).
  2. Note: If you need access to the API Mapping feature but you can’t see it in the Administration sidebar contact the Whispir Support Team (

  3. In the API Name field enter a short description of what the mapping is for and/or what it does.
    As soon as you click in the field additional fields appear below it.
  4. In the API Request ID field enter a unique ID (with no spaces).
    This is the identifier that external systems will use to invoke this particular mapping. Therefore it must be unique across all Whispir customers.
    Best practice is to make the ID a short form of the API name so it’s easier to manage in the future.
  5. Tip! You can click Generate to add a unique ID automatically.

  6. In the API Type field:
    • Select Simple if you want an incoming external request to trigger only a single action. Go to Step 6.
    • Select Rule-Based if you want an incoming external request to trigger multiple actions. Go to Step 5.
  7. In the Execute matched rules field select an option.
  8. In the IP Range Filter field enter *.*.*.* (which represents an infinite IP range).
    A specific IP address or address range is rarely required for this field.
  9. (optional) Enter any relevant variables in the API Variable(s) fields.
    These are custom variables that can be included in the body of an SMS message, email or voice message. They’re dynamically populated from the inbound request into an outbound action at send time.
    • In the left column enter the name of each variable (with no spaces).
    • (optional) In the right column enter the default value to be used if no value is provided for the variable in the left column.
  10. Click Save.
    Your new mapping is saved but it won’t appear in the API Mapping List at the bottom of the page until you assign rules to it.
  11. Go to Assign and add rules to the mapping.
create the API mapping


Assign and add rules to the mapping

  1. In the Select API field select the mapping you just saved.
    Additional fields appear below it.
  2. Do one of the following:

Related links