Generic SMS Partner Integration Guide

Overview

This guide explains how to integrate an SMS partner with the Punchh loyalty platform. This guide is intended for businesses that use a Generic SMS Partner adapter where a third-party SMS provider manages the full SMS lifecycle, messaging, compliance, opt-in/opt-out, and syncs subscription status to Punchh via inbound webhooks. Punchh does not send any SMS messages in this implementation.

Note: Contact your Punchh representative to update this Punchh platform configuration.

The integration is webhook-based. Punchh sends guest create/update and loyalty events to the SMS partner via outbound webhooks, while the SMS partner sends SMS subscription status updates back to Punchh via inbound webhooks after a successful double opt-in.

Integration Flow

How the Integration Works

The integration consists of the following stages:

1. Guest sign-up
2. SMS consent evaluation
3. Double opt-in
4. Loyalty event processing
5. Phone number updates

Guest Sign-up

When a guest signs up through the mobile app or web sign-up form:

1. The guest enters their profile information.

2. The sign-up form displays an SMS marketing consent checkbox.

3. The mobile app or web app sends the consent value in the profile_field_answers parameter in the Mobile Sign-up / Register or Online Ordering Create New User API request.
   

   Note: For Generic SMS Partner businesses, Punchh does not send compliance SMS. The send_compliance_sms parameter in the sign-up request is ignored. The SMS partner is responsible for initiating the opt-in process.

4. Punchh creates the guest profile, stores the consent value in the profile_fields array object, and sets sms_subscription = false.

5. Punchh sends a Guest (action: create) webhook to the SMS partner, which includes the guest's phone number and the consent value in the profile_fields array. Here is a sample JSON Guest (action: create) payload with profile_fields containing the SMS consent.

   "profile_fields": [
        {
          "answer": "Yes",
          "code": "sms_marketing_consent",
          "question": "Would you like to receive SMS marketing messages?",
          "upf": "upf0"
        }
      ]
   

   json

6. The SMS partner evaluates the consent value in the profile_fields array object:

   • If the consent value is Yes, the SMS partner initiates the double opt-in process by sending a confirmation SMS to the guest.
   • If the consent value is No or the field is not present, the SMS partner takes no action, and no SMS is sent.

7. Once the guest confirms opt-in, the SMS partner sends an inbound webhook to Punchh with sms_subscription: true.

8. Punchh updates the guest's sms_subscription status to true.

Note: The sms_subscription parameter in the sign-up API response will always return false, regardless of the consent value provided in profile_field_answers. The value is updated only when the SMS partner sends a subscription status update to Punchh via the inbound webhook.

Social Sign-ups

For social sign-ups (Google, Facebook, and similar providers), a phone number may not be available during account creation.

In this case:

1. Punchh sends the initial Guest (action: create) webhook without a phone value.
2. The SMS partner receives the webhook event but takes no action since the phone is null.
3. When the guest later updates their profile with a phone number and SMS subscription consent in the profile_fields array object via the Mobile Update User Profile or Online Ordering Update User Information API, Punchh sends a Guest (action: update) webhook event.
4. The SMS partner evaluates the phone and the SMS consent value in the profile_fields array object. If the phone is present and consent is Yes, the SMS partner initiates the double opt-in process.
5. Once the guest confirms, the SMS partner sends the inbound webhook to Punchh with sms_subscription: true.
6. Punchh updates the guest's sms_subscription status to true.

Guest Object Attributes

These attributes are included in the Guest action: create and Guest action: update webhook payloads. See the Guest event topic for the complete list of attributes.

SMS Consent Processing

When the SMS partner receives a guest webhook, it evaluates sms_subscription in the webhook payload.

The SMS partner should also prevent duplicate opt-in messages for phone numbers that have already been processed.

Double Opt-in Process

The SMS partner is responsible for completing the double opt-in process.

The process is:

1. Send a confirmation SMS to the guest.
2. Wait for the guest to confirm.
3. Send a webhook to Punchh confirming the subscription.
4. Punchh updates sms_subscription to true.

Note: The sms_subscription field is updated only after Punchh receives the confirmation webhook from the SMS partner.

SMS Opt-in Flow — Generic Adapter Flow

Loyalty Events

After a guest is subscribed, Punchh sends loyalty event webhooks, such as:

• Check-ins
• Coupon issuance
• Reward redemption

The SMS partner can use these events to send transactional or promotional SMS notifications.

Phone Number Updates

When a guest changes their phone number:

1. The guest updates their phone number in Punchh via the mobile app using the Update User Profile API or via the web app using the Update User Information API.
2. Punchh sends a Guest (action: update) webhook to the SMS partner containing the updated guest profile with the new phone number.
3. Mobile or web app sends an explicit update call to the SMS Partner with both the old and new phone numbers.
4. The SMS Partner deactivates the old number and updates the record with the new phone number.
5. If sms_subscription is true, the SMS partner re-initiates the double opt-in process for the new phone number. If the guest does not provide consent or opts out during the process, the SMS partner sends the inbound webhook to Punchh with sms_subscription set to false.

Note: The mobile or web app is responsible for explicit SMS Partner update call containing both old and new phone numbers. This dual-number payload ensures the SMS Partner can correctly deactivate the old record and link the new number to the existing guest profile.

Webhook Events

Inbound SMS Subscription Webhook

After a guest completes the double opt-in process, the SMS partner sends a webhook to Punchh to update the guest's SMS subscription status.

Sample Request

curl 'https://SERVER_NAME_GOES_HERE.punchh.com/hooks/smspartner/<business_key>/conversations/status' \
--header 'Content-Type: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--data '{
  "client": "CLIENT_GOES_HERE",
  "phone": "1111111111",
  "email": "test@example.com",
  "sms_subscription": true,
  "user_type": "loyalty",
  "first_name": "John",
  "last_name": "Doe"
}'

Request Headers

Request Parameters

SMS Subscription Management

The SMS partner is the source of truth for SMS consent. For Generic SMS Partner businesses, Punchh does not send any SMS messages, including compliance, opt-in confirmation, or opt-out confirmation messages. The SMS partner is responsible for managing SMS opt-in and opt-out requests.

Opt-in (Subscribe SMS)

When a guest opts in to SMS communications through the SMS partner:

1. The guest sends a subscribe keyword (for example, START) to the SMS partner's number or completes the SMS partner's double opt-in process.
2. The SMS partner updates the guest's subscription status in its system.
3. The SMS partner sends the inbound SMS subscription webhook to Punchh with sms_subscription set to true.
4. Punchh looks up the guest by phone number.
5. If the guest exists, Punchh updates sms_subscription to true.
6. If the guest does not exist, Punchh does not create a guest profile. The webhook is accepted, but no action is taken.
7. Punchh does not send a confirmation SMS to the guest. The SMS partner is responsible for sending any opt-in confirmation messages.

Note: The inbound webhook only updates subscription status. It does not create a guest profile in Punchh. The guest must already exist in Punchh and be created through a standard sign-up process (for example, the Mobile Sign-up API or Online Ordering Create User API).

Sample Request

curl 'https://SERVER_NAME_GOES_HERE.punchh.com/hooks/smspartner/<business_key>/conversations/status' \
--header 'Content-Type: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--data '{
  "client": "CLIENT_GOES_HERE",
  "phone": "1111111111",
  "email": "test@example.com",
  "sms_subscription": true,
  "user_type": "loyalty",
  "first_name": "John",
  "last_name": "Doe"
}'

Opt-out (Unsubscribe SMS)

When a guest opts out of SMS communications through the SMS partner:

1. The guest sends an unsubscribe keyword (for example, STOP) to the SMS partner's number.
2. The SMS partner removes the guest from its active subscriber list and stops sending SMS messages.
3. The SMS partner sends the inbound SMS subscription webhook to Punchh with sms_subscription set to false.
4. Punchh looks up the guest by phone number and updates sms_subscription to false.
5. Punchh does not send an unsubscribe confirmation SMS to the guest. The SMS Partner is responsible for sending any opt-out confirmation messages.

Sample Request

curl 'https://SERVER_NAME_GOES_HERE.punchh.com/hooks/smspartner/<business_key>/conversations/status' \
--header 'Content-Type: application/json' \
--header 'x-pch-digest: SIGNATURE_GOES_HERE' \
--data '{
  "client": "CLIENT_GOES_HERE",
  "phone": "1111111111",
  "email": "test@example.com",
  "sms_subscription": false,
  "user_type": "loyalty",
  "first_name": "John",
  "last_name": "Doe"
}'

Note: The inbound webhook only updates subscription status. It does not create a guest profile in Punchh. The guest must already exist in Punchh and be created through a standard sign-up process (for example, the Mobile Sign-up API or Online Ordering Create User API).

Error Handling