Engage Email Widget API Integration

  • Updated

Olo Engage offers a website email signup form integration from your website to feed Engage and SendGrid guest data for Marketing Automation email campaigns. The instructions below provide information about the integration, including technical details and example. 

Overview

This integration takes the following actions:

  • Adds guest data to Engage dashboard 
  • Adds guest data to a defined SendGrid list for a specific “merchant” (restaurant location)

What you need from Engage:

  • Wisely API key
  • Widget ID for each restaurant location

Technical Details

Before getting started please note that the following are required to be integers (strings won't work):

  "birth_day": "optional",

  "birth_month": "optional",

  "birth_year": "optional",

NOTE: The POST link below will not render anything if directly clicked in a web browser as it is intended for API calls only. 

POST https://loyaltyapi.wisely.io/v2/web/merchant/subscribe

Headers:

api_key:

Content-Type: application/json

Body:

{

  "fname": "required",

  "lname": "required",

  "email": "required",

  "widget_id": "required",

  "birth_day": "optional",

  "birth_month": "optional",

  "birth_year": "optional",

  "zip_code": "optional",

  "phone": "optional",

  "sms_marketing_opt_in": "boolean|optional"

}

SMS Opt-in

If you intend to collect phone numbers for SMS marketing purposes, you MUST include a dedicated opt in check box tied to the "sms_marketing_opt_in" body field. Consent for email and SMS are required by law to be two distinct actions by the guest. 

The minimum required opt-in copy is as follows:

"By checking this box, you consent to receive text messages sent by an automatic telephone dialing system. Consent to these terms is not a condition of purchase. Message frequency varies."

**Please consult with you legal team to ensure you're following all applicable laws**

Example opt-in flow:

mceclip0.png

 

Example using a curl request to hit this API:

curl --location --request POST 'https://loyaltyapi.wisely.io/v2/web/merchant/subscribe' \

--header 'api_key: {REPLACE_API_KEY}' \

--header 'Content-Type: application/json' \

--data-raw '{

   "fname": "MyTester",

   "lname": "Stewart",

   "email": "Test@Test.com",

   "widget_id": "1",

   "birth_day": "10",

   "birth_month": "10"

}'

FAQs

Both fname and lname are required, yet we only serve one field called 'name'. why?

A: OUR web widget form splits the name into first and last name, natively, based on whitespace:

fname, lname = name.gsub(/[^0-9A-Za-z]/, ' ').split

HOWEVER, our API does NOT do any splitting. The first and last name is only split by our frontend code for the Engage-provided web widget.

Our API tests that:

  1. At LEAST one of fname or lname is filled out
  2. AND that the name doesn't contain any numbers:
if((fname.length == 0 && lname.length == 0) || regexnum.test(fname) || regexnum.test(lname)){
    logger.debug("this name could be supplied by a bot : "+fname + ' '+lname)
    res.sendStatus(202)
    return;
}

I'm getting a 401 Unauthorized Error. Why?

Check that:

  1. The right API key is being used for that program
  2. The headers are included (PLEASE make sure headers are included)
  3. The request is a POST, not a GET

I'm getting a 202 Request Accepted. Why?

This means that request didn't include a first or last name. At LEAST a first name must be provided.

Can I send the birthday in one string, like "11/16/1995"? 

No. It must be parsed into birth_day, birth_month, and birth_year.

Does the phone filed input need to be in a particular format?

We use Google’s phone parser on the backend. It should handle any kind of phone input.

Related articles