Introduction

The intention of this document is to integrate the Annex Cloud loyalty program with Gorgias Support desk so that the Annex Cloud clients can use Gorgias as a customer support help desk to provide the necessary support to subscribed customers along with the loyalty program information. The help desk support representatives can easily provide support to customers based on the loyalty actions performed on eCommerce/other integrated platforms.

Purpose

This section will contain the purpose of integration with the platform.

1. The main objective of the document is to give detailed information regarding the integration between Annex Cloud and Gorgias Help Desk Support.
2. Sync customer’s loyalty data along with verification of customer's loyalty.
3. Show loyalty information of a customer at the time of opening a new ticket or existing ticket of a customer.

High-Level Design (common for all w.r.t platforms)

The HLD will consist of data flow and communication between the AC and the Platform.

The HLD will be designed by IPM and Dev.

Product and Integration Support

This section will contain a list of contact persons and the escalation matrix for any support.

Revision History

Prerequisites for Installation

Client Name: Gorgias

Site ID: XXXXXX // Annex cloud will provide your site id.

Access Token: XXXXXXX

Steps for creating an Access token:

Step 1: Create 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

Gorgias: 

Configuration Steps

Create an HTTP Integration on Gorgias Integration Tab:

Steps to how to create HTTP Integration:

1. After the Login of Gorgias account, you can see the screen below.
   
2. Click on the kebab menu, which is placed on the left sidebar for multiple options, and click on the Settings option.
   
3. Now you can see the screen below and click on the Integration Tab.
   
4. Now see the Integration Apps and Select HTTP option.
   
5. Click on Add HTTP Integration button.
   
6. Fill up the information below for the need to get User info details from Ticket Created users and Click on Add Integration button.
   
   
7. Now we can see the Created HTTP Integration.
   
8. Create Ticket and Add Customer for Gorgias and Sync that Customer to Annex Cloud as a Loyalty member.

Steps: 

1. Click on the kebab menu which is placed in the left sidebar and click on the ticket option.
   
2. Click on the Create Ticket button.
   
3. Fill in the ticket info Subject, Customer Email, Message, and click on Send button.
   
4. That Create ticket now you can click on Edit Widget which is the place in Right sidebar.
   
5. Now we can check if the last added ticket customer is now Annex Cloud's loyalty member. And we check the loyalty details on the widget.
   
6. Drag and drop the values below into the sidebar to preview how they will look next to your tickets. After dragging and dropping the values, click on the Save changes button.
   
7. And click on Leave Widget Edition, which is placed in the right sidebar for ticket info and an updated widget next to our ticket.
   
8. Now we can see the loyalty details next to your tickets.
   

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

Staging path: https://api.socialannexstaging.com/gorgias

Production path: https://api.socialannex.com/gorgias

Installations of Loyalty Program

(This should include necessary screenshots).

List of all possible use cases setup: 

1. Get loyalty info from Mention ticket users.
2. Sync Loyalty Customer from Annex Cloud to Gorgias

List of APIs/Data Push/Setting up Trigger

Create User and Opt-in User API

Request:

Sample Request:

{
  "id": "user@domain.com",
  "email": "user@domain.com",
  "firstName": "John",
  "lastName": "Doe",
  "zipCode": "90002",
  "optInStatus": "YES",
  "status": "ACTIVE",
  "phone": ""123-123-4567",
  "birthDate": "2018-04-01T00:00:00-0700",
  "anniversaryDate": "2018-04-01T00:00:00-0700",
  "userProfileImageUrl": "https://www.socialannex.com/public/manageoptionsdesign16/images/product_landing/loyalty-hover.png",
  "createDate": "2018-04-01T00:00:00-0700",
  "updateDate": "2018-04-01T00:00:00-0700",
  "extendedAttribute": ["KEY1": "VALUE1", "KEY2": "VALUE2"]
}

Response

This will create a user and opt-in that user for the loyalty program and will return the details which include a user name, opt-in status, phone, birthdate, anniversary date, etc.

Output fields:

• id: Return the unique id.
• email: Returns the email address of the user.
• firstName: Returns the first name of the user.
• lastName: Returns the last name of the user.
• optInStatus: Return the opt-in status of the user.
• status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
• phone: Returns the phone number of the user.
• birthDate: Returns the birthdate of the user in yyyy-MM-dd'T'HH:mm:ssZ format.
• anniversaryDate: Returns the anniversary date of the user in yyyy-MM-dd'T'HH:mm:ssZ format.
• userProfileImageUrl: Returns the url of the user’s profile image only if this parameter is passed while creating the user.
• createDate: Returns the date & time in yyyy-MM-dd'T'HH:mm:ssZ format in which the user was created.
• updateDate: Returns the date & time in yyyy-MM-dd'T'HH:mm:ssZ format on which the user was updated.
• extendedAttribute: Displays the extra user attributes which are added as per the client’s request.
• 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:

User Details API

Request:

Sample Request:

/users/user@domain.com

Response:

This will return all the details of the user.

Output fields:

• id: Returns a unique identifier (in the SA system) used to identify the user.
• email: Returns the email address of the user.
• firstName: Displays the first name of the user.
• lastName: Displays the last name of the user.
• zipCode: Displays the zip code of the user’s location.
• status: Returns the status of the user if the user is active or inactive. By default, it will be active and can be changed to inactive if the client requests.
• phone: Displays the phone number of the user.
• birthDate: Displays the birthdate of the user in yyyy-MM-dd'T'HH:mm:ssZ format.
• anniversaryDate: Displays the anniversary date of the user in yyyy-MM-dd'T'HH:mm:ssZ format.
• userProfileImageUrl: Returns the url of the user’s profile image. If this field is not passed while creating the user, then this field’s response will be blank.
• createDate: Displays the date on which the user is created in yyyy-MM-dd'T'HH:mm:ssZ format.
• updateDate: Displays the date on which the user details are updated in yyyy-MM-dd'T'HH:mm:ssZ format.
• totalSpendCurrency: Displays the total currency spent by the user.
• extendedAttribute: Displays the extra user attributes which will vary according to the client.
• 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:

Add Points API

Request:

To give points:

To redeem points:

To redeem customs points:

To award/deduct customs points:

Sample Request:

To give points:
{
  "id": "user@domain.com",
  "actionId": "100",
  "activity": "CREDIT",
  "reason": "aj Bonus"
  "credit": "50"
}

To redeem points:
{
  "id": "user@domain.com",
  "rewardId": "111",
  "activity": "DEBIT",
  "orderId": "OD001",
  "reason":"claim"
  "source":"web"
}

To redeem custom points:
{
  "id": "user@domain.com",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "500",
  "reason":"used for purchase"
  "source":"web"
}

To award custom points:
{
  "id": "user@domain.com",
  "actionId": "100",
  "activity": "CREDIT",
  "credit": "50",
  "reason":"bonus"
}

To deduct custom points:
{
  "id": "user@domain.com",
  "actionId": "100",
  "activity": "DEBIT",
  "orderId": "OD001",
  "debit": "50",
  "reason":"adjustment"
}

Response:

This will return a successful response with the details of the points that are added/redeemed from the user’s account.

Output fields:

• id: Displays the unique customer id.
• actionId: Return the particular action id.
• activity: Displays action like credit or debit.
• credit: Displays the number of points credited in the user's account.
• pointsAwarded: Displays the number of points awarded.
• updatedUserTier: Returns the updated user tier after the points are awarded/removed.
• updatedAvailablePoints: Displays the number of updated available points.
• updatedLifetimePoints: Displays the number of updated lifetime points.
• updatedUserTier: Displays the updated user tier.
• releaseDate: Displays the release date in yyyy-mm-dd format in which the hold points will be released.
• reason: Displays the reason for adding or removing the points.
• errorCode: Displays 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:

View Points Details

Request:

Sample Request:

/points/user@domain.com

Response:

This will return the details of the points of the user.

Output fields:

• id: Displays the unique id of the user.
• availablePoints: Displays the available points of the user.
• usedPoints: Displays the used points of the user.
• expiredPoints: Displays the expired points of the user.
• lifetimePoints: Displays the number of points the user has earned since the account is created.
• earnedPointsPeriod: Displays the earned points period (anniversaryYear, calenderYear,quarter,semester)
• spendPointsPeriod: Displays the spend points period (anniversaryYear, calenderYear,quarter,semester)
• earnedPoints: Displays the total earned points in the select “earnedPointsPeriod”
• spendPoints: Displays the total spend points in the selected “spendPointsPeriod”
• holdPoints: Displays the number of total hold points.
• usedPointsOnReward: Displays the number of points used on the reward.
• pointsToExpire: Displays the number of points that are expiring.
• pointsToNextTier: Displays the number of points needed to achieve the next tier.
• pointsToExpireDate: Displays the date (in yyyy-mm-dd format) on which the points will expire.
• spendToNextTier: Displays the number of dollars that the user needs to spend to achieve the next tier. (This field will be displayed only if the tier functionality is based on spending)
• creditsToCurrencyRatio: Displays the credits to currency ratio set at the site admin.
• creditsToCurrencyValue: Displays the converted value of credits to currency according to the ratio.
• errorCode: Displays 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:

Get Tier Information

Request:

Sample Request:

/users/user@domain.com/tiers

Response:

This will return the tier details.

Output fields:

• currentTier: Returns the name of the tier.
• previousTier: Returns to the previous (last) tier that was assigned to the user.
• tierAchieveDate: Returns the current tier achievement date in in yyyy-MM-dd'T'HH:mm:ssZ format.
• tierExpirationDate: Returns the tier expiration date in yyyy-MM-dd'T'HH:mm:ssZ format.
• nextTier: Displays the name of the next tier.
• pointsToNextTier: Displays the number of points required to achieve the next tier.
• purchaseRatio: Displays the purchase ratio which will be applied to the user (from this tier) while earning purchase points.
• currentTierPurchaseRatio: Displays the purchase ratio which will be applied to the user for this tier while earning purchase points.
• spendAmountToNextTier: Displays the amount a user needs to spend to achieve the next tier.
• errorCode: Displays 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:

Create a Customer API(Gorgias)

API - https://socialannextestsite.gorgias.com/api/customers

Content-type: application/json

Accept: application/json

Method: POST

Authorization: Basic YWNpbnRlZ3JhdGlvbnNAYW5uZXhjbG91ZC5jb206NjVmYTk4N2U1OWQ3Mzc4MWMzNDU2MzJiN2U1NTI3NjA4YmI2YzY5NzhmOWE0ZjNlZTMzMDNjY2NhMGJkMGJlZg== (This Authorization key is taken from Gorgias Rest API tab.)

Request Body

{
"timezone":"UTC",
"email":"test.email@test.com",
"name":"Test Name"
}

Response

{
  "id": 63678235,
  "external_id": null,
  "active": true,
  "email": "test.email@test.com",
  "name": "Test Name",
  "firstname": "Test",
  "lastname": "Name",
  "channels": [
    {
      "id": 77653599,
      "type": "email",
      "address": "test.email@test.com",
      "preferred": true,
      "created_datetime": "2021-11-15T11:25:12.580565+00:00",
      "updated_datetime": "2021-11-15T11:25:12.580576+00:00",
      "deleted_datetime": null,
      "user": {
        "id": 63678235,
        "name": "Test Name"
      },
      "customer": {
        "id": 63678235,
        "name": "Test Name"
      }
    }
  ],
  "language": null,
  "timezone": "UTC",
  "created_datetime": "2021-11-15T11:25:12.541887+00:00",
  "updated_datetime": "2021-11-15T11:25:12.544664+00:00",
  "meta": {
    "name_set_via": "agent"
  },
  "data": null,
  "customer": null,
  "integrations": {},
  "note": null
}

List customers (Gorgias)

API: https://socialannextestsite.gorgias.com/api/customers

Accept: application/json

Method: GET

Authorization: Basic YWNpbnRlZ3JhdGlvbnNAYW5uZXhjbG91ZC5jb206NjVmYTk4N2U1OWQ3Mzc4MWMzNDU2MzJiN2U1NTI3NjA4YmI2YzY5NzhmOWE0ZjNlZTMzMDNjY2NhMGJkMGJlZg== (This Authorization key is taken from Gorgias Rest API tab.)

Response 

{
  "data": [
     {
       "id": 62859020,
       "external_id": null,
      "active": true,
      "email": "test6@test.com",
       "name": "",
       "firstname": "",
      "lastname": "",
       "language": null,
       "timezone": "UTC",
      "created_datetime": "2021-11-11T12:28:12.925000+00:00",
      "updated_datetime": "2021-11-11T12:28:12.926887+00:00",
       "meta": {
        "name_set_via": "agent"
       },
       "data": null,
       "note": null
    },
    {
       "id": 60539821,
       "external_id": null,
       "active": true,
       "email": "dj@yopmail.com",
       "name": "Djovik",
       "firstname": "Djovik",
       "lastname": "",
       "language": null,
       "timezone": null,
       "created_datetime": "2021-11-02T09:33:28.933467+00:00",
       "updated_datetime": "2021-11-05T08:37:12.344616+00:00",
       "meta": {
         "name_set_via": "agent"
       },
       "data": null,
       "note": "Test"
     },
]
}

Functions (for ESP, Gorgias)

Configurable Fields List (for ESP, Gorgias) 

Installations of RAF

List of all possible use cases setup

Instructions for resolving the run time errors

System and Security Requirements

Appendix

(Should be in tabular format) 

List of definitions (Abbreviations)

Response Codes