Prerequisites

General

Requirements for your app

  • When building your plugin you can use our PHP, node.js client, or Java SDK (.jar file).
  • Your application needs to handle authentication for Mapp Connect. It's recommended that your app has the UI for providing the Integrations ID, Secret Key, and API address for authentications. However, those values can also be hard-coded in the client file. 
  • Use the GET API to obtain the Groups and Prepared Messages from your Engage instance into your app. This allows you to add contacts with/without attributes to groups and send messages (Email, SMS, In-App, Push).

Packages and Downloads

GitHub Repositories

PHP

Java

JavaScript (node.js)

Postman Sandbox

This Postman collection can be used to test how to authenticate and use all types of events. To use it, create a free Postman account (or download the free app) and upload the collection. The procedures described below use this collection to demonstrate how it works.

Procedures

These procedures use the demo Postman collection (above) to demonstrate the authorization and API testing process. In this same way, you can authorize and test your app for use with Mapp Connect. 

To perform these procedures, you need to create a Postman account and upload the collection in the Collections section of your Postman workspace.

Test authentication

  1. Replace the API URL in the URL line with the API URL of the cluster where your Engage system is located. In our example, the part that needs to be replaced is "jamie.h.shortest-route.com/charon/api/v1/". If you don't know which cluster applies to your system, reach out to your account or customer success manager.

     Available clusters
    Address / Cluster

    Please check with your account manager which cluster applies to your system.

    Available clusters:

    • EU L3 cluster: https://jamie.g.shortest-route.com/charon/api/v1/ 

    • US L3 cluster: https://jamie.a.shortest-route.com/charon/api/v1/

    • EMC cluster: https://jamie.h.shortest-route.com/charon/api/v1/ 

    • EMC-US cluster: https://jamie.c.shortest-route.com/charon/api/v1/ 

    For more information, see Clusters.


  2. Create a GENERIC integration in Mapp Connect. See the full process here: Create an Integration.

    Keep the Integration ID and the Secret ready. You will need them to perform the next steps.

    • Integration ID: Each integration has a unique ID. The integration ID is available on the overview tab of your integration settings.
    • Integration Secret:  A random secret is available if enabled. This key can be used to sign a REST request using HMAC Authentication (read more here). Generate a secret key and store it in a notepad. This secret will only be visible once. Copy this and save it for future use after regeneration.
  3. Once the integration is created, paste the Integration ID in the URL after /integration/. 

  4. Go to the Pre-Request Script tab and paste the secret key in line 21.
  5. Click Send and wait for the response.
  6. Since Mapp Connect is an asynchronous API, there are only two types of responses:
    1. 200: call received
    2. 500: incorrect JSON, or wrong authentication credentials

Test API methods

You can test any method that is listed in the collection. All available API calls are listed below.

  1. Select the method you want to test from the menu on the left.
  2. Enter the payload to the Body section and click Send. For more information, see API Endpoints.

Available API Methods

Mapp Connect is a simple async API with methods to:

GET

List of Mapp Engage groups, prepared email, push, and SMS messages and mobile App ID.

POST

Add or update data for:

  • User:
    • create a contact in Mapp Engage (not existing contacts require a group ID in a payload to be subscribed in the system)
    • update an existing contact (group ID is not required), unsubscribe or remove a contact
  • Email:
    • send a prepared email message to the contact with parameters
    • send a prepared email message to a group (without parameters)
  • SMS: send a prepared SMS message to the contact (mobile number or email field is required) with parameters
  • Push: send a prepared push message to the contact (mobile number or email field is required) with parameters
  • Transaction: add order details to contact and send an order message
  • Wishlist: add a Wishlist item to the contact profile
  • Abandoned Cart: add abandoned cart product to the contact profile
  • Automation: trigger whiteboard automation from a third-party app (see Set Up a Mapp Connect Automation Event)
  • Product Catalog: create and/or update a product catalog item in Mapp Engage
  • Coupon: create a coupon

For more information, see API Endpoints.