Receiving opt-out webhooks with the Volt GraphQL API

Volt Connect handles opt-out tracking automatically, ensuring that you never send a message to anyone who has previously unsubscribed from your messaging, and helping to keep you compliant with the Telephone Consumer Protection Act (TCPA). However, if you wish to track opt-outs within your system, it is possible to monitor for “STOP keywords” via Volt’s messaging webhooks.

To set up webhooks for your messaging, check out our guide: Receiving message webhooks with the Volt GraphQL API.

Instructions

Extracting the message body from a webhook

First, ensure that your system is set up to receive messaging webhooks. Here is an example message.received webhook:

{
  "type": "messaging",
  "id": "rfw_6962ccb5_80d23dc13c024d38873534471681379c",
  "payload": {
    "message_app_id": "c7fdc0ba-f3df-4e30-a7fc-397940a6f675",
    "id": null,
    "to_number": "+15555550123",
    "from_number": "+15555550145",
    "valid_until": null,
    "type": "SMS",
    "text": "Replying to message from handset",
    "sent_at": null,
    "received_at": "2022-04-07T22:21:04.259+00:00",
    "status": "webhook_delivered",
    "parts": 1,
    "messaging_profile_id": "40017bf5-8809-4640-9925-da5c732667b7",
    "media": [],
    "encoding": "GSM-7",
    "direction": "inbound",
    "completed_at": null,
    "occurred_at": "2022-04-07T22:21:04.397+00:00",
    "event_type": "message.received"
  },
  "time": 1649370064
}

Notice the payload object at the root level of the JSON object. This contains a key text, which includes the message body for any inbound messages.

Evaluating a message body for STOP keywords

A contact opts out whenever they message your phone number with a “STOP keyword.” The STOP keywords are messages which only contain the following terms (excluding punctuation and whitespace):

STOP
REMOVE
OPT OUT
UNSUBSCRIBE
CANCEL
QUIT

To evaluate whether a message has STOP keywords, follow these steps:

Strip all whitespace and punctuation from the message body. This ensures that messages which, for example, contain a STOP keyword followed by a single space are treated as if they only contained a STOP keyword, which is necessary for TCPA compliance.
Check if the cleaned, transformed message (i.e. possibly containing only a STOP keyword) is present in the list of STOP keywords.
If the cleaned, transformed message is present in the list of STOP keywords, the contact has opted out, and your system can now respond appropriately.