Introduction

The intention of this document is to integrate Annex Cloud products with Attentive SMS so that the Annex Cloud clients can use Attentive as an SMS gateway to send SMS to subscribed customers. The customers will be able to receive SMS based on loyalty actions performed on an ecommerce platform.

Purpose

1. Activate Attentive from Annex Cloud Dashboard.
2. Send the required data from Annex Cloud to Attentive to trigger the SMS.
3. Mapping a loyalty customer’s mobile number as a unique ID.
4. Setup a CRON job to complete the trigger mechanism to fulfill the loyalty action-based SMS campaigns.

High-Level Design

Revision History

Prerequisites for Installation

• Client Name - Attentive
• Site ID - XXXXXX // Annex cloud will provide your site id.
• Access Token - XXXXXXX
  • Steps to creating an Access token:
    • Step 1: Create a JSON array with Loyalty Token and Site id.
    • Step 2: Encode with function of base64_encdoe().

Loyalty Program Version

Annex Cloud - Loyalty V3 API 3.0.0

Attentive - NA

Configuration Steps

1. Create Sign-up flow Or Attentive team will provide you with the Sign-up flow for Integration Affiliate Endpoint

Steps for how to create a sign-up flow on Attentive:

1. Log in to the URL below- https://ui.attentivemobile.com/signin
   Username –XXXXXXX (Annex Cloud will provide you)
   Password- XXXXXX (Annex Cloud will provide with you)
2. Click on the left-side Subscribers tab.
3. Click on Create Sign-up flow button.
4. And see the form below and fill in the information and click on the Save button.
5. Created Sign-up flow. You can check on the Subscribers page.

2. Create App

Steps for how to create an App on Attentive for API Integration:

1. After Login on Attentive, Click on the Left side Integrations tab and click the Create App button.
2. Fill out the information from the App and give written permission for the app and click on Create button.
3. Now you can see the Created app

Integration Flow

This section will contain a generic flow diagram or diagrammatic representation of how the Annex Cloud system will communicate with the platform.

The integration flow will be designed by IPM and Dev.

Installation Steps on the Platform

The installation steps are explained by use cases that are supported by the Attentive platform.

1. Subscribe a User: As a customer, I want to subscribe to the SMS campaign so that I will receive SMS based on my loyalty activity.
2. Get subscription eligibility for a user 
3. Unsubscribe SMS service: As a user, I want to unsubscribe from the SMS services so that I will not be able to receive SMS based on my loyalty activities.
4. Messages: As a subscriber, I should be able to receive SMS based on my loyalty activities so that I can keep myself updated.
5. Segments: Attentive does not provide an API where we can push the segments from Annex Cloud to the Attentive platform. But the exported list from Annex Cloud can be uploaded on the Attentive platform.

List of APIs/Data Push/Setting up Trigger

Below is the list of APIs which are used for operations:

1. Subscribe User –API - https://api.attentivemobile.com/v1/subscriptions

Content-type – application/json

Method- POST

Authorization - Bearer elNnY1pFcXRwSmJNTFlkRnVIdU1nSFhoRUE5QURxeno1VFc4 (This Authorization key is taken from an App which is made in the Attentive Integration tab.)

Request Body – 

{
    "user": {
        "phone": "7707651750",
        "email": "test@gmail.com"
    },
    "signUpSourceId": "132109" (This sign-up source id is taken from the Sign-up flow which is made in the Attentive Subscribers tab.)
}

Response-

{
    "user": {
        "phone": "7707651750",
        "email": "test@gmail.com"
    },
    "subscriptionResponses": [
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "TEXT"
            },
            "subscriptionCreationStatus": "NEWLY_CREATED"
        },
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "EMAIL"
            },
            "subscriptionCreationStatus": "NEWLY_CREATED"
        }
    ]
}

Subscribed User

2. Get subscription eligibility for a user – API - https://api.attentivemobile.com/v1/subscriptions?phone=7707651750&email=test@gmail.com

Content-type – application/json

Method- GET

Authorization - Bearer elNnY1pFcXRwSmJNTFlkRnVIdU1nSFhoRUE5QURxeno1VFc4 (This Authorization key is taken from an App which is made in the Attentive Integration tab.)

Response-

{
    "subscriptionEligibilities": [
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "TEXT"
            },
            "eligibility": {
                "isEligible": true
            }
        },
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "EMAIL"
            },
            "eligibility": {
                "isEligible": true
            }
        }
    ]
}

Eligible Subscribed User-

3. Unsubscribe subscriptions for a user – API - https://api.attentivemobile.com/v1/subscriptions/unsubscribe

Content-type – application/json

Method- POST

Authorization - Bearer elNnY1pFcXRwSmJNTFlkRnVIdU1nSFhoRUE5QURxeno1VFc4 (This Authorization key is taken from an App which is made in the Attentive Integration tab.)

Request Body – 

{
    "user": {
        "phone": "7707651750",
        "email": "test@gmail.com"
    },
    "subscriptions": [
        {
            "type": "MARKETING",
            "channel": "EMAIL"
        },
        {
            "type": "MARKETING",
            "channel": "TEXT"
        }
    ]
}

Response-

{
    "user": {
        "phone": "7707651750",
        "email": "test@gmail.com"
    },
    "subscriptionResponses": [
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "TEXT"
            },
            "subscriptionUnsubscribeStatus": "NEWLY_UNSUBSCRIBED"
        },
        {
            "subscription": {
                "type": "MARKETING",
                "channel": "EMAIL"
            },
            "subscriptionUnsubscribeStatus": "NEWLY_UNSUBSCRIBED"
        }
    ]
}

4. Messages

API - https://api.attentivemobile.com/v1/subscriptions/messages

Content-type – application/json

Method- POST

Authorization - Bearer EJ0S7a5v27DkZuxxtIxjyIq3S54ac4dNm8NDLf8sMK8 

(You must provide an access token. Contact legacyapi@attentivemobile.com for this token.)

Request Body – 

{
    "to": "7707651750",
    "body": "Hello check the test message please7"
}

Response-

{
    "type": "v1",
    "to": "+17707651750",
    "body": "Hello check the test message please7",
    "skipFatigue": true,
    "createShortLink": false,
    "addSubscriber": "true"
}

User Messages -

5. Segments – API - https://s15.socialannex.net/api/3.0/segment

Request:

Sample Request:

{
 "name":"Only Members",
 "type":"Current Data",
 "fromDate":"2020-01-17",
 "toDate":"2020-02-14",
"member":"jacobsmith@gmail.com,brianpaul@gmail.com,markburger@gmail.com",
 "status":"ACTIVE",
"externalId":"123",
"externalName":"Members specific"
}

Response:

This will create a segment and will return the details which include segment id, segment name, segment type, etc.

Output fields:

• segmentId: Return the unique id of the segment.
• segmentName: Returns the name of the segment.
• segmentType: Returns the type of segment (Current Data/Past Data).
• segmentFromDate: Returns the segment starting date in yyyy-MM-dd'T'HH:mm:ssZ format.
• segmentToDate: Return the segment ending date in yyyy-MM-dd'T'HH:mm:ssZ format.
• member: Returns the email ids of the members in the segment.
• errorCode: Display only when the API request fails. This will denote the type of error.
• errorMessage: Displays the reason why the API request has failed.

Sample Positive Response:

Sample Error Response:

Functions (for ESP, Attentive)

Created Library Functions/Methods:

1. Subscribe User – addOrUpdateContact($json_data) 
2. Get subscription eligibility for user - getLists($json_data)
3. Unsubscribe subscriptions for a user - unsubscribeUser(($json_data)
4. Messages - messages ($json_data)
5. Segments - segmentSubscibe ($json_data)

Instructions for resolving the run time errors

1. Messages - To start sending the messages, the Legacy APIs Access Token needs to be activated. To do so, an email needs to be sent to the Attentive Legacy team for the Access token.

Email ID: legacyapi@attentivemobile.com

2. Subscribe User - source id is required for user subscription.

We can find this Sign up source id in the Subscribers tab. Check the screenshot below.